yoshi-std

Core error handling framework with enterprise-grade performance and developer experience optimization.

~=####====A===r===c===M===o===o===n====S===t===u===d===i===o===s====X|0|$>

• Enterprise Error Handling Framework [Performance-Critical]
• Zero-cost error creation with O(1) context attachment
• Type-safe error categorization with compile-time verification
• Advanced context management with structured data preservation
• High-performance error chain analysis with lazy evaluation
• Memory-efficient error storage with inline optimization
• Comprehensive serialization support with format flexibility

~=####====A===r===c===M===o===o===n====S===t===u===d===i===o===s====X|0|$>

GitHub: ArcMoon Studios Copyright: (c) 2025 ArcMoon Studios Author: Lord Xyn License: Business Source License 1.1 (BSL-1.1) License Terms: Non-production use only; commercial/production use requires paid license. Effective Date: 2025-05-25 | Change License: GPL v3 Contact: LordXyn@proton.me

Overview

yoshi-std is the foundational crate of the Yoshi error handling framework, providing enterprise-grade error management with sub-microsecond performance characteristics. Built for mission-critical systems requiring both exceptional performance and comprehensive error context preservation.

Key Features

• 🚀 Zero-Cost Abstractions: Error creation and context attachment with minimal runtime overhead
• 🎯 Type-Safe Categories: Compile-time verified error classification with YoshiKind
• 📊 Rich Context System: Structured error context with arbitrary data attachment
• 🔗 Advanced Chaining: Sophisticated error chain analysis and traversal
• 📱 Universal Serialization: JSON, CBOR, MessagePack, and custom format support
• 🧪 Testing Integration: Comprehensive error testing utilities and patterns
• ⚡ Performance Optimized: Sub-microsecond error operations with memory efficiency

Installation

Add to your Cargo.toml:

[dependencies]
yoshi-std = "0.1.0"

# Optional features
yoshi-std = { version = "0.1.0", features = ["serde", "tracing"] }

Quick Start

Basic Error Creation

use yoshi_std::{Yoshi, YoshiKind};

// Simple error creation
let error = Yoshi::new(YoshiKind::NotFound, "User not found");

// With context
let error = Yoshi::new(YoshiKind::Validation, "Invalid email format")
    .with_context("email", "invalid@domain")
    .with_context("field", "user_email");

// From std::error::Error
let io_error = std::fs::read("missing.txt").unwrap_err();
let yoshi_error = Yoshi::from_error(YoshiKind::Io, io_error);

Error Categories

use yoshi_std::YoshiKind;

match error.kind() {
    YoshiKind::Io => println!("I/O operation failed"),
    YoshiKind::Network => println!("Network communication error"),
    YoshiKind::Validation => println!("Input validation failed"),
    YoshiKind::NotFound => println!("Resource not found"),
    YoshiKind::Timeout => println!("Operation timed out"),
    YoshiKind::Config => println!("Configuration error"),
    YoshiKind::ResourceExhausted => println!("Resource limit exceeded"),
    YoshiKind::Internal => println!("Internal system error"),
}

Context Management

use yoshi_std::{Yoshi, YoContext};

let mut error = Yoshi::new(YoshiKind::Database, "Connection failed");

// Add structured context
error = error
    .with_context("host", "db.example.com")
    .with_context("port", 5432)
    .with_context("database", "production")
    .with_context("retry_count", 3);

// Access context
if let Some(host) = error.context().get("host") {
    println!("Failed to connect to: {}", host);
}

// Iterate through all context
for (key, value) in error.context().iter() {
    println!("{}: {}", key, value);
}

Core Types Reference

Yoshi

The primary error type providing comprehensive error handling capabilities.

YoshiKind

Error categorization enum for type-safe error classification.

YoContext

Structured context data container for error enrichment.

Advanced Usage

Error Chaining

use yoshi_std::{Yoshi, YoshiKind};

