trybox 0.10.1 → 0.12.0

package/dist/index.d.ts

@@ -1,338 +1,422 @@
-type ResultErrorCode = "ABORTED" | "NETWORK" | "TIMEOUT" | "VALIDATION" | "HTTP" | "CIRCUIT_OPEN" | "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 ResultError<Code extends string = ResultErrorCode | (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 [] ? ResultError : RuleReturn<TRules[number]> | ResultError<"UNKNOWN">;
-type Rule<E extends ResultError = ResultError> = (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;
+type RetryCount = number & {
+    readonly __brand: 'RetryCount';
 };
-/**
- * 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 ResultError = ResultError> = {
-    /**
-     * 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;
+type ConcurrencyLimit = number & {
+    readonly __brand: 'ConcurrencyLimit';
 };
-/**
- * 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;
-    /** Timestamp (ms) when the execution started. */
-    startTime: number;
-    /** The delay (ms) applied before the last attempt, if any. */
-    lastDelay?: number;
+type Percentage = number & {
+    readonly __brand: 'Percentage';
 };
+type StatusCode = number & {
+    readonly __brand: 'StatusCode';
+};
+declare const asMilliseconds: (n: number) => Milliseconds;
+declare const asRetryCount: (n: number) => RetryCount;
+declare const asConcurrencyLimit: (n: number) => ConcurrencyLimit;
+declare const asPercentage: (n: number) => Percentage;
+declare const asStatusCode: (n: number) => StatusCode;
+
 /**
- * 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 ResultError = ResultError> = 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?: unknown) => void;
-        error?: (msg: string, error: E) => void;
+
+declare abstract class TypedError<Code extends string = string, Meta = unknown> extends Error {
+    abstract readonly code: Code;
+    readonly cause?: unknown;
+    readonly meta?: Meta;
+    readonly status?: number;
+    readonly timestamp: Date;
+    constructor(message: string, opts?: {
+        cause?: unknown;
+        meta?: Meta;
+        status?: number;
+    });
+    is<C extends string>(code: C): this is TypedError<C> & {
+        code: C;
+    };
+    withMeta<const M>(meta: M): this & {
+        meta: M;
     };
-    /**
-     * Callback on abort, useful for reacting to `AbortSignal`.
-     */
-    onAbort?: (signal: AbortSignal) => void;
+    withStatus(status: number): this & {
+        status: number;
+    };
+    withCause(cause: unknown): this & {
+        cause: unknown;
+    };
+    toJSON(): Record<string, unknown>;
+}
+declare class TimeoutError extends TypedError<'TIMEOUT'> {
+    readonly code: "TIMEOUT";
+    constructor(timeout: Milliseconds, cause?: unknown);
+}
+declare class AbortedError extends TypedError<'ABORTED'> {
+    readonly code: "ABORTED";
+    constructor(reason?: string, cause?: unknown);
+}
+declare class CircuitOpenError extends TypedError<'CIRCUIT_OPEN'> {
+    readonly code: "CIRCUIT_OPEN";
+    constructor(resetAfter: Milliseconds, cause?: unknown);
+}
+type ValidationMeta = {
+    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> {
+    readonly validationErrors: unknown[];
+    readonly code: "VALIDATION";
+    constructor(message: string, validationErrors: unknown[], cause?: unknown);
+}
+declare class NetworkError extends TypedError<'NETWORK'> {
+    readonly statusCode?: number | undefined;
+    readonly code: "NETWORK";
+    constructor(message: string, statusCode?: number | undefined, cause?: unknown);
+}
+type HttpMeta = {
+    response?: unknown;
 };
+declare class HttpError extends TypedError<'HTTP', HttpMeta> {
+    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'> {
+    readonly code: "UNKNOWN";
+    constructor(message: string, cause?: unknown);
+}
+
 /**
- * Execution metrics optionally returned in `RunResult`.
+ * Modern error normalization system
+ * Provides type-safe error transformation and normalization
  */
-type Metrics<E extends ResultError = ResultError> = {
-    totalAttempts: number;
-    totalRetries: number;
-    totalDuration: number;
-    lastError?: E;
-};
-type RunResult<T, E extends ResultError = ResultError> = {
-    ok: true;
-    data: T;
-    error: null;
-    metrics?: Metrics<E>;
-} | {
-    ok: false;
-    data: null;
-    error: E;
-    metrics?: Metrics<E>;
-};
+
+type ErrorNormalizer<E extends TypedError = TypedError> = (error: unknown) => E;
+type ErrorRule<E extends TypedError = TypedError> = (error: unknown) => E | null;
 
 /**
- * Executes an async operation and returns a Result instead of throwing.
- *
- * Errors are normalized into an `ResultError` (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 result types with enhanced discriminated unions
+ * Provides better type safety and more granular result categorization
  */
-declare function run<T, E extends ResultError = ResultError>(fn: (ctx?: {
-    signal: AbortSignal;
-}) => MaybePromise<T>, options?: RunOptions<T, E>): Promise<RunResult<T, E>>;
+
+type ExecutionResult<T, E extends TypedError = TypedError> = SuccessResult<T, E> | FailureResult<E> | AbortedResult<E> | TimeoutResult<E>;
+interface SuccessResult<T, E extends TypedError> {
+    readonly type: 'success';
+    readonly ok: true;
+    readonly data: T;
+    readonly error: null;
+    readonly metrics?: ExecutionMetrics$1<E>;
+}
+interface FailureResult<E extends TypedError> {
+    readonly type: 'failure';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics?: ExecutionMetrics$1<E>;
+}
+interface AbortedResult<E extends TypedError> {
+    readonly type: 'aborted';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics?: ExecutionMetrics$1<E>;
+}
+interface TimeoutResult<E extends TypedError> {
+    readonly type: 'timeout';
+    readonly ok: false;
+    readonly data: null;
+    readonly error: E;
+    readonly metrics?: ExecutionMetrics$1<E>;
+}
+interface ExecutionMetrics$1<E extends TypedError> {
+    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;
+    }>;
+}
 
 /**
- * Discriminated result per item in `runAll`:
- * - "ok": successful task with `data`
- * - "error": failed task with `error`
- * - "skipped": task not executed due to cancellation/fail-fast/concurrency
+ * Modern circuit breaker implementation with enhanced state management
+ * Provides circuit breaker pattern with type safety and observability
  */
