tryo 0.9.4 → 0.13.3

package/dist/index.d.ts

@@ -1,321 +1,448 @@
-import { MaybePromise as MaybePromise$1 } from 'bun';
-
-type AppErrorCode = "ABORTED" | "NETWORK" | "TIMEOUT" | "VALIDATION" | "HTTP" | "UNKNOWN";
 /**
- * A normalized error shape returned by `run()`.
- *
- * - `code`: A stable identifier you can switch on (e.g. "HTTP", "VALIDATION").
- * - `message`: User-facing or log-friendly message.
- * - `status`: Optional numeric status (commonly HTTP status).
- * - `meta`: Optional payload with extra context (response body, validation fields, etc.).
- * - `cause`: The original thrown value for debugging.
+ * Branded types for enhanced type safety and runtime validation
+ * These provide compile-time guarantees while maintaining runtime checks
  */
-type AppError<Code extends string = AppErrorCode | (string & {}), Meta = unknown> = {
-    code: Code;
-    message: string;
-    status?: number;
-    meta?: Meta;
-    cause?: unknown;
+type Milliseconds = number & {
+    readonly __brand: 'Milliseconds';
 };
-type NonNull<T> = T extends null ? never : T;
-type RuleReturn<R> = R extends (err: unknown) => infer Out ? NonNull<Out> : never;
-type InferErrorFromRules<TRules extends readonly Rule<any>[]> = TRules extends readonly [] ? AppError : RuleReturn<TRules[number]> | AppError<"UNKNOWN">;
-type Rule<E extends AppError = AppError> = (err: unknown) => E | null;
-
-type RetryDelayFn<E> = (attempt: number, err: E) => number;
-type MaybePromise<T> = T | Promise<T>;
-type Jitter = boolean | number | {
-    ratio?: number;
-    mode?: "full" | "equal";
-    rng?: () => number;
-};
-/**
- * Backoff strategy to calculate the delay between retries.
- * - "linear": uses the base delay as is in each attempt.
- * - "exponential": multiplies the delay by 2^(attempt-1).
- * - "fibonacci": multiplies by F(attempt) (classic Fibonacci sequence).
- * - function: custom function based on the attempt number.
- */
-type BackoffStrategy = "linear" | "exponential" | "fibonacci" | ((attempt: number) => number);
-/**
- * Retry options for `run`, `runAll` and `runAllOrThrow`.
- */
-type RetryOptions<E extends AppError = AppError> = {
-    /**
-     * Number of retries to perform (does not include the initial attempt).
-     * @default 0
-     */
-    retries?: number;
-    /**
-     * Delay between attempts:
-     * - number: fixed delay (ms)
-     * - () => number: lazy delay (evaluated per attempt)
-     * - (attempt, err) => number: delay based on attempt and last error
-     * @default 0 or a default baseDelay if retries are present
-     */
-    retryDelay?: number | (() => number) | RetryDelayFn<E>;
-    /**
-     * Decides whether to retry given a specific error.
-     * Can be synchronous or asynchronous.
-     * Receives the next attempt number and a context with accumulated metrics.
-     * @default () => true
-     */
-    shouldRetry?: (attempt: number, error: E, context: RetryContext) => boolean | Promise<boolean>;
-    /**
-     * Random jitter to avoid thundering herd:
-     * - true: default ratio 0.5
-     * - false: no jitter
-     * - number: ratio 0..1
-     * - object: full control (ratio, mode, rng)
-     * @default 0.5
-     */
-    jitter?: Jitter;
-    /**
-     * Backoff strategy to apply on the calculated delay.
-     * @default "linear"
-     */
-    backoffStrategy?: BackoffStrategy;
-    /**
-     * Upper limit of the delay after backoff and before jitter.
-     * @default undefined (no limit)
-     */
-    maxDelay?: number;
-};
-/**
- * Context for `shouldRetry` with accumulated metrics of the current attempt.
- */
-type RetryContext = {
-    /** Total attempts (including the next retry). */
-    totalAttempts: number;
-    /** Elapsed time in ms since the start of `run`. */
-    elapsedTime: number;
+type RetryCount = number & {
+    readonly __brand: 'RetryCount';
 };
+declare const asMilliseconds: (n: number) => Milliseconds;
+declare const asRetryCount: (n: number) => RetryCount;
+
 /**
- * Main options for `run` and extended to `runAll`/`runAllOrThrow`.
+ * Modern typed error hierarchy with enhanced capabilities
+ * Provides type-safe error handling with fluent API and metadata support
  */
-type RunOptions<T, E extends AppError = AppError> = RetryOptions<E> & {
-    /**
-     * Normalizes an unknown error value to your type `E`.
-     * If not provided, a default normalizer is used.
-     */
-    toError?: (err: unknown) => E;
-    /**
-     * Optional transformation applied after `toError`.
-     * Useful for adjusting messages, codes, or adding metadata.
-     */
-    mapError?: (error: E) => E;
-    /**
-     * Callback on failure (not called if `ignoreAbort` and error is ABORTED).
-     */
-    onError?: (error: E) => void;
-    /**
-     * Callback on success.
-     */
-    onSuccess?: (data: T) => void;
-    /**
-     * Callback that always executes at the end (success or error).
-     */
-    onFinally?: () => void;
-    /**
-     * If true, aborts (ABORTED) are not considered fatal errors:
-     * `onError` is not called and `{ ok: false, error }` is returned.
-     * @default true
-     */
-    ignoreAbort?: boolean;
-    /**
-     * Signal for native work cancellation.
-     * If aborted, it cuts with `AbortError`.
-     */
-    signal?: AbortSignal;
-    /**
-     * Maximum timeout in ms for the work; expires with `TimeoutError`.
-     */
-    timeout?: number;
-    /**
-     * Retry observability: receives attempt, error, and next delay.
-     */
-    onRetry?: (attempt: number, error: E, nextDelay: number) => void;
-    /**
-     * Optional structured logger for debug and errors.
-     */
-    logger?: {
-        debug?: (msg: string, meta?: any) => void;
-        error?: (msg: string, error: E) => void;
+
+declare abstract class TypedError<Code extends string = string, Meta extends Record<string, unknown> = Record<string, unknown>, Raw = unknown> extends Error {
+    abstract readonly code: Code;
+    readonly cause?: unknown;
+    readonly meta: Meta;
+    readonly status?: number;
+    readonly raw: Raw;
+    readonly path?: string;
+    readonly timestamp: number;
+    readonly retryable: boolean;
+    constructor(message: string, opts: {
+        cause?: unknown;
+        meta?: Meta;
+        status?: number;
+        retryable?: boolean;
+        raw: Raw;
+        path?: string;
+    });
+    is<C extends string>(code: C): this is TypedError<C> & {
+        code: C;
+    };
+    withMeta<const M>(meta: M): this & {
+        meta: M;
+    };
+    withStatus(status: number): this & {
+        status: number;
+    };
+    withCause(cause: unknown): this & {
+        cause: unknown;
+    };
+    withPath(path: string): this;
+    withRaw<const R>(raw: R): this & {
+        raw: R;
     };
-    /**
-     * Callback on abort, useful for reacting to `AbortSignal`.
-     */
-    onAbort?: (signal: AbortSignal) => void;
-    /**
-     * Per-call circuit breaker configuration.
-     * If not defined, can use the default value from `Runner`.
-     */
-    circuitBreaker?: CircuitBreakerOptions;
+    withRetryable(retryable: boolean): this;
+    toJSON(): Record<string, unknown>;
+}
+type AnyTypedError = TypedError<string, any, unknown>;
+declare class TimeoutError extends TypedError<'TIMEOUT', Record<string, unknown>, unknown> {
+    readonly code: "TIMEOUT";
+    constructor(timeout: Milliseconds, cause?: unknown);
+}
+declare class AbortedError extends TypedError<'ABORTED', Record<string, unknown>, unknown> {
+    readonly code: "ABORTED";
+    constructor(reason?: string, cause?: unknown);
+}
+declare class CircuitOpenError extends TypedError<'CIRCUIT_OPEN', Record<string, unknown>, unknown> {
+    readonly code: "CIRCUIT_OPEN";
+    constructor(resetAfter: Milliseconds, cause?: unknown);
+}
+type ValidationMeta = Record<string, unknown> & {
+    validationErrors: unknown[];
 };
-/**
- * Circuit breaker configuration options:
- * - failureThreshold: number of consecutive failures to open the circuit
- * - resetTimeout: time in ms it remains open before attempting half-open
- * - halfOpenRequests: allowed quantity in half-open state
- */
-type CircuitBreakerOptions = {
-    failureThreshold: number;
-    resetTimeout: number;
-    halfOpenRequests?: number;
+declare class ValidationError extends TypedError<'VALIDATION', ValidationMeta, unknown> {
+    readonly validationErrors: unknown[];
+    readonly code: "VALIDATION";
+    constructor(message: string, validationErrors: unknown[], cause?: unknown);
+}
+declare class NetworkError extends TypedError<'NETWORK', Record<string, unknown>, unknown> {
+    readonly statusCode?: number | undefined;
+    readonly code: "NETWORK";
+    constructor(message: string, statusCode?: number | undefined, cause?: unknown);
+}
+type HttpMeta = Record<string, unknown> & {
+    response?: unknown;
 };
+declare class HttpError extends TypedError<'HTTP', HttpMeta, unknown> {
+    readonly status: number;
+    readonly response?: unknown | undefined;
+    readonly code: "HTTP";
+    constructor(message: string, status: number, response?: unknown | undefined, cause?: unknown);
+}
+declare class UnknownError extends TypedError<'UNKNOWN', Record<string, unknown>, unknown> {
+    readonly code: "UNKNOWN";
+    constructor(message: string, cause?: unknown);
+}
+
 /**
- * Execution metrics optionally returned in `RunResult`.
+ * Modern result types with enhanced discriminated unions
+ * Provides better type safety and more granular result categorization
  */
-type Metrics = {
-    totalAttempts: number;
-    totalRetries: number;
-    totalDuration: number;
-    lastError?: AppError;
-};
-type RunResult<T, E extends AppError = AppError> = {
-    ok: true;
-    data: T;
-    error: null;
-    metrics?: Metrics;
-} | {
-    ok: false;
-    data: null;
-    error: E;
-    metrics?: Metrics;
-};
+
+type TryoResult<T, E extends AnyTypedError = AnyTypedError> = SuccessResult<T, E> | FailureResult<E> | AbortedResult<E> | TimeoutResult<E>;
+interface SuccessResult<T, E extends AnyTypedError> {
+    readonly type: 'success';
+    readonly ok: true;
+    readonly data: T;
+    readonly error: null;
+    readonly metrics: TryoMetrics$1<E>;
+}
+interface FailureResult<E extends AnyTypedError> {
+    readonly type: 'failure';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics: TryoMetrics$1<E>;
+}
+interface AbortedResult<E extends AnyTypedError> {
+    readonly type: 'aborted';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics: TryoMetrics$1<E>;
+}
+interface TimeoutResult<E extends AnyTypedError> {
+    readonly type: 'timeout';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics: TryoMetrics$1<E>;
+}
+interface TryoMetrics$1<E extends AnyTypedError> {
+    readonly totalAttempts: RetryCount;
+    readonly totalRetries: RetryCount;
+    readonly totalDuration: Milliseconds;
+    readonly lastError?: E;
+    readonly retryHistory: Array<{
+        readonly attempt: RetryCount;
+        readonly error: E;
+        readonly delay: Milliseconds;
+        readonly timestamp: Date;
+    }>;
+}
 
 /**
- * Executes an async operation and returns a Result instead of throwing.
- *
- * Errors are normalized into an `AppError` (or a custom error type `E`)
- * using the provided `toError` function.
- *
- * This utility is framework-agnostic and works in browsers, Node.js,
- * React effects, and any async context.
+ * Modern circuit breaker implementation with enhanced state management
+ * Provides circuit breaker pattern with type safety and observability
  */
-declare function run<T, E extends AppError = AppError>(fn: () => MaybePromise<T>, options?: RunOptions<T, E>): Promise<RunResult<T, E>>;
+
+interface CircuitBreakerConfig<E extends AnyTypedError = AnyTypedError> {
+    /** Number of consecutive failures before opening circuit */
+    readonly failureThreshold: number;
+    /** How long to wait before attempting to close circuit */
+    readonly resetTimeout: number;
+    /** Number of requests allowed in half-open state */
+    readonly halfOpenRequests: number;
+    /** Optional function to determine if error should count as failure */
+    readonly shouldCountAsFailure?: (error: E) => boolean;
+}
+type CircuitState = 'closed' | 'open' | 'half-open';
 
 /**
- * Discriminated result per item in `runAllSettled`:
- * - "ok": successful task with `data`
- * - "error": failed task with `error`
- * - "skipped": task not executed due to cancellation/fail-fast/concurrency
+ * Modern error normalization system
+ * Provides type-safe error transformation and normalization
  */
-type RunAllItemResult<T, E extends AppError = AppError> = {
-    status: "ok";
-    ok: true;
-    data: T;
-    error: null;
-} | {
-    status: "error";
-    ok: false;
-    data: null;
-    error: E;
-} | {
-    status: "skipped";
-    ok: false;
-    data: null;
-    error: null;
-};
-/** Helper to discriminate successful results. */
-type SuccessResult<T> = Extract<RunAllItemResult<T, any>, {
-    status: "ok";
-}>;
-/** Helper to discriminate error results. */
-type ErrorResult<E> = Extract<RunAllItemResult<any, E extends AppError ? E : AppError>, {
-    status: "error";
-}>;
-/** Type guard that detects `status: "ok"` with `data` typing. */
-declare const isSuccess: <T, E extends AppError = AppError>(r: RunAllItemResult<T, E>) => r is SuccessResult<T>;
-type RunAllOptions<T, E extends AppError = AppError> = RunOptions<T, E> & {
-    /**
-     * Maximum number of concurrent tasks to run.
-     * @default Infinity
-     */
-    concurrency?: number;
-    /**
-     * Execution mode regarding errors.
-     * - "settle": Run all tasks (default).
-     * - "fail-fast": Stop starting new tasks if one fails.
-     * @default "settle"
-     */
-    mode?: "settle" | "fail-fast";
-};
-declare function runAllSettled<T, E extends AppError = AppError>(tasks: Array<() => MaybePromise<T>>, options?: RunAllOptions<T, E>): Promise<RunAllItemResult<T, E>[]>;
+
+type ErrorNormalizer<E extends AnyTypedError = AnyTypedError> = (error: unknown) => E;
+type ErrorRule<E extends AnyTypedError = AnyTypedError> = (error: unknown) => E | null;
 
 /**
- * Options for `runAll`:
- * - Inherits all options from `RunOptions`
- * - `concurrency`: limit of simultaneous tasks; if one fails, it throws
+ * Modern retry strategies with enhanced capabilities
+ * Provides various retry patterns with type safety
  */
-type RunAllOrThrowOptions<T, E extends AppError = AppError> = RunOptions<T, E> & {
-    /**
-     * Maximum number of concurrent tasks to run.
-     * @default Infinity
-     */
-    concurrency?: number;
-};
-declare function runAll<T, E extends AppError = AppError>(tasks: Array<() => MaybePromise$1<T>>, options?: RunAllOrThrowOptions<T, E>): Promise<T[]>;
 
-declare function createNormalizer<E extends AppError>(rules: Rule<E>[], fallback: (err: unknown) => E): (err: unknown) => E;
-declare function defaultFallback(err: unknown): AppError;
-declare function toAppError(err: unknown): AppError;
-
-declare const rules: {
-    abort: Rule<AppError<"ABORTED">>;
-    timeout: Rule<AppError<"TIMEOUT">>;
-    httpStatus: Rule<AppError<"HTTP">>;
-    aggregate: Rule<AppError<"UNKNOWN", {
-        errors: unknown[];
-    }>>;
-    string: Rule<AppError<"UNKNOWN">>;
-    message: Rule<AppError<"UNKNOWN">>;
+type RetryStrategy = FixedDelayStrategy | ExponentialBackoffStrategy | FibonacciBackoffStrategy | CustomDelayStrategy;
+interface FixedDelayStrategy {
+    readonly type: 'fixed';
+    readonly delay: number;
+}
+interface ExponentialBackoffStrategy {
+    readonly type: 'exponential';
+    readonly base: number;
+    readonly factor: number;
+    readonly maxDelay?: number;
+}
+interface FibonacciBackoffStrategy {
+    readonly type: 'fibonacci';
+    readonly base: number;
+    readonly maxDelay?: number;
+}
+interface CustomDelayStrategy {
+    readonly type: 'custom';
+    readonly calculate: (attempt: RetryCount, error: unknown) => number;
+}
+declare const RetryStrategies: {
+    readonly fixed: (delay: number) => FixedDelayStrategy;
+    readonly exponential: (base: number, factor?: number, maxDelay?: number) => ExponentialBackoffStrategy;
+    readonly fibonacci: (base: number, maxDelay?: number) => FibonacciBackoffStrategy;
+    readonly custom: (calculate: (attempt: RetryCount, error: unknown) => number) => CustomDelayStrategy;
 };
 
-declare class ErrorRuleBuilder<E> {
-    private readonly matcher;
-    constructor(matcher: (err: unknown) => err is E);
-    toError<const Out extends AppError>(mapper: (err: E) => Out): Rule<Out>;
+interface TryoConfig<E extends AnyTypedError = AnyTypedError> {
+    /** Abort signal passed to tasks */
+    readonly signal?: AbortSignal;
+    /** If true, aborts are treated as non-throwing failures */
+    readonly ignoreAbort?: boolean;
+    /** Timeout configuration */
+    readonly timeout?: number;
+    /** Retry configuration */
+    readonly retry?: RetryConfig<E>;
+    /** Circuit breaker configuration */
+    readonly circuitBreaker?: CircuitBreakerConfig<E>;
+    /** Error handling configuration */
+    readonly errorHandling: ErrorHandlingConfig<E>;
+    /** Concurrency configuration for batch operations */
+    readonly concurrency?: number;
+    /** Logging configuration */
+    readonly logger?: LoggerConfig<E>;
+    /** Callback hooks */
+    readonly hooks?: HookConfig<E>;
 }
-declare const errorRule: {
-    instance<E extends new (...args: any[]) => unknown>(ctor: E): ErrorRuleBuilder<InstanceType<E>>;
-    when<E = unknown>(predicate: (err: unknown) => err is E): ErrorRuleBuilder<E>;
+interface RetryConfig<E extends AnyTypedError> {
+    /** Maximum number of retry attempts */
+    readonly maxRetries: number;
+    /** Base delay strategy */
+    readonly strategy: RetryStrategy;
+    /** Jitter configuration to prevent thundering herd */
+    readonly jitter?: JitterConfig;
+    /** Function to determine if retry should be attempted */
+    readonly shouldRetry?: ShouldRetryPredicate<E>;
+}
+type ShouldRetryPredicate<E extends AnyTypedError> = (attempt: number, error: E, context: RetryContext) => boolean;
+interface RetryContext {
+    /** Total attempts made so far */
+    readonly totalAttempts: number;
+    /** Elapsed time since start */
+    readonly elapsedTime: number;
+    /** Start timestamp */
+    readonly startTime: Date;
+    /** Last delay applied */
+    readonly lastDelay?: number;
+}
+interface ErrorHandlingConfig<E extends AnyTypedError> {
+    /** Error normalizer function */
+    readonly normalizer: ErrorNormalizer<E>;
+    /** Optional error mapping/transformation */
+    readonly mapError?: (error: E) => E;
+}
+interface LoggerConfig<E extends AnyTypedError> {
+    /** Debug logging function */
+    readonly debug?: (message: string, meta?: unknown) => void;
+    /** Error logging function */
+    readonly error?: (message: string, error: E) => void;
+    /** Info logging function */
+    readonly info?: (message: string, meta?: unknown) => void;
+    /** Warning logging function */
+    readonly warn?: (message: string, meta?: unknown) => void;
+}
+interface HookConfig<E extends AnyTypedError> {
+    /** Called on successful execution */
+    readonly onSuccess?: <T>(data: T, metrics?: TryoMetrics<E>) => void;
+    /** Called on failed execution */
+    readonly onError?: (error: E, metrics?: TryoMetrics<E>) => void;
+    /** Called always, success or failure */
+    readonly onFinally?: (metrics?: TryoMetrics<E>) => void;
+    /** Called on abort */
+    readonly onAbort?: (signal: AbortSignal) => void;
+    /** Called before retry attempt */
+    readonly onRetry?: (attempt: number, error: E, delay: number) => void;
+    /** Called when circuit breaker state changes */
+    readonly onCircuitStateChange?: (from: CircuitState, to: CircuitState) => void;
+}
+type TryoMetrics<E extends AnyTypedError> = TryoMetrics$1<E>;
+type JitterConfig = {
+    type: 'none';
+} | {
+    type: 'full';
+    ratio: number;
+} | {
+    type: 'equal';
+    ratio: number;
+} | {
+    type: 'custom';
+    calculate: (delay: number) => number;
+};
+declare const JitterConfig: {
+    readonly none: () => JitterConfig;
+    readonly full: (ratio?: number) => JitterConfig;
+    readonly equal: (ratio?: number) => JitterConfig;
+    readonly custom: (calculate: (delay: number) => number) => JitterConfig;
 };
 
-type CreateRunnerOptions<E extends AppError = AppError> = {
-    /**
-     * Custom matchers to use for normalizing errors.
-     * If not provided, the default matchers are used.
-     */
-    rules?: Rule<E>[];
-    /**
-     * Custom fallback function to use for normalizing errors.
-     * If not provided, the default fallback is used.
-     */
+type RulesMode = 'extend' | 'replace';
+type DefaultError = AbortedError | TimeoutError | NetworkError | HttpError | CircuitOpenError | ValidationError | UnknownError;
+type RunOptions<E extends AnyTypedError> = Omit<Partial<TryoConfig<E>>, 'circuitBreaker'>;
+type AllOptions<E extends AnyTypedError> = Omit<Partial<TryoConfig<E> & {
+    concurrency?: number;
+}>, 'circuitBreaker'>;
+type MaybePromise<T> = T | Promise<T>;
+type NonNull<T> = T extends null ? never : T;
+type RuleReturn<R> = R extends (err: unknown) => infer Out ? NonNull<Out> : never;
+type InferErrorFromRules<TRules extends readonly ErrorRule<AnyTypedError>[]> = TRules extends readonly [] ? TypedError : RuleReturn<TRules[number]> | UnknownError;
+type TryoOptions<E extends AnyTypedError = AnyTypedError> = Omit<Partial<TryoConfig<E>>, 'errorHandling' | 'signal'> & {
+    rules?: Array<ErrorRule<E>>;
+    rulesMode?: RulesMode;
     fallback?: (err: unknown) => E;
-    /**
-     * If you want a completely custom normalizer, you can provide it directly.
-     * If set, `matchers` and `fallback` are ignored.
-     */
     toError?: (err: unknown) => E;
-    /** Default for run options */
-    ignoreAbort?: boolean;
-    /** Optional default mapper for all runs */
     mapError?: (error: E) => E;
-    /**
-     * Default circuit breaker for all executions of the instance.
-     * Can be overridden by `options.circuitBreaker` in each `run`.
-     */
-    circuitBreaker?: CircuitBreakerOptions;
 };
-interface Runner<E extends AppError> {
-    run<T>(fn: () => Promise<T>, options?: RunOptions<T, E>): Promise<RunResult<T, E>>;
-    all<T>(fns: Array<() => MaybePromise<T>>, options?: RunAllOptions<T, E>): Promise<RunAllItemResult<T, E>[]>;
-    allOrThrow<T>(fns: Array<() => MaybePromise<T>>, options?: RunOptions<T, E>): Promise<T[]>;
+type ExtractCode<R> = R extends (...args: any[]) => infer E ? E extends TypedError<any, any, any> | null ? E extends null ? never : E extends TypedError<infer C, any, any> ? string extends C ? never : C : never : never : never;
+type CheckUniqueCodes<T extends readonly any[], Seen = never> = T extends readonly [infer Head, ...infer Tail] ? ExtractCode<Head> extends infer C ? [C] extends [never] ? CheckUniqueCodes<Tail, Seen> : [C] extends [Seen] ? {
+    error: '❌ ERROR: Código duplicado detectado';
+    code: C;
+} : CheckUniqueCodes<Tail, Seen | C> : never : true;
+declare function tryo<const TRules extends readonly ErrorRule<AnyTypedError>[]>(options: Omit<TryoOptions<InferErrorFromRules<TRules>>, 'rules' | 'rulesMode'> & {
+    rules: TRules & (CheckUniqueCodes<TRules> extends true ? unknown : CheckUniqueCodes<TRules>);
+    rulesMode: 'replace';
+}): Tryo<InferErrorFromRules<TRules>>;
+declare function tryo<const TRules extends readonly ErrorRule<AnyTypedError>[]>(options: Omit<TryoOptions<InferErrorFromRules<TRules> | DefaultError>, 'rules'> & {
+    rules: TRules & (CheckUniqueCodes<TRules> extends true ? unknown : CheckUniqueCodes<TRules>);
+    rulesMode?: 'extend';
+}): Tryo<InferErrorFromRules<TRules> | DefaultError>;
+declare function tryo<E extends AnyTypedError = DefaultError>(options?: TryoOptions<E>): Tryo<E>;
+type Tryo<E extends AnyTypedError = AnyTypedError> = {
+    run: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => MaybePromise<T>, options?: RunOptions<E>) => Promise<TryoResult<T, E>>;
+    runOrThrow: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => MaybePromise<T>, options?: RunOptions<E>) => Promise<T>;
+    orThrow: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => MaybePromise<T>, options?: RunOptions<E>) => Promise<T>;
+    all: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => MaybePromise<T>>, options?: AllOptions<E>) => Promise<Array<TryoResult<T, E>>>;
+    allOrThrow: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => MaybePromise<T>>, options?: AllOptions<E>) => Promise<T[]>;
+    partitionAll: <T>(results: Array<TryoResult<T, E>>) => {
+        ok: Array<SuccessResult<T, E>>;
+        errors: Array<FailureResult<E> | AbortedResult<E> | TimeoutResult<E>>;
+        failure: Array<FailureResult<E>>;
+        aborted: Array<AbortedResult<E>>;
+        timeout: Array<TimeoutResult<E>>;
+    };
+    withConfig: (additionalConfig: Omit<Partial<TryoConfig<E>>, 'signal'>) => Tryo<E>;
+};
+
+declare const run: <T>(task: (ctx: {
+    signal: AbortSignal;
+}) => T | Promise<T>, options?: {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly ignoreAbort?: boolean | undefined;
+    readonly retry?: RetryConfig<DefaultError> | undefined;
+    readonly errorHandling?: ErrorHandlingConfig<DefaultError> | undefined;
+    readonly concurrency?: number | undefined;
+    readonly logger?: LoggerConfig<DefaultError> | undefined;
+    readonly hooks?: HookConfig<DefaultError> | undefined;
+} | undefined) => Promise<TryoResult<T, DefaultError>>;
+declare const runOrThrow: <T>(task: (ctx: {
+    signal: AbortSignal;
+}) => T | Promise<T>, options?: {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly ignoreAbort?: boolean | undefined;
+    readonly retry?: RetryConfig<DefaultError> | undefined;
+    readonly errorHandling?: ErrorHandlingConfig<DefaultError> | undefined;
+    readonly concurrency?: number | undefined;
+    readonly logger?: LoggerConfig<DefaultError> | undefined;
+    readonly hooks?: HookConfig<DefaultError> | undefined;
+} | undefined) => Promise<T>;
+declare const orThrow: <T>(task: (ctx: {
+    signal: AbortSignal;
+}) => T | Promise<T>, options?: {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly ignoreAbort?: boolean | undefined;
+    readonly retry?: RetryConfig<DefaultError> | undefined;
+    readonly errorHandling?: ErrorHandlingConfig<DefaultError> | undefined;
+    readonly concurrency?: number | undefined;
+    readonly logger?: LoggerConfig<DefaultError> | undefined;
+    readonly hooks?: HookConfig<DefaultError> | undefined;
+} | undefined) => Promise<T>;
+declare const all: <T>(tasks: ((ctx: {
+    signal: AbortSignal;
+}) => T | Promise<T>)[], options?: {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly ignoreAbort?: boolean | undefined;
+    readonly retry?: RetryConfig<DefaultError> | undefined;
+    readonly errorHandling?: ErrorHandlingConfig<DefaultError> | undefined;
+    concurrency?: number | undefined;
+    readonly logger?: LoggerConfig<DefaultError> | undefined;
+    readonly hooks?: HookConfig<DefaultError> | undefined;
+} | undefined) => Promise<TryoResult<T, DefaultError>[]>;
+declare const allOrThrow: <T>(tasks: ((ctx: {
+    signal: AbortSignal;
+}) => T | Promise<T>)[], options?: {
+    readonly timeout?: number | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly ignoreAbort?: boolean | undefined;
+    readonly retry?: RetryConfig<DefaultError> | undefined;
+    readonly errorHandling?: ErrorHandlingConfig<DefaultError> | undefined;
+    concurrency?: number | undefined;
+    readonly logger?: LoggerConfig<DefaultError> | undefined;
+    readonly hooks?: HookConfig<DefaultError> | undefined;
+} | undefined) => Promise<T[]>;
+
+/**
+ * Modern fluent error rule builder
+ * Provides type-safe error rule creation with enhanced ergonomics
+ */
+
+declare class ErrorRuleBuilder<T> {
+    private readonly predicate;
+    constructor(predicate: (err: unknown) => err is T);
+    toCode<const C extends string>(code: C): ErrorMapper<T, C>;
+    toError<const Out extends {
+        code: string;
+        message: string;
+        meta?: Record<string, unknown>;
+        status?: number;
+        cause?: unknown;
+        retryable?: boolean;
+        raw?: any;
+        path?: string;
+    }>(mapper: (err: T) => Out): ErrorRule<TypedError<Out['code'], Out['meta'] extends Record<string, unknown> ? Out['meta'] : Record<string, unknown>, unknown extends Out['raw'] ? T : Out['raw']>>;
+}
+declare class ErrorMapper<T, C extends string> {
+    private readonly predicate;
+    private readonly errorCode;
+    constructor(predicate: (err: unknown) => err is T, errorCode: C);
+    with<const M extends Record<string, unknown> = Record<string, unknown>, const R = '__NOT_SET__'>(mapper: (err: T) => {
+        message: string;
+        cause?: unknown;
+        meta?: M;
+        status?: number;
+        retryable?: boolean;
+        raw?: R;
+        path?: string;
+    }): ErrorRule<TypedError<C, M, R extends '__NOT_SET__' ? T : R>>;
 }
-declare function createRunner(opts?: Omit<CreateRunnerOptions<AppError>, "rules">): Runner<AppError>;
-declare function createRunner<const TRules extends readonly Rule<any>[]>(opts: {
-    rules: TRules;
-} & Omit<CreateRunnerOptions<InferErrorFromRules<TRules>>, "rules">): Runner<InferErrorFromRules<TRules>>;
 
-export { type AppError, type AppErrorCode, type BackoffStrategy, type CircuitBreakerOptions, type CreateRunnerOptions, type ErrorResult, type Metrics, type RetryContext, type RetryOptions, type RunAllItemResult, type RunAllOptions, type RunOptions, type RunResult, type SuccessResult, createNormalizer, createRunner, defaultFallback, errorRule, isSuccess, rules, run, runAll, runAllSettled, toAppError };
+declare const errorRule: {
+    readonly when: <T>(predicate: (err: unknown) => err is T) => ErrorRuleBuilder<T>;
+    readonly instance: <T extends new (...args: unknown[]) => unknown>(ErrorClass: T) => ErrorRuleBuilder<InstanceType<T>>;
+};
+
+export { type AbortedResult, type FailureResult, type Milliseconds, type RetryCount, RetryStrategies, type RulesMode, type SuccessResult, type TimeoutResult, type TryoConfig, type TryoMetrics$1 as TryoMetrics, type TryoOptions, type TryoResult, TypedError, all, allOrThrow, asMilliseconds, asRetryCount, tryo as default, errorRule, orThrow, run, runOrThrow, tryo };