fn process_file(path: &str) -> Result<String, Yoshi> {
    std::fs::read_to_string(path)
        .map_err(|e| Yoshi::from_error(YoshiKind::Io, e)
            .with_context("operation", "read_file")
            .with_context("path", path))
}

fn parse_config(content: &str) -> Result<Config, Yoshi> {
    serde_json::from_str(content)
        .map_err(|e| Yoshi::from_error(YoshiKind::Config, e)
            .with_context("operation", "parse_json")
            .with_context("format", "JSON"))
}

fn load_configuration(path: &str) -> Result<Config, Yoshi> {
    let content = process_file(path)
        .map_err(|e| e.with_context("stage", "file_reading"))?;

    parse_config(&content)
        .map_err(|e| e.with_context("stage", "configuration_parsing"))
}

// Error chain analysis
match load_configuration("config.json") {
    Ok(config) => println!("Loaded: {:?}", config),
    Err(error) => {
        println!("Configuration loading failed:");
        for (depth, err) in error.chain().enumerate() {
            println!("  {}: {}", depth, err);
        }

        // Access root cause
        if let Some(root_cause) = error.root_cause() {
            println!("Root cause: {}", root_cause);
        }
    }
}

Async Integration

use yoshi_std::{Yoshi, YoshiKind};
use tokio::time::{timeout, Duration};

async fn fetch_data(url: &str) -> Result<String, Yoshi> {
    let client = reqwest::Client::new();

    let response = timeout(Duration::from_secs(30), client.get(url).send())
        .await
        .map_err(|_| Yoshi::new(YoshiKind::Timeout, "Request timed out")
            .with_context("url", url)
            .with_context("timeout_ms", "30000"))?
        .map_err(|e| Yoshi::from_error(YoshiKind::Network, e)
            .with_context("url", url)
            .with_context("operation", "http_request"))?;

    if !response.status().is_success() {
        return Err(Yoshi::new(YoshiKind::Network, "HTTP error")
            .with_context("status_code", response.status().as_u16())
            .with_context("url", url));
    }

    response.text()
        .await
        .map_err(|e| Yoshi::from_error(YoshiKind::Network, e)
            .with_context("operation", "response_body_read")
            .with_context("url", url))
}

Custom Error Recovery

use yoshi_std::{Yoshi, YoshiKind};

struct RetryConfig {
    max_attempts: usize,
    base_delay_ms: u64,
    max_delay_ms: u64,
}

impl Default for RetryConfig {
    fn default() -> Self {
        Self {
            max_attempts: 3,
            base_delay_ms: 100,
            max_delay_ms: 5000,
        }
    }
}

async fn retry_operation<F, T, Fut>(
    mut operation: F,
    config: RetryConfig,
) -> Result<T, Yoshi>
where
    F: FnMut() -> Fut,
    Fut: std::future::Future<Output = Result<T, Yoshi>>,
{
    let mut last_error = None;
    let mut delay = config.base_delay_ms;

    for attempt in 1..=config.max_attempts {
        match operation().await {
            Ok(result) => return Ok(result),
            Err(error) => {
                last_error = Some(error.with_context("attempt", attempt));

                if attempt < config.max_attempts {
                    tokio::time::sleep(Duration::from_millis(delay)).await;
                    delay = (delay * 2).min(config.max_delay_ms);
                }
            }
        }
    }

    Err(last_error.unwrap()
        .with_context("max_attempts", config.max_attempts)
        .with_context("operation", "retry_exhausted"))
}

Error Aggregation

use yoshi_std::{Yoshi, YoshiKind};

struct ErrorAggregator {
    errors: Vec<Yoshi>,
}

impl ErrorAggregator {
    fn new() -> Self {
        Self { errors: Vec::new() }
    }

    fn add_error(&mut self, error: Yoshi) {
        self.errors.push(error);
    }

    fn has_errors(&self) -> bool {
        !self.errors.is_empty()
    }