-type RunAllItemResult<T, E extends ResultError = ResultError> = {
-    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 ResultError ? E : ResultError>, {
-    status: "error";
-}>;
-/** Type guard that detects `status: "ok"` with `data` typing. */
-declare const isSuccess: <T, E extends ResultError = ResultError>(r: RunAllItemResult<T, E>) => r is SuccessResult<T>;
-type RunAllOptions<T, E extends ResultError = ResultError> = 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 runAll<T, E extends ResultError = ResultError>(tasks: Array<() => MaybePromise<T>>, options?: RunAllOptions<T, E>): Promise<RunAllItemResult<T, E>[]>;
+
+interface CircuitBreakerConfig<E extends TypedError = TypedError> {
+    /** 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;
+}
 
 /**
- * Options for `runAllOrThrow`:
- * - 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 ResultError = ResultError> = RunOptions<T, E> & {
-    /**
-     * Maximum number of concurrent tasks to run.
-     * @default Infinity
-     */
-    concurrency?: number;
-};
-declare function runAllOrThrow<T, E extends ResultError = ResultError>(tasks: Array<() => MaybePromise<T>>, options?: RunAllOrThrowOptions<T, E>): Promise<T[]>;
-
-declare function createNormalizer<E extends ResultError>(rules: Rule<E>[], fallback: (err: unknown) => E): (err: unknown) => E;
-declare function defaultFallback(err: unknown): ResultError;
-declare function toResultError(err: unknown): ResultError;
 
-declare const rules: {
-    circuitOpen: Rule<ResultError<"CIRCUIT_OPEN">>;
-    abort: Rule<ResultError<"ABORTED">>;
-    timeout: Rule<ResultError<"TIMEOUT">>;
-    httpStatus: Rule<ResultError<"HTTP">>;
-    aggregate: Rule<ResultError<"UNKNOWN", {
-        errors: unknown[];
-    }>>;
-    string: Rule<ResultError<"UNKNOWN">>;
-    message: Rule<ResultError<"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 const defaultRules: readonly [Rule<ResultError<"CIRCUIT_OPEN">>, Rule<ResultError<"ABORTED">>, Rule<ResultError<"TIMEOUT">>, Rule<ResultError<"HTTP">>, Rule<ResultError<"UNKNOWN", {
-    errors: unknown[];
-}>>, Rule<ResultError<"UNKNOWN">>, Rule<ResultError<"UNKNOWN">>];
-type DefaultRules = typeof defaultRules;
-type DefaultError = InferErrorFromRules<DefaultRules>;
 
