tryx 1.0.0

A powerful Dart library for functional, reliable, and expressive error handling using Result types. Provides type-safe error handling without exceptions, with support for async operations, streams, an [...]

Changelog

All notable changes to the Tryx package will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

1.0.0 - 2025-10-08

Added

Core Features

• Result<T, E> Type System: Type-safe error handling without exceptions
  • Success<T, E> and Failure<T, E> sealed classes
  • SafeResult<T> type alias for Result<T, Exception>
  • Comprehensive equality, hashCode, and toString implementations

Safe Execution Functions

• safe(): Wraps synchronous operations in Result types
• safeAsync(): Wraps asynchronous operations in Result types
• safeWith(): Custom error mapping for both sync and async operations

Functional Extensions

• Result Extensions: map(), flatMap(), mapError(), when(), fold()
• Side Effect Methods: onSuccess(), onFailure() for logging and monitoring
• Value Extraction: getOrElse(), getOrNull() for safe value access
• Error Recovery: recover(), recoverWith() for fallback handling
• Future Extensions: mapAsync(), flatMapAsync(), whenAsync() for async chaining

Stream Integration

• Stream Safe Extensions: safeStream(), safeMap(), safeAsyncMap(), safeExpand(), safeWhere()
• Stream Result Extensions: successes(), failures(), mapSuccesses(), flatMapSuccesses()
• Stream Processing: collectResults(), partition(), error recovery for streams
• Side Effects: onSuccesses(), onFailures() for stream monitoring

Advanced Error Recovery Patterns

• Circuit Breaker: Prevents cascading failures with configurable thresholds
  • CircuitBreaker class with open/closed/half-open states
  • CircuitBreakerConfig for customizable behavior
  • Automatic recovery and manual reset capabilities
• Fallback Chains: Sequential fallback strategies with FallbackChain<T, E>
• Adaptive Recovery: Learning-based retry with AdaptiveRecovery<T, E>
• Bulkhead Pattern: Resource isolation with Bulkhead<T, E>
• Recovery Orchestrator: Combines multiple recovery patterns

Configuration System

• Global Configuration: TryxConfig for library-wide settings
• Logging Integration: Configurable logging with custom loggers
• Performance Monitoring: Optional performance tracking and slow operation detection
• Configuration Presets: Pre-configured setups for development, production, testing, network, and database scenarios

Advanced Safe Execution

• Safe Class: Configurable safe execution with retry policies, timeouts, and logging
• Factory Constructors: Safe.network(), Safe.database(), Safe.critical() for common scenarios
• Retry Policies: Comprehensive retry system with exponential backoff, linear backoff, and custom delays
• Error Classification: ErrorClassifier for determining retry strategies

Utility Functions

• Result Combinators: combineResults(), combineResults2(), combineResults3()
• Error Collection: combineResultsCollectingErrors() for validation scenarios
• Type Conversions: fromNullable(), fromBool(), toNullable()
• Stream Operations: partitionResults(), traverse(), sequence()

Migration Support

• Migration Helpers: MigrationHelper class for transitioning from try-catch
• Migration Patterns: Common patterns for legacy code integration
• Bridge Functions: Convert between Result and exception-based code

Documentation & Examples

• Comprehensive API Documentation: Full dartdoc coverage for all public APIs
• Usage Examples: Practical examples in example/ directory
• Migration Guide: Step-by-step transition from traditional error handling
• Best Practices: Recommended patterns and usage guidelines

Technical Details

• Dart SDK: Requires Dart 3.0.0 or higher
• Dependencies: Minimal dependencies (only meta package)
• Null Safety: Full null safety support
• Performance: Zero-cost abstractions with compile-time optimizations
• Type Safety: Leverages Dart's type system for compile-time error detection

Package Structure

• Clean Architecture: Feature-based modular organization
• Comprehensive Testing: Full test coverage with unit, integration, and stream tests
• Production Ready: Optimized for pub.dev publication
• Documentation: Professional README, API docs, and examples