    fn into_result<T>(self, success_value: T) -> Result<T, Yoshi> {
        if self.errors.is_empty() {
            Ok(success_value)
        } else {
            let mut combined = Yoshi::new(
                YoshiKind::Internal,
                format!("Multiple errors occurred ({} total)", self.errors.len())
            );

            for (index, error) in self.errors.into_iter().enumerate() {
                combined = combined.with_context(
                    format!("error_{}", index),
                    error.to_string()
                );
            }

            Err(combined)
        }
    }
}

// Usage example
fn validate_batch_data(items: &[DataItem]) -> Result<(), Yoshi> {
    let mut aggregator = ErrorAggregator::new();

    for (index, item) in items.iter().enumerate() {
        if let Err(error) = validate_item(item) {
            aggregator.add_error(
                error.with_context("item_index", index)
                     .with_context("batch_validation", true)
            );
        }
    }

    aggregator.into_result(())
}

Serialization Support

JSON Serialization

use yoshi_std::{Yoshi, YoshiKind};
use serde_json;

#[cfg(feature = "serde")]
fn serialize_error() -> Result<(), Box<dyn std::error::Error>> {
    let error = Yoshi::new(YoshiKind::Validation, "Invalid input")
        .with_context("field", "email")
        .with_context("value", "invalid@domain")
        .with_context("rule", "email_format");

    // Serialize to JSON
    let json = serde_json::to_string_pretty(&error)?;
    println!("Serialized error:\n{}", json);

    // Deserialize from JSON
    let deserialized: Yoshi = serde_json::from_str(&json)?;
    assert_eq!(error.kind(), deserialized.kind());
    assert_eq!(error.message(), deserialized.message());

    Ok(())
}

Tracing Integration

use yoshi_std::{Yoshi, YoshiKind};
use tracing::{error, warn, info};

#[cfg(feature = "tracing")]
fn log_error_with_tracing(error: &Yoshi) {
    match error.kind() {
        YoshiKind::Internal => {
            error!(
                error = %error,
                kind = ?error.kind(),
                context = ?error.context(),
                "Critical internal error occurred"
            );
        }
        YoshiKind::Network | YoshiKind::Timeout => {
            warn!(
                error = %error,
                kind = ?error.kind(),
                context = ?error.context(),
                "Network operation failed"
            );
        }
        _ => {
            info!(
                error = %error,
                kind = ?error.kind(),
                context = ?error.context(),
                "Operation completed with error"
            );
        }
    }
}

Performance Characteristics

Performance Tier: Enterprise-Ready (Level 2 of 3) Level 3 = All edge case optimizations complete

Based on comprehensive benchmarking, yoshi-std delivers exceptional performance for high-complexity edge case behavior:

Error Creation Performance

Memory Efficiency

Comparison with Alternatives

Testing Utilities

Error Testing Patterns

#[cfg(test)]
mod tests {
    use yoshi_std::{Yoshi, YoshiKind};

    #[test]
    fn test_error_creation() {
        let error = Yoshi::new(YoshiKind::Validation, "Test error");

        assert_eq!(error.kind(), &YoshiKind::Validation);
        assert_eq!(error.message(), "Test error");
        assert!(error.context().is_empty());
    }

    #[test]
    fn test_error_context() {
        let error = Yoshi::new(YoshiKind::Config, "Configuration error")
            .with_context("file", "config.toml")
            .with_context("line", "42");

        assert_eq!(error.context().get("file"), Some("config.toml"));
        assert_eq!(error.context().get("line"), Some("42"));
        assert_eq!(error.context().len(), 2);
    }

    #[test]
    fn test_error_chaining() {
        let io_error = std::io::Error::new(
            std::io::ErrorKind::NotFound,
            "File not found"
        );

        let base_error = Yoshi::from_error(YoshiKind::Io, io_error)
            .with_context("path", "/etc/config");

        let wrapper_error = Yoshi::new(YoshiKind::Config, "Failed to load config")
            .with_source(base_error);

        let chain: Vec<_> = wrapper_error.chain().collect();
        assert_eq!(chain.len(), 3); // wrapper + base + io_error
    }