-declare class ErrorRuleBuilder<E> {
-    private readonly matcher;
-    constructor(matcher: (err: unknown) => err is E);
-    toError<const Out extends ResultError>(mapper: (err: E) => Out): Rule<Out>;
+interface ExecutionConfig<E extends TypedError = TypedError> {
+    /** 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 TypedError> {
+    /** 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 TypedError> = (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 TypedError> {
+    /** Error normalizer function */
+    readonly normalizer: ErrorNormalizer<E>;
+    /** Optional error mapping/transformation */
+    readonly mapError?: (error: E) => E;
+}
+interface LoggerConfig<E extends TypedError> {
+    /** 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 TypedError> {
+    /** Called on successful execution */
+    readonly onSuccess?: <T>(data: T, metrics?: ExecutionMetrics<E>) => void;
+    /** Called on failed execution */
+    readonly onError?: (error: E, metrics?: ExecutionMetrics<E>) => void;
+    /** Called always, success or failure */
+    readonly onFinally?: (metrics?: ExecutionMetrics<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 CircuitState = 'closed' | 'open' | 'half-open';
+type ExecutionMetrics<E extends TypedError> = ExecutionMetrics$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 RulesMode = "extend" | "replace";
-type CreateRunnerOptions<E extends ResultError = ResultError> = {
-    /**
-     * Custom matchers to use for normalizing errors.
-     * If not provided, the default matchers are used.
-     */
-    rules?: Rule<E>[];
-    /**
-     * How to treat provided rules in relation to default rules.
-     * - "extend": Use default rules after custom rules (default).
-     * - "replace": Use only custom rules (and fallback).
-     */
+type RulesMode = 'extend' | 'replace';
+type DefaultError = AbortedError | TimeoutError | NetworkError | HttpError | CircuitOpenError | ValidationError | UnknownError;
+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<TypedError>[]> = TRules extends readonly [] ? TypedError : RuleReturn<TRules[number]> | UnknownError;
+type ExecutorOptions<E extends TypedError = TypedError> = Omit<Partial<ExecutionConfig<E>>, 'errorHandling'> & {
+    rules?: Array<ErrorRule<E>>;
     rulesMode?: RulesMode;
-    /**
-     * Custom fallback function to use for normalizing errors.
-     * If not provided, the default fallback is used.
-     */
     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;
-    /**
-     * Circuit breaker configuration (applies to all executions of the Runner).
-     */
-    circuitBreaker?: CircuitBreakerOptions;
 };
-interface Runner<E extends ResultError> {
-    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?: RunAllOrThrowOptions<T, E>): 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?: unknown;
+        status?: number;
+        cause?: unknown;
+    }>(mapper: (err: T) => Out): ErrorRule<TypedError<Out['code'], Out['meta']>>;
+}
+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 = unknown>(mapper: (err: T) => {
+        message: string;
+        cause?: unknown;
+        meta?: M;
+        status?: number;
+    }): (err: unknown) => TypedError<C, M> | null;
 }
 
-declare function trybox(options?: Omit<CreateRunnerOptions<ResultError>, "rules">): Runner<ResultError>;
-declare function trybox<const TRules extends readonly Rule<any>[]>(options: {
-    rules: TRules;
-    rulesMode: "replace";
-} & Omit<CreateRunnerOptions<InferErrorFromRules<TRules>>, "rules" | "rulesMode">): Runner<InferErrorFromRules<TRules>>;
-declare function trybox<const TRules extends readonly Rule<any>[]>(options: {
+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>>;
+};
+
+/**
+ * Public API: legacy runner-first.
+ *
+ * Default export is a factory that creates an internal Executor instance.
+ * The Executor class and the old functional facade are intentionally not
+ * exported from the package surface.
+ */
+
+type Runner<E extends TypedError = TypedError> = {
+    run: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<ExecutionResult<T, E>>;
+    execute: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<ExecutionResult<T, E>>;
+    runOrThrow: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<T>;
+    executeOrThrow: <T>(task: (ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<T>;
+    runAll: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+        concurrency?: number;
+    }>) => Promise<Array<ExecutionResult<T, E>>>;
+    executeAll: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+        concurrency?: number;
+    }>) => Promise<Array<ExecutionResult<T, E>>>;
+    runOrThrowAll: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+        concurrency?: number;
+    }>) => Promise<T[]>;
+    executeOrThrowAll: <T>(tasks: Array<(ctx: {
+        signal: AbortSignal;
+    }) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+        concurrency?: number;
+    }>) => Promise<T[]>;
+};
+declare function trybox<const TRules extends readonly ErrorRule<TypedError>[]>(options: Omit<ExecutorOptions<InferErrorFromRules<TRules>>, 'rules'> & {
     rules: TRules;
-    rulesMode?: "extend";
-} & Omit<CreateRunnerOptions<InferErrorFromRules<TRules> | DefaultError>, "rules" | "rulesMode">): Runner<InferErrorFromRules<TRules> | DefaultError>;
+}): Runner<InferErrorFromRules<TRules>>;
+declare function trybox<E extends TypedError = DefaultError>(options?: ExecutorOptions<E>): Runner<E>;
+
+declare const execute: <T, E extends TypedError = DefaultError>(task: (ctx: {
+    signal: AbortSignal;
+}) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<ExecutionResult<T, TypedError<string, unknown>>>;
+declare const executeOrThrow: <T, E extends TypedError = DefaultError>(task: (ctx: {
+    signal: AbortSignal;
+}) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<T>;
+declare const executeAll: <T, E extends TypedError = DefaultError>(tasks: Array<(ctx: {
+    signal: AbortSignal;
+}) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+    concurrency?: number;
+}>) => Promise<ExecutionResult<T, TypedError<string, unknown>>[]>;
+declare const executeAllOrThrow: <T, E extends TypedError = DefaultError>(tasks: Array<(ctx: {
+    signal: AbortSignal;
+}) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+    concurrency?: number;
+}>) => Promise<T[]>;
+declare const executeOrThrowAll: <T, E extends TypedError = DefaultError>(tasks: Array<(ctx: {
+    signal: AbortSignal;
+}) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+    concurrency?: number;
+}>) => Promise<T[]>;
+declare const run: <T, E extends TypedError = DefaultError>(task: (ctx: {
+    signal: AbortSignal;
+}) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<ExecutionResult<T, TypedError<string, unknown>>>;
+declare const runOrThrow: <T, E extends TypedError = DefaultError>(task: (ctx: {
+    signal: AbortSignal;
+}) => Promise<T>, options?: Partial<ExecutionConfig<E>>) => Promise<T>;
+declare const runAll: <T, E extends TypedError = DefaultError>(tasks: Array<(ctx: {
+    signal: AbortSignal;
+}) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+    concurrency?: number;
+}>) => Promise<ExecutionResult<T, TypedError<string, unknown>>[]>;
+declare const runOrThrowAll: <T, E extends TypedError = DefaultError>(tasks: Array<(ctx: {
+    signal: AbortSignal;
+}) => Promise<T>>, options?: Partial<ExecutionConfig<E> & {
+    concurrency?: number;
+}>) => Promise<T[]>;
 
-export { type BackoffStrategy, type CircuitBreakerOptions, type ErrorResult, type Metrics, type ResultError, type ResultErrorCode, type RetryContext, type RetryOptions, type RunAllItemResult, type RunAllOptions, type RunOptions, type RunResult, type SuccessResult, createNormalizer, trybox as default, defaultFallback, errorRule, isSuccess, rules, run, runAll, runAllOrThrow, toResultError };
+export { type AbortedResult, type ConcurrencyLimit, type ExecutionConfig, type ExecutionMetrics$1 as ExecutionMetrics, type ExecutionResult, type ExecutorOptions, type FailureResult, type Milliseconds, type Percentage, type RetryCount, RetryStrategies, type RulesMode, type Runner, type StatusCode, type SuccessResult, type TimeoutResult, asConcurrencyLimit, asMilliseconds, asPercentage, asRetryCount, asStatusCode, trybox as default, errorRule, execute, executeAll, executeAllOrThrow, executeOrThrow, executeOrThrowAll, run, runAll, runOrThrow, runOrThrowAll, trybox };