pi_result 0.2.0

Thin, typed, and observable Result aliases and error interoperability utilities
Documentation
//! `pi_result` 的基础结果与错误类型别名。
//!
//! 本模块定义库中最底层、最核心的一组类型别名。后续的边界转换、
//! attachment、检查、格式化与测试辅助模块都基于这些别名构建。
//!
//! # 类型关系
//!
//! - [`Result`]:默认的 report 型结果别名
//! - [`TypedResult`]:`Result<T, C>` 的语义别名
//! - [`RawResult`]:原生标准库 `Result` 别名,适用于轻量叶子错误
//! - [`ErrorReport`]:`error_stack::Report<C>` 的别名
//! - [`Error`]:默认公共错误对象,即 `Report<ErrorKind>`
//!
//! # 推荐使用方式
//!
//! 1. 叶子函数优先考虑 `RawResult<T, LocalError>`
//! 2. 需要在内部多层叠加上下文时使用 `Result<T, LocalContext>`
//! 3. 对外公开边界默认收敛为 `Result<T>`

use error_stack::Report;

use crate::kind::ErrorKind;

/// `error_stack::Report<C>` 的统一别名。
///
/// # 作用
///
/// - 提升项目内类型命名一致性
/// - 便于在公共 API 与测试中统一描述 report 类型
pub type ErrorReport<C> = Report<C>;

/// `pi_result` 默认的公共错误对象。
///
/// 等价于 `error_stack::Report<ErrorKind>`。
///
/// # 适用场景
///
/// - 公开模块 API
/// - 公开库 API
/// - App 层统一错误对象
pub type Error = ErrorReport<ErrorKind>;

/// `pi_result` 默认的 report 型结果别名。
///
/// 当不显式指定第二个泛型参数时,默认返回 `Report<ErrorKind>`。
///
/// # 示例
///
/// `Result<T>` 等价于:
///
/// ```text
/// core::result::Result<T, error_stack::Report<pi_result::ErrorKind>>
/// ```
///
/// `Result<T, C>` 等价于:
///
/// ```text
/// core::result::Result<T, error_stack::Report<C>>
/// ```
///
/// # 注意事项
///
/// 第二个泛型参数 `C` 表示 `Report<C>` 的上下文类型,而不是裸错误类型。
pub type Result<T, C = ErrorKind> = core::result::Result<T, ErrorReport<C>>;

/// `Result<T, C>` 的语义别名。
///
/// 本别名不增加新的能力,只用于在代码层强调:
/// 当前函数已经进入 typed report 传播链。
pub type TypedResult<T, C> = Result<T, C>;

/// 原生标准库 `Result<T, E>` 的统一别名。
///
/// # 适用场景
///
/// - 叶子函数
/// - 热路径
/// - 仅需 `thiserror + #[from]` 的局部逻辑
///
/// # 注意事项
///
/// `RawResult` 本身不携带 `Report` 的 frame 与 attachment。
/// 若需要进入统一可观测错误链,应在合适的边界显式转换为 `Result<T, C>` 或 `Result<T>`。
pub type RawResult<T, E> = core::result::Result<T, E>;

#[cfg(test)]
mod tests {
    use super::{Error, ErrorKind, ErrorReport, RawResult, Result, TypedResult};
    use error_stack::Report;
    use thiserror::Error;

    #[derive(Debug, Error)]
    #[error("local test context")]
    struct LocalContext;

    #[derive(Debug, Error, Clone, PartialEq, Eq)]
    #[error("local raw error")]
    struct LocalRawError;

    fn assert_send_sync<T: Send + Sync>() {}

    #[test]
    fn test_default_result_uses_public_error_kind() {
        let report = Report::new(ErrorKind::Internal);
        let value: Result<()> = Err(report);

        let error = value.expect_err("expected report");
        assert_eq!(error.current_context(), &ErrorKind::Internal);
    }

    #[test]
    fn test_typed_result_uses_custom_context_type() {
        let report = Report::new(LocalContext);
        let value: TypedResult<(), LocalContext> = Err(report);

        let error = value.expect_err("expected typed report");
        assert_eq!(error.current_context().to_string(), "local test context");
    }

    #[test]
    fn test_error_alias_equals_report_of_error_kind() {
        let error: Error = Report::new(ErrorKind::Dependency);
        let typed: ErrorReport<ErrorKind> = error;

        assert_eq!(typed.current_context(), &ErrorKind::Dependency);
    }

    #[test]
    fn test_raw_result_preserves_std_result_behavior() {
        let value: RawResult<u32, LocalRawError> = Err(LocalRawError);
        let cloned = value.clone();

        assert_eq!(value, cloned);
        assert_eq!(value.expect_err("expected raw error"), LocalRawError);
    }

    #[test]
    fn test_public_error_is_send_and_sync() {
        assert_send_sync::<Error>();
        assert_send_sync::<ErrorReport<ErrorKind>>();
    }

    #[test]
    fn test_result_alias_keeps_report_debug_and_display_support() {
        let error: Error = Report::new(ErrorKind::Timeout);

        let display = format!("{error}");
        let alternate = format!("{error:#}");
        let debug = format!("{error:?}");

        assert_eq!(display, "timeout");
        assert!(alternate.contains("timeout"));
        assert!(debug.contains("timeout"));
    }
}