    // Property-based testing with arbitrary errors
    #[cfg(feature = "proptest")]
    use proptest::prelude::*;

    #[cfg(feature = "proptest")]
    proptest! {
        #[test]
        fn test_error_roundtrip_serialization(
            message in "\\PC*",
            contexts in prop::collection::vec(
                (prop::string::string_regex("[a-zA-Z_][a-zA-Z0-9_]*").unwrap(), "\\PC*"),
                0..10
            )
        ) {
            let mut error = Yoshi::new(YoshiKind::Validation, message.clone());

            for (key, value) in contexts.iter() {
                error = error.with_context(key, value);
            }

            #[cfg(feature = "serde")]
            {
                let serialized = serde_json::to_string(&error).unwrap();
                let deserialized: Yoshi = serde_json::from_str(&serialized).unwrap();

                prop_assert_eq!(error.kind(), deserialized.kind());
                prop_assert_eq!(error.message(), deserialized.message());
                prop_assert_eq!(error.context().len(), deserialized.context().len());
            }
        }
    }
}

Feature Flags

Configure yoshi-std with optional features:

[dependencies]
yoshi-std = { version = "0.1.0", features = ["serde", "tracing"] }

Available Features

Core Features (Always Enabled)

• Error creation and chaining
• Context management
• Type-safe error categories
• std::error::Error implementation
• Display and Debug formatting

Experimental Features

Experimental features are available under --cfg experimental:

#[cfg(experimental)]
use yoshi_std::experimental::{ErrorMetrics, ErrorRecovery};

Migration Guide

From anyhow

// Before (anyhow)
use anyhow::{Result, Context, bail};

fn old_function() -> Result<String> {
    let content = std::fs::read_to_string("file.txt")
        .context("Failed to read file")?;

    if content.is_empty() {
        bail!("File is empty");
    }

    Ok(content)
}

// After (yoshi-std)
use yoshi_std::{Yoshi, YoshiKind};

fn new_function() -> Result<String, Yoshi> {
    let content = std::fs::read_to_string("file.txt")
        .map_err(|e| Yoshi::from_error(YoshiKind::Io, e)
            .with_context("operation", "read_file")
            .with_context("path", "file.txt"))?;

    if content.is_empty() {
        return Err(Yoshi::new(YoshiKind::Validation, "File is empty")
            .with_context("path", "file.txt")
            .with_context("size", "0"));
    }

    Ok(content)
}

From thiserror

// Before (thiserror)
use thiserror::Error;

#[derive(Error, Debug)]
pub enum AppError {
    #[error("I/O error")]
    Io(#[from] std::io::Error),

    #[error("Validation failed: {message}")]
    Validation { message: String },
}

// After (yoshi-std)
use yoshi_std::{Yoshi, YoshiKind};

type AppError = Yoshi;

fn create_io_error(io_err: std::io::Error) -> AppError {
    Yoshi::from_error(YoshiKind::Io, io_err)
}

fn create_validation_error(message: &str) -> AppError {
    Yoshi::new(YoshiKind::Validation, message)
}

Best Practices

Error Context Guidelines

1. Add Operation Context: Always include the operation being performed
2. Include Relevant Data: Add key identifiers and parameters
3. Use Structured Keys: Consistent naming for context keys
4. Avoid Sensitive Data: Don't include passwords or tokens in context

// Good: Structured context with relevant information
let error = Yoshi::new(YoshiKind::Database, "Connection failed")
    .with_context("operation", "user_lookup")
    .with_context("user_id", user_id)
    .with_context("table", "users")
    .with_context("retry_count", attempts);

// Avoid: Unstructured or missing context
let error = Yoshi::new(YoshiKind::Database, "Something went wrong");

Performance Optimization

1. Reuse Error Instances: Clone errors instead of recreating
2. Minimize Context: Only add essential context information
3. Lazy Evaluation: Use closures for expensive context computation
4. Error Pooling: Consider object pools for high-frequency errors

// Efficient error reuse
static CONFIG_ERROR: Lazy<Yoshi> = Lazy::new(|| {
    Yoshi::new(YoshiKind::Config, "Configuration validation failed")
});

fn validate_config(config: &Config) -> Result<(), Yoshi> {
    if config.is_invalid() {
        return Err(CONFIG_ERROR.clone()
            .with_context("config_version", config.version())
            .with_context("validation_time", SystemTime::now()));
    }
    Ok(())
}

Enterprise Integration

Monitoring and Observability

use yoshi_std::{Yoshi, YoshiKind};
use tracing::{error, instrument};
use metrics::{counter, histogram};

#[instrument(skip(operation))]
async fn monitored_operation<F, T>(
    operation_name: &str,
    operation: F,
) -> Result<T, Yoshi>
where
    F: Future<Output = Result<T, Yoshi>>,
{
    let start = std::time::Instant::now();

    match operation.await {
        Ok(result) => {
            histogram!("operation_duration", start.elapsed())
                .with_tag("operation", operation_name)
                .with_tag("status", "success");

            Ok(result)
        }
        Err(error) => {
            counter!("operation_errors")
                .with_tag("operation", operation_name)
                .with_tag("error_kind", format!("{:?}", error.kind()))
                .increment(1);

            histogram!("operation_duration", start.elapsed())
                .with_tag("operation", operation_name)
                .with_tag("status", "error");

            error!(
                error = %error,
                operation = operation_name,
                duration_ms = start.elapsed().as_millis(),
                "Operation failed"
            );

            Err(error.with_context("operation", operation_name)
                     .with_context("duration_ms", start.elapsed().as_millis()))
        }
    }
}

Health Check Integration

use yoshi_std::{Yoshi, YoshiKind};
use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize)]
pub struct HealthStatus {
    pub status: String,
    pub checks: Vec<HealthCheck>,
    pub last_error: Option<Yoshi>,
}

#[derive(Serialize, Deserialize)]
pub struct HealthCheck {
    pub name: String,
    pub status: String,
    pub duration_ms: u64,
    pub error: Option<Yoshi>,
}

impl HealthStatus {
    pub fn healthy() -> Self {
        Self {
            status: "healthy".to_string(),
            checks: Vec::new(),
            last_error: None,
        }
    }

    pub fn add_check(&mut self, check: HealthCheck) {
        if check.error.is_some() && self.status == "healthy" {
            self.status = "degraded".to_string();
        }
        self.checks.push(check);
    }

    pub fn with_error(mut self, error: Yoshi) -> Self {
        self.status = "unhealthy".to_string();
        self.last_error = Some(error);
        self
    }
}

Contributing

We welcome contributions to yoshi-std! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/arcmoonstudios/yoshi.git
cd yoshi/yoshi-std

# Install development dependencies
cargo install --locked cargo-nextest
cargo install --locked cargo-criterion

# Run tests
cargo nextest run
cargo test --doc

# Run benchmarks
cargo criterion

# Check code quality
cargo clippy --all-targets --all-features
cargo fmt --check

Performance Testing

# Run performance benchmarks
cargo bench

# Profile with flamegraph
cargo install flamegraph
cargo flamegraph --bench error_creation

# Memory profiling
cargo install dhat
cargo run --features dhat-heap --bin memory_profile

License

This project is licensed under the Business Source License 1.1 (BSL-1.1).

License Summary

• Development and Testing: Free for non-production use
• Production Use: Requires a commercial license
• License Change: Converts to GPL v3 on 2025-05-25
• Commercial Licensing: Contact LordXyn@proton.me

See the LICENSE file for full terms and conditions.

ArcMoon Studios - Where precision meets innovation in enterprise error handling.