@jagreehal/workflow 1.0.0

package/dist/core.d.cts

@@ -0,0 +1,1606 @@
+/**
+ * @jagreehal/workflow/core
+ *
+ * Core Result primitives and run() function.
+ * Use this module for minimal bundle size when you don't need the full workflow capabilities
+ * (like retries, timeout, or state persistence) provided by `createWorkflow`.
+ *
+ * This module provides:
+ * 1. `Result` types for error handling without try/catch
+ * 2. `run()` function for executing steps with standardized error management
+ * 3. Utilities for transforming and combining Results
+ */
+/**
+ * Represents a successful computation or a failed one.
+ * Use this type to represent the outcome of an operation that might fail,
+ * instead of throwing exceptions.
+ *
+ * @template T - The type of the success value
+ * @template E - The type of the error value (defaults to unknown)
+ * @template C - The type of the cause (defaults to unknown)
+ */
+type Result<T, E = unknown, C = unknown> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+    cause?: C;
+};
+/**
+ * A Promise that resolves to a Result.
+ * Use this for asynchronous operations that might fail.
+ */
+type AsyncResult<T, E = unknown, C = unknown> = Promise<Result<T, E, C>>;
+type UnexpectedStepFailureCause = {
+    type: "STEP_FAILURE";
+    origin: "result";
+    error: unknown;
+    cause?: unknown;
+} | {
+    type: "STEP_FAILURE";
+    origin: "throw";
+    error: unknown;
+    thrown: unknown;
+};
+type UnexpectedCause = {
+    type: "UNCAUGHT_EXCEPTION";
+    thrown: unknown;
+} | UnexpectedStepFailureCause;
+type UnexpectedError = {
+    type: "UNEXPECTED_ERROR";
+    cause: UnexpectedCause;
+};
+type PromiseRejectedError = {
+    type: "PROMISE_REJECTED";
+    cause: unknown;
+};
+/** Cause type for promise rejections in async batch helpers */
+type PromiseRejectionCause = {
+    type: "PROMISE_REJECTION";
+    reason: unknown;
+};
+type EmptyInputError = {
+    type: "EMPTY_INPUT";
+    message: string;
+};
+type MaybeAsyncResult<T, E, C = unknown> = Result<T, E, C> | Promise<Result<T, E, C>>;
+/**
+ * Creates a successful Result.
+ * Use this when an operation completes successfully.
+ *
+ * @param value - The success value to wrap
+ * @returns A Result object with `{ ok: true, value }`
+ *
+ * @example
+ * ```typescript
+ * function divide(a: number, b: number): Result<number, string> {
+ *   if (b === 0) return err("Division by zero");
+ *   return ok(a / b);
+ * }
+ * ```
+ */
+declare const ok: <T>(value: T) => Result<T, never, never>;
+/**
+ * Creates a failed Result.
+ * Use this when an operation fails.
+ *
+ * @param error - The error value describing what went wrong (e.g., error code, object)
+ * @param options - Optional context about the failure
+ * @param options.cause - The underlying cause of the error (e.g., a caught exception)
+ * @returns A Result object with `{ ok: false, error }` (and optional cause)
+ *
+ * @example
+ * ```typescript
+ * // Simple error
+ * const r1 = err("NOT_FOUND");
+ *
+ * // Error with cause (useful for wrapping exceptions)
+ * try {
+ *   // ... unsafe code
+ * } catch (e) {
+ *   return err("PROCESSING_FAILED", { cause: e });
+ * }
+ * ```
+ */
+declare const err: <E, C = unknown>(error: E, options?: {
+    cause?: C;
+}) => Result<never, E, C>;
+/**
+ * Checks if a Result is successful.
+ * Use this to narrow the type of a Result to the success case.
+ *
+ * @param r - The Result to check
+ * @returns `true` if successful, allowing access to `r.value`
+ *
+ * @example
+ * ```typescript
+ * const r = someOperation();
+ * if (isOk(r)) {
+ *   console.log(r.value); // Type is T
+ * } else {
+ *   console.error(r.error); // Type is E
+ * }
+ * ```
+ */
+declare const isOk: <T, E, C>(r: Result<T, E, C>) => r is {
+    ok: true;
+    value: T;
+};
+/**
+ * Checks if a Result is a failure.
+ * Use this to narrow the type of a Result to the error case.
+ *
+ * @param r - The Result to check
+ * @returns `true` if failed, allowing access to `r.error` and `r.cause`
+ *
+ * @example
+ * ```typescript
+ * if (isErr(r)) {
+ *   // Handle error case early
+ *   return;
+ * }
+ * // Proceed with success case
+ * ```
+ */
+declare const isErr: <T, E, C>(r: Result<T, E, C>) => r is {
+    ok: false;
+    error: E;
+    cause?: C;
+};
+/**
+ * Checks if an error is an UnexpectedError.
+ * Used internally by the framework but exported for advanced custom handling.
+ * Indicates an error that wasn't typed/expected in the `run` signature.
+ */
+declare const isUnexpectedError: (e: unknown) => e is UnexpectedError;
+type AnyFunction = (...args: never[]) => unknown;
+/**
+ * Extract error type from a single function's return type
+ */
+type ErrorOf<T extends AnyFunction> = ReturnType<T> extends Result<unknown, infer E, unknown> ? E : ReturnType<T> extends Promise<Result<unknown, infer E, unknown>> ? E : never;
+/**
+ * Extract union of error types from multiple functions
+ */
+type Errors<T extends AnyFunction[]> = {
+    [K in keyof T]: ErrorOf<T[K]>;
+}[number];
+/**
+ * Extract value type from Result
+ */
+type ExtractValue<T> = T extends {
+    ok: true;
+    value: infer U;
+} ? U : never;
+/**
+ * Extract error type from Result
+ */
+type ExtractError<T> = T extends {
+    ok: false;
+    error: infer E;
+} ? E : never;
+/**
+ * Extract cause type from Result
+ */
+type ExtractCause<T> = T extends {
+    ok: false;
+    cause?: infer C;
+} ? C : never;
+/**
+ * Extract cause type from a function's return type
+ */
+type CauseOf<T extends AnyFunction> = ReturnType<T> extends Result<unknown, unknown, infer C> ? C : ReturnType<T> extends Promise<Result<unknown, unknown, infer C>> ? C : never;
+/**
+ * Options for configuring a step within a workflow.
+ * Use these to enable tracing, caching, and state persistence.
+ */
+type StepOptions = {
+    /**
+     * Human-readable label for the step.
+     * Used in logs, traces, and error messages.
+     * Highly recommended for debugging complex workflows.
+     */
+    name?: string;
+    /**
+     * Stable identity key for the step.
+     * REQUIRED for:
+     * 1. Caching: Used as the cache key.
+     * 2. Resuming: Used to identify which steps have already completed.
+     *
+     * Must be unique within the workflow.
+     */
+    key?: string;
+};
+/**
+ * The `step` object passed to the function in `run(async (step) => { ... })`.
+ * acts as the bridge between your business logic and the workflow engine.
+ *
+ * It provides methods to:
+ * 1. Execute operations that return `Result` types.
+ * 2. safely wrap operations that might throw exceptions (using `step.try`).
+ * 3. Assign names and keys to operations for tracing and caching.
+ *
+ * @template E - The union of all known error types expected in this workflow.
+ */
+interface RunStep<E = unknown> {
+    /**
+     * Execute a Result-returning operation (lazy function form).
+     *
+     * Use this form when the operation has side effects or is expensive,
+     * so it's only executed if the step hasn't been cached/completed yet.
+     *
+     * @param operation - A function that returns a Result or AsyncResult
+     * @param options - Step name or options object
+     * @returns The success value (unwrapped)
+     * @throws {EarlyExit} If the result is an error (stops execution safely)
+     *
+     * @example
+     * ```typescript
+     * const user = await step(() => fetchUser(id), "fetch-user");
+     * ```
+     */
+    <T, StepE extends E, StepC = unknown>(operation: () => Result<T, StepE, StepC> | AsyncResult<T, StepE, StepC>, options?: StepOptions | string): Promise<T>;
+    /**
+     * Execute a Result-returning operation (direct value form).
+     *
+     * Use this form for simple operations or when you already have a Result/Promise.
+     * Note: The operation has already started/completed by the time `step` is called.
+     *
+     * @param result - A Result object or Promise resolving to a Result
+     * @param options - Step name or options object
+     * @returns The success value (unwrapped)
+     * @throws {EarlyExit} If the result is an error (stops execution safely)
+     *
+     * @example
+     * ```typescript
+     * const user = await step(existingResult, "check-result");
+     * ```
+     */
+    <T, StepE extends E, StepC = unknown>(result: Result<T, StepE, StepC> | AsyncResult<T, StepE, StepC>, options?: StepOptions | string): Promise<T>;
+    /**
+     * Execute a standard throwing operation safely.
+     * Catches exceptions and maps them to a typed error, or wraps them if no mapper is provided.
+     *
+     * Use this when integrating with libraries that throw exceptions.
+     *
+     * @param operation - A function that returns a value or Promise (may throw)
+     * @param options - Configuration including error mapping
+     * @returns The success value
+     * @throws {EarlyExit} If the operation throws (stops execution safely)
+     *
+     * @example
+     * ```typescript
+     * const data = await step.try(
+     *   () => db.query(),
+     *   {
+     *     name: "db-query",
+     *     onError: (e) => ({ type: "DB_ERROR", cause: e })
+     *   }
+     * );
+     * ```
+     */
+    try: <T, const Err extends E>(operation: () => T | Promise<T>, options: {
+        error: Err;
+        name?: string;
+        key?: string;
+    } | {
+        onError: (cause: unknown) => Err;
+        name?: string;
+        key?: string;
+    }) => Promise<T>;
+}
+/**
+ * Unified event stream for workflow execution.
+ *
+ * Note: step_complete.result uses Result<unknown, unknown, unknown> because events
+ * aggregate results from heterogeneous steps. At runtime, the actual Result object
+ * preserves its original types, but the event type cannot statically represent them.
+ * Use runtime checks or the meta field to interpret cause values.
+ */
+type WorkflowEvent<E> = {
+    type: "workflow_start";
+    workflowId: string;
+    ts: number;
+} | {
+    type: "workflow_success";
+    workflowId: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "workflow_error";
+    workflowId: string;
+    ts: number;
+    durationMs: number;
+    error: E;
+} | {
+    type: "step_start";
+    workflowId: string;
+    stepKey?: string;
+    name?: string;
+    ts: number;
+} | {
+    type: "step_success";
+    workflowId: string;
+    stepKey?: string;
+    name?: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "step_error";
+    workflowId: string;
+    stepKey?: string;
+    name?: string;
+    ts: number;
+    durationMs: number;
+    error: E;
+} | {
+    type: "step_aborted";
+    workflowId: string;
+    stepKey?: string;
+    name?: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "step_complete";
+    workflowId: string;
+    stepKey: string;
+    name?: string;
+    ts: number;
+    durationMs: number;
+    result: Result<unknown, unknown, unknown>;
+    meta?: StepFailureMeta;
+} | {
+    type: "step_cache_hit";
+    workflowId: string;
+    stepKey: string;
+    name?: string;
+    ts: number;
+} | {
+    type: "step_cache_miss";
+    workflowId: string;
+    stepKey: string;
+    name?: string;
+    ts: number;
+};
+type RunOptionsWithCatch<E, C = void> = {
+    /**
+     * Handler for expected errors.
+     * Called when a step fails with a known error type.
+     */
+    onError?: (error: E, stepName?: string) => void;
+    /**
+     * Listener for workflow events (start, success, error, step events).
+     * Use this for logging, telemetry, or debugging.
+     */
+    onEvent?: (event: WorkflowEvent<E | UnexpectedError>, ctx: C) => void;
+    /**
+     * Catch-all mapper for unexpected exceptions.
+     * Required for "Strict Mode".
+     * Converts unknown exceptions (like network crashes or bugs) into your typed error union E.
+     */
+    catchUnexpected: (cause: unknown) => E;
+    /**
+     * Unique ID for this workflow execution.
+     * Defaults to a random UUID.
+     * Useful for correlating logs across distributed systems.
+     */
+    workflowId?: string;
+    /**
+     * Arbitrary context object passed to onEvent.
+     * Useful for passing request IDs, user IDs, or loggers.
+     */
+    context?: C;
+};
+type RunOptionsWithoutCatch<E, C = void> = {
+    /**
+     * Handler for expected errors AND unexpected errors.
+     * Unexpected errors will be wrapped in `UnexpectedError`.
+     */
+    onError?: (error: E | UnexpectedError, stepName?: string) => void;
+    onEvent?: (event: WorkflowEvent<E | UnexpectedError>, ctx: C) => void;
+    catchUnexpected?: undefined;
+    workflowId?: string;
+    context?: C;
+};
+type RunOptions<E, C = void> = RunOptionsWithCatch<E, C> | RunOptionsWithoutCatch<E, C>;
+/**
+ * Symbol used to identify early exit throws.
+ * Exported for the caching layer in workflow.ts.
+ * @internal
+ */
+declare const EARLY_EXIT_SYMBOL: unique symbol;
+/**
+ * Metadata about how a step failed.
+ * @internal
+ */
+type StepFailureMeta = {
+    origin: "result";
+    resultCause?: unknown;
+} | {
+    origin: "throw";
+    thrown: unknown;
+};
+/**
+ * Early exit object thrown to short-circuit workflow execution.
+ * @internal
+ */
+type EarlyExit<E> = {
+    [EARLY_EXIT_SYMBOL]: true;
+    error: E;
+    meta: StepFailureMeta;
+};
+/**
+ * Create an early exit throw object.
+ * Used by the caching layer to synthesize early exits for cached errors.
+ * @internal
+ */
+declare function createEarlyExit<E>(error: E, meta: StepFailureMeta): EarlyExit<E>;
+/**
+ * Type guard for early exit objects.
+ * @internal
+ */
+declare function isEarlyExit<E>(e: unknown): e is EarlyExit<E>;
+/**
+ * Execute a workflow with "Strict Mode" error handling.
+ *
+ * In this mode, you MUST provide `catchUnexpected` to map unknown exceptions
+ * to your typed error union `E`. This guarantees that the returned Result
+ * will only ever contain errors of type `E`.
+ *
+ * @param fn - The workflow function containing steps
+ * @param options - Configuration options, including `catchUnexpected`
+ * @returns A Promise resolving to `Result<T, E>`
+ *
+ * @example
+ * ```typescript
+ * const result = await run(async (step) => {
+ *   // ... steps ...
+ * }, {
+ *   catchUnexpected: (e) => ({ type: 'UNKNOWN_ERROR', cause: e })
+ * });
+ * ```
+ */
+declare function run<T, E, C = void>(fn: (step: RunStep<E>) => Promise<T> | T, options: RunOptionsWithCatch<E, C>): AsyncResult<T, E, unknown>;
+/**
+ * Execute a workflow with "Typed Mode" error handling.
+ *
+ * In this mode, you provide an `onError` callback. The returned Result
+ * may contain your typed errors `E` OR `UnexpectedError` if an uncaught
+ * exception occurs.
+ *
+ * @param fn - The workflow function containing steps
+ * @param options - Configuration options, including `onError`
+ * @returns A Promise resolving to `Result<T, E | UnexpectedError>`
+ */
+declare function run<T, E, C = void>(fn: (step: RunStep<E | UnexpectedError>) => Promise<T> | T, options: {
+    onError: (error: E | UnexpectedError, stepName?: string) => void;
+    onEvent?: (event: WorkflowEvent<E | UnexpectedError>, ctx: C) => void;
+    workflowId?: string;
+    context?: C;
+}): AsyncResult<T, E | UnexpectedError, unknown>;
+/**
+ * Execute a workflow with "Safe Default" error handling.
+ *
+ * In this mode, you don't need to specify any error types.
+ * Any error (Result error or thrown exception) will be returned as
+ * an `UnexpectedError`.
+ *
+ * @param fn - The workflow function containing steps
+ * @param options - Optional configuration
+ * @returns A Promise resolving to `Result<T, UnexpectedError>`
+ *
+ * @example
+ * ```typescript
+ * const result = await run(async (step) => {
+ *   return await step(someOp());
+ * });
+ * ```
+ */
+declare function run<T, C = void>(fn: (step: RunStep) => Promise<T> | T, options?: {
+    onEvent?: (event: WorkflowEvent<UnexpectedError>, ctx: C) => void;
+    workflowId?: string;
+    context?: C;
+}): AsyncResult<T, UnexpectedError, unknown>;
+declare namespace run {
+    var strict: <T, E, C = void>(fn: (step: RunStep<E>) => Promise<T> | T, options: {
+        onError?: (error: E, stepName?: string) => void;
+        onEvent?: (event: WorkflowEvent<E | UnexpectedError>, ctx: C) => void;
+        catchUnexpected: (cause: unknown) => E;
+        workflowId?: string;
+        context?: C;
+    }) => AsyncResult<T, E, unknown>;
+}
+/**
+ * Error thrown when `unwrap()` is called on an error Result.
+ *
+ * This error is thrown to prevent silent failures when using `unwrap()`.
+ * Prefer using `unwrapOr`, `unwrapOrElse`, or pattern matching with `match` or `isOk`/`isErr`.
+ */
+declare class UnwrapError<E = unknown, C = unknown> extends Error {
+    readonly error: E;
+    readonly cause?: C | undefined;
+    constructor(error: E, cause?: C | undefined);
+}
+/**
+ * Unwraps a Result, throwing an error if it's a failure.
+ *
+ * ## When to Use
+ *
+ * Use `unwrap()` when:
+ * - You're certain the Result is successful (e.g., after checking with `isOk`)
+ * - You're in a context where errors should crash (e.g., tests, initialization)
+ * - You need the value immediately and can't handle errors gracefully
+ *
+ * ## Why Avoid This
+ *
+ * **Prefer alternatives** in production code:
+ * - `unwrapOr(defaultValue)` - Provide a fallback value
+ * - `unwrapOrElse(fn)` - Compute fallback from error
+ * - `match()` - Handle both cases explicitly
+ * - `isOk()` / `isErr()` - Type-safe pattern matching
+ *
+ * Throwing errors makes error handling harder and can crash your application.
+ *
+ * @param r - The Result to unwrap
+ * @returns The success value if the Result is successful
+ * @throws {UnwrapError} If the Result is an error (includes the error and cause)
+ *
+ * @example
+ * ```typescript
+ * // Safe usage after checking
+ * const result = someOperation();
+ * if (isOk(result)) {
+ *   const value = unwrap(result); // Safe - we know it's ok
+ * }
+ *
+ * // Unsafe usage (not recommended)
+ * const value = unwrap(someOperation()); // May throw!
+ * ```
+ */
+declare const unwrap: <T, E, C>(r: Result<T, E, C>) => T;
+/**
+ * Unwraps a Result, returning a default value if it's a failure.
+ *
+ * ## When to Use
+ *
+ * Use `unwrapOr()` when:
+ * - You have a sensible default value for errors
+ * - You want to continue execution even on failure
+ * - The default value is cheap to compute (use `unwrapOrElse` if expensive)
+ *
+ * ## Why Use This
+ *
+ * - **Safe**: Never throws, always returns a value
+ * - **Simple**: One-liner for common error handling
+ * - **Type-safe**: TypeScript knows you'll always get a `T`
+ *
+ * @param r - The Result to unwrap
+ * @param defaultValue - The value to return if the Result is an error
+ * @returns The success value if successful, otherwise the default value
+ *
+ * @example
+ * ```typescript
+ * // Provide default for missing data
+ * const user = unwrapOr(fetchUser(id), { id: 'anonymous', name: 'Guest' });
+ *
+ * // Provide default for numeric operations
+ * const count = unwrapOr(parseCount(input), 0);
+ *
+ * // Provide default for optional features
+ * const config = unwrapOr(loadConfig(), getDefaultConfig());
+ * ```
+ */
+declare const unwrapOr: <T, E, C>(r: Result<T, E, C>, defaultValue: T) => T;
+/**
+ * Unwraps a Result, computing a default value from the error if it's a failure.
+ *
+ * ## When to Use
+ *
+ * Use `unwrapOrElse()` when:
+ * - The default value is expensive to compute (lazy evaluation)
+ * - You need to log or handle the error before providing a default
+ * - The default depends on the error type or cause
+ * - You want to transform the error into a success value
+ *
+ * ## Why Use This Instead of `unwrapOr`
+ *
+ * - **Lazy**: Default is only computed if needed (better performance)
+ * - **Error-aware**: You can inspect the error before providing default
+ * - **Flexible**: Default can depend on error type or cause
+ *
+ * @param r - The Result to unwrap
+ * @param fn - Function that receives the error and optional cause, returns the default value
+ * @returns The success value if successful, otherwise the result of calling `fn(error, cause)`
+ *
+ * @example
+ * ```typescript
+ * // Compute default based on error type
+ * const port = unwrapOrElse(parsePort(env.PORT), (error) => {
+ *   if (error === 'INVALID_FORMAT') return 3000;
+ *   if (error === 'OUT_OF_RANGE') return 8080;
+ *   return 4000; // default
+ * });
+ *
+ * // Log error before providing default
+ * const data = unwrapOrElse(fetchData(), (error, cause) => {
+ *   console.error('Failed to fetch:', error, cause);
+ *   return getCachedData();
+ * });
+ *
+ * // Transform error into success value
+ * const result = unwrapOrElse(operation(), (error) => {
+ *   return { success: false, reason: String(error) };
+ * });
+ * ```
+ */
+declare const unwrapOrElse: <T, E, C>(r: Result<T, E, C>, fn: (error: E, cause?: C) => T) => T;
+/**
+ * Wraps a synchronous throwing function in a Result.
+ *
+ * ## When to Use
+ *
+ * Use `from()` when:
+ * - You have a synchronous function that throws exceptions
+ * - You want to convert exceptions to typed errors
+ * - You're integrating with libraries that throw (e.g., JSON.parse, fs.readFileSync)
+ * - You need to handle errors without try/catch blocks
+ *
+ * ## Why Use This
+ *
+ * - **Type-safe errors**: Convert thrown exceptions to typed Result errors
+ * - **No try/catch**: Cleaner code without nested try/catch blocks
+ * - **Composable**: Results can be chained with `andThen`, `map`, etc.
+ * - **Explicit errors**: Forces you to handle errors explicitly
+ *
+ * @param fn - The synchronous function to execute (may throw)
+ * @returns A Result with the function's return value or the thrown error
+ *
+ * @example
+ * ```typescript
+ * // Wrap JSON.parse
+ * const parsed = from(() => JSON.parse('{"key": "value"}'));
+ * // parsed: { ok: true, value: { key: "value" } }
+ *
+ * const error = from(() => JSON.parse('invalid'));
+ * // error: { ok: false, error: SyntaxError }
+ * ```
+ */
+declare function from<T>(fn: () => T): Result<T, unknown>;
+/**
+ * Wraps a synchronous throwing function in a Result with custom error mapping.
+ *
+ * Use this overload when you want to map thrown exceptions to your typed error union.
+ *
+ * @param fn - The synchronous function to execute (may throw)
+ * @param onError - Function to map the thrown exception to a typed error
+ * @returns A Result with the function's return value or the mapped error
+ *
+ * @example
+ * ```typescript
+ * // Map exceptions to typed errors
+ * const parsed = from(
+ *   () => JSON.parse(input),
+ *   (cause) => ({ type: 'PARSE_ERROR' as const, cause })
+ * );
+ * // parsed.error: { type: 'PARSE_ERROR', cause: SyntaxError }
+ *
+ * // Map to simple error codes
+ * const value = from(
+ *   () => riskyOperation(),
+ *   () => 'OPERATION_FAILED' as const
+ * );
+ * ```
+ */
+declare function from<T, E>(fn: () => T, onError: (cause: unknown) => E): Result<T, E>;
+/**
+ * Wraps a Promise in a Result, converting rejections to errors.
+ *
+ * ## When to Use
+ *
+ * Use `fromPromise()` when:
+ * - You have an existing Promise that might reject
+ * - You want to convert Promise rejections to typed errors
+ * - You're working with libraries that return Promises (fetch, database clients)
+ * - You need to handle rejections without .catch() chains
+ *
+ * ## Why Use This
+ *
+ * - **Type-safe errors**: Convert Promise rejections to typed Result errors
+ * - **Composable**: Results can be chained with `andThen`, `map`, etc.
+ * - **Explicit handling**: Forces you to handle errors explicitly
+ * - **No .catch() chains**: Cleaner than Promise.catch() patterns
+ *
+ * @param promise - The Promise to await (may reject)
+ * @returns A Promise resolving to a Result with the resolved value or rejection reason
+ *
+ * @example
+ * ```typescript
+ * // Wrap fetch
+ * const result = await fromPromise(
+ *   fetch('/api').then(r => r.json())
+ * );
+ * // result.ok: true if fetch succeeded, false if rejected
+ * ```
+ */
+declare function fromPromise<T>(promise: Promise<T>): AsyncResult<T, unknown>;
+/**
+ * Wraps a Promise in a Result with custom error mapping.
+ *
+ * Use this overload when you want to map Promise rejections to your typed error union.
+ *
+ * @param promise - The Promise to await (may reject)
+ * @param onError - Function to map the rejection reason to a typed error
+ * @returns A Promise resolving to a Result with the resolved value or mapped error
+ *
+ * @example
+ * ```typescript
+ * // Map fetch errors to typed errors
+ * const result = await fromPromise(
+ *   fetch('/api').then(r => {
+ *     if (!r.ok) throw new Error(`HTTP ${r.status}`);
+ *     return r.json();
+ *   }),
+ *   () => 'FETCH_FAILED' as const
+ * );
+ * // result.error: 'FETCH_FAILED' if fetch failed
+ *
+ * // Map with error details
+ * const data = await fromPromise(
+ *   db.query(sql),
+ *   (cause) => ({ type: 'DB_ERROR' as const, message: String(cause) })
+ * );
+ * ```
+ */
+declare function fromPromise<T, E>(promise: Promise<T>, onError: (cause: unknown) => E): AsyncResult<T, E>;
+/**
+ * Wraps an async function in a Result, catching both thrown exceptions and Promise rejections.
+ *
+ * ## When to Use
+ *
+ * Use `tryAsync()` when:
+ * - You have an async function that might throw or reject
+ * - You want to convert both exceptions and rejections to typed errors
+ * - You're creating new async functions (use `fromPromise` for existing Promises)
+ * - You need to handle errors without try/catch or .catch()
+ *
+ * ## Why Use This Instead of `fromPromise`
+ *
+ * - **Function form**: Takes a function, not a Promise (lazy evaluation)
+ * - **Catches both**: Handles both thrown exceptions and Promise rejections
+ * - **Cleaner syntax**: No need to wrap in Promise manually
+ *
+ * @param fn - The async function to execute (may throw or reject)
+ * @returns A Promise resolving to a Result with the function's return value or error
+ *
+ * @example
+ * ```typescript
+ * // Wrap async function
+ * const result = await tryAsync(async () => {
+ *   const data = await fetchData();
+ *   return processData(data);
+ * });
+ * ```
+ */
+declare function tryAsync<T>(fn: () => Promise<T>): AsyncResult<T, unknown>;
+/**
+ * Wraps an async function in a Result with custom error mapping.
+ *
+ * Use this overload when you want to map errors to your typed error union.
+ *
+ * @param fn - The async function to execute (may throw or reject)
+ * @param onError - Function to map the error (exception or rejection) to a typed error
+ * @returns A Promise resolving to a Result with the function's return value or mapped error
+ *
+ * @example
+ * ```typescript
+ * // Map errors to typed errors
+ * const result = await tryAsync(
+ *   async () => await fetchData(),
+ *   () => 'FETCH_ERROR' as const
+ * );
+ *
+ * // Map with error details
+ * const data = await tryAsync(
+ *   async () => await processFile(path),
+ *   (cause) => ({ type: 'PROCESSING_ERROR' as const, cause })
+ * );
+ * ```
+ */
+declare function tryAsync<T, E>(fn: () => Promise<T>, onError: (cause: unknown) => E): AsyncResult<T, E>;
+/**
+ * Converts a nullable value to a Result.
+ *
+ * ## When to Use
+ *
+ * Use `fromNullable()` when:
+ * - You have a value that might be `null` or `undefined`
+ * - You want to treat null/undefined as an error case
+ * - You're working with APIs that return nullable values (DOM APIs, optional properties)
+ * - You want to avoid null checks scattered throughout your code
+ *
+ * ## Why Use This
+ *
+ * - **Type-safe**: Converts nullable types to non-nullable Results
+ * - **Explicit errors**: Forces you to handle null/undefined cases
+ * - **Composable**: Results can be chained with `andThen`, `map`, etc.
+ * - **No null checks**: Eliminates need for `if (value == null)` checks
+ *
+ * @param value - The value that may be null or undefined
+ * @param onNull - Function that returns an error when value is null/undefined
+ * @returns A Result with the value if not null/undefined, otherwise the error from `onNull`
+ *
+ * @example
+ * ```typescript
+ * // Convert DOM element lookup
+ * const element = fromNullable(
+ *   document.getElementById('app'),
+ *   () => 'ELEMENT_NOT_FOUND' as const
+ * );
+ *
+ * // Convert optional property
+ * const userId = fromNullable(
+ *   user.id,
+ *   () => 'USER_ID_MISSING' as const
+ * );
+ *
+ * // Convert database query result
+ * const record = fromNullable(
+ *   await db.find(id),
+ *   () => ({ type: 'NOT_FOUND' as const, id })
+ * );
+ * ```
+ */
+declare function fromNullable<T, E>(value: T | null | undefined, onNull: () => E): Result<T, E>;
+/**
+ * Transforms the success value of a Result.
+ *
+ * ## When to Use
+ *
+ * Use `map()` when:
+ * - You need to transform a success value to another type
+ * - You want to apply a pure function to the value
+ * - You're building a pipeline of transformations
+ * - The transformation cannot fail (use `andThen` if it can fail)
+ *
+ * ## Why Use This
+ *
+ * - **Functional style**: Composable, chainable transformations
+ * - **Error-preserving**: Errors pass through unchanged
+ * - **Type-safe**: TypeScript tracks the transformation
+ * - **No unwrapping**: Avoids manual `if (r.ok)` checks
+ *
+ * @param r - The Result to transform
+ * @param fn - Pure function that transforms the success value (must not throw)
+ * @returns A new Result with the transformed value, or the original error if `r` was an error
+ *
+ * @example
+ * ```typescript
+ * // Transform numeric value
+ * const doubled = map(ok(21), n => n * 2);
+ * // doubled: { ok: true, value: 42 }
+ *
+ * // Transform object property
+ * const name = map(fetchUser(id), user => user.name);
+ *
+ * // Chain transformations
+ * const formatted = map(
+ *   map(parseNumber(input), n => n * 2),
+ *   n => `Result: ${n}`
+ * );
+ * ```
+ */
+declare function map<T, U, E, C>(r: Result<T, E, C>, fn: (value: T) => U): Result<U, E, C>;
+/**
+ * Transforms the error value of a Result.
+ *
+ * ## When to Use
+ *
+ * Use `mapError()` when:
+ * - You need to normalize or transform error types
+ * - You want to convert errors to a different error type
+ * - You're building error handling pipelines
+ * - You need to format error messages or codes
+ *
+ * ## Why Use This
+ *
+ * - **Error normalization**: Convert errors to a common format
+ * - **Type transformation**: Change error type while preserving value type
+ * - **Composable**: Can be chained with other transformers
+ * - **Success-preserving**: Success values pass through unchanged
+ *
+ * @param r - The Result to transform
+ * @param fn - Function that transforms the error value (must not throw)
+ * @returns A new Result with the original value, or the transformed error if `r` was an error
+ *
+ * @example
+ * ```typescript
+ * // Normalize error codes
+ * const normalized = mapError(err('not_found'), e => e.toUpperCase());
+ * // normalized: { ok: false, error: 'NOT_FOUND' }
+ *
+ * // Convert error types
+ * const typed = mapError(
+ *   err('404'),
+ *   code => ({ type: 'HTTP_ERROR' as const, status: parseInt(code) })
+ * );
+ *
+ * // Format error messages
+ * const formatted = mapError(
+ *   err('PARSE_ERROR'),
+ *   code => `Failed to parse: ${code}`
+ * );
+ * ```
+ */
+declare function mapError<T, E, F, C>(r: Result<T, E, C>, fn: (error: E) => F): Result<T, F, C>;
+/**
+ * Pattern matches on a Result, calling the appropriate handler.
+ *
+ * ## When to Use
+ *
+ * Use `match()` when:
+ * - You need to handle both success and error cases
+ * - You want to transform a Result to a different type
+ * - You need exhaustive handling (both cases must be handled)
+ * - You're building user-facing messages or responses
+ *
+ * ## Why Use This
+ *
+ * - **Exhaustive**: Forces you to handle both success and error cases
+ * - **Type-safe**: TypeScript ensures both handlers are provided
+ * - **Functional**: Pattern matching style, similar to Rust's `match` or Haskell's `case`
+ * - **Single expression**: Can be used in expressions, not just statements
+ *
+ * @param r - The Result to match
+ * @param handlers - Object with `ok` and `err` handler functions
+ * @param handlers.ok - Function called with the success value
+ * @param handlers.err - Function called with the error and optional cause
+ * @returns The return value of the appropriate handler (both must return the same type `R`)
+ *
+ * @example
+ * ```typescript
+ * // Build user-facing messages
+ * const message = match(result, {
+ *   ok: (user) => `Hello ${user.name}`,
+ *   err: (error) => `Error: ${error}`,
+ * });
+ *
+ * // Transform to API response
+ * const response = match(operation(), {
+ *   ok: (data) => ({ status: 200, body: data }),
+ *   err: (error) => ({ status: 400, error: String(error) }),
+ * });
+ *
+ * // Handle with cause
+ * const log = match(result, {
+ *   ok: (value) => console.log('Success:', value),
+ *   err: (error, cause) => console.error('Error:', error, cause),
+ * });
+ * ```
+ */
+declare function match<T, E, C, R>(r: Result<T, E, C>, handlers: {
+    ok: (value: T) => R;
+    err: (error: E, cause?: C) => R;
+}): R;
+/**
+ * Chains Results together (flatMap/monadic bind).
+ *
+ * ## When to Use
+ *
+ * Use `andThen()` when:
+ * - You need to chain operations that can fail
+ * - The next operation depends on the previous success value
+ * - You're building a pipeline of dependent operations
+ * - You want to avoid nested `if (r.ok)` checks
+ *
+ * ## Why Use This Instead of `map`
+ *
+ * - **Can fail**: The chained function returns a Result (can fail)
+ * - **Short-circuits**: If first Result fails, second operation never runs
+ * - **Error accumulation**: Errors from both operations are in the union
+ * - **Composable**: Can chain multiple operations together
+ *
+ * ## Common Pattern
+ *
+ * This is the fundamental building block for Result pipelines:
+ * ```typescript
+ * andThen(operation1(), value1 =>
+ *   andThen(operation2(value1), value2 =>
+ *     ok({ value1, value2 })
+ *   )
+ * )
+ * ```
+ *
+ * @param r - The first Result
+ * @param fn - Function that takes the success value and returns a new Result (may fail)
+ * @returns The Result from `fn` if `r` was successful, otherwise the original error
+ *
+ * @example
+ * ```typescript
+ * // Chain dependent operations
+ * const userPosts = andThen(
+ *   fetchUser('1'),
+ *   user => fetchPosts(user.id)
+ * );
+ *
+ * // Build complex pipelines
+ * const result = andThen(parseInput(input), parsed =>
+ *   andThen(validate(parsed), validated =>
+ *     process(validated)
+ *   )
+ * );
+ *
+ * // Chain with different error types
+ * const data = andThen(
+ *   fetchUser(id), // Returns Result<User, 'FETCH_ERROR'>
+ *   user => fetchPosts(user.id) // Returns Result<Post[], 'NOT_FOUND'>
+ * );
+ * // data.error: 'FETCH_ERROR' | 'NOT_FOUND'
+ * ```
+ */
+declare function andThen<T, U, E, F, C1, C2>(r: Result<T, E, C1>, fn: (value: T) => Result<U, F, C2>): Result<U, E | F, C1 | C2>;
+/**
+ * Executes a side effect on a successful Result without changing it.
+ *
+ * ## When to Use
+ *
+ * Use `tap()` when:
+ * - You need to log, debug, or observe success values
+ * - You want to perform side effects in a pipeline
+ * - You need to mutate external state based on success
+ * - You're debugging and want to inspect values without breaking the chain
+ *
+ * ## Why Use This
+ *
+ * - **Non-breaking**: Doesn't change the Result, just performs side effect
+ * - **Composable**: Can be inserted anywhere in a pipeline
+ * - **Type-preserving**: Returns the same Result type
+ * - **Lazy**: Side effect only runs if Result is successful
+ *
+ * @param r - The Result to tap
+ * @param fn - Side effect function called with the success value (return value ignored)
+ * @returns The original Result unchanged (for chaining)
+ *
+ * @example
+ * ```typescript
+ * // Log success values
+ * const logged = tap(result, user => console.log('Got user:', user.name));
+ * // logged === result, but console.log was called
+ *
+ * // Debug in pipeline
+ * const debugged = pipe(
+ *   fetchUser(id),
+ *   r => tap(r, user => console.log('Fetched:', user)),
+ *   r => map(r, user => user.name)
+ * );
+ *
+ * // Mutate external state
+ * const tracked = tap(result, data => {
+ *   analytics.track('operation_success', data);
+ * });
+ * ```
+ */
+declare function tap<T, E, C>(r: Result<T, E, C>, fn: (value: T) => void): Result<T, E, C>;
+/**
+ * Executes a side effect on an error Result without changing it.
+ *
+ * ## When to Use
+ *
+ * Use `tapError()` when:
+ * - You need to log, debug, or observe error values
+ * - You want to perform side effects on errors in a pipeline
+ * - You need to report errors to external systems (logging, monitoring)
+ * - You're debugging and want to inspect errors without breaking the chain
+ *
+ * ## Why Use This
+ *
+ * - **Non-breaking**: Doesn't change the Result, just performs side effect
+ * - **Composable**: Can be inserted anywhere in a pipeline
+ * - **Type-preserving**: Returns the same Result type
+ * - **Lazy**: Side effect only runs if Result is an error
+ *
+ * @param r - The Result to tap
+ * @param fn - Side effect function called with the error and optional cause (return value ignored)
+ * @returns The original Result unchanged (for chaining)
+ *
+ * @example
+ * ```typescript
+ * // Log errors
+ * const logged = tapError(result, (error, cause) => {
+ *   console.error('Error:', error, cause);
+ * });
+ *
+ * // Report to error tracking
+ * const tracked = tapError(result, (error, cause) => {
+ *   errorTracker.report(error, cause);
+ * });
+ *
+ * // Debug in pipeline
+ * const debugged = pipe(
+ *   operation(),
+ *   r => tapError(r, (err, cause) => console.error('Failed:', err)),
+ *   r => mapError(r, err => 'FORMATTED_ERROR')
+ * );
+ * ```
+ */
+declare function tapError<T, E, C>(r: Result<T, E, C>, fn: (error: E, cause?: C) => void): Result<T, E, C>;
+/**
+ * Transforms the success value of a Result, catching any errors thrown by the transform.
+ *
+ * ## When to Use
+ *
+ * Use `mapTry()` when:
+ * - Your transform function might throw exceptions
+ * - You want to convert transform errors to typed errors
+ * - You're working with libraries that throw (e.g., JSON.parse, Date parsing)
+ * - You need to handle both Result errors and transform exceptions
+ *
+ * ## Why Use This Instead of `map`
+ *
+ * - **Exception-safe**: Catches exceptions from the transform function
+ * - **Error mapping**: Converts thrown exceptions to typed errors
+ * - **Dual error handling**: Handles both Result errors and transform exceptions
+ *
+ * @param result - The Result to transform
+ * @param transform - Function to transform the success value (may throw exceptions)
+ * @param onError - Function to map thrown exceptions to a typed error
+ * @returns A Result with:
+ *   - Transformed value if both Result and transform succeed
+ *   - Original error if Result was an error
+ *   - Transform error if transform threw an exception
+ *
+ * @example
+ * ```typescript
+ * // Safe JSON parsing
+ * const parsed = mapTry(
+ *   ok('{"key": "value"}'),
+ *   JSON.parse,
+ *   () => 'PARSE_ERROR' as const
+ * );
+ *
+ * // Safe date parsing
+ * const date = mapTry(
+ *   ok('2024-01-01'),
+ *   str => new Date(str),
+ *   () => 'INVALID_DATE' as const
+ * );
+ *
+ * // Transform with error details
+ * const processed = mapTry(
+ *   result,
+ *   value => riskyTransform(value),
+ *   (cause) => ({ type: 'TRANSFORM_ERROR' as const, cause })
+ * );
+ * ```
+ */
+declare function mapTry<T, U, E, F, C>(result: Result<T, E, C>, transform: (value: T) => U, onError: (cause: unknown) => F): Result<U, E | F, C | unknown>;
+/**
+ * Transforms the error value of a Result, catching any errors thrown by the transform.
+ *
+ * ## When to Use
+ *
+ * Use `mapErrorTry()` when:
+ * - Your error transform function might throw exceptions
+ * - You're doing complex error transformations (e.g., string formatting, object construction)
+ * - You want to handle both Result errors and transform exceptions
+ * - You need to safely normalize error types
+ *
+ * ## Why Use This Instead of `mapError`
+ *
+ * - **Exception-safe**: Catches exceptions from the error transform function
+ * - **Error mapping**: Converts thrown exceptions to typed errors
+ * - **Dual error handling**: Handles both Result errors and transform exceptions
+ *
+ * @param result - The Result to transform
+ * @param transform - Function to transform the error value (may throw exceptions)
+ * @param onError - Function to map thrown exceptions to a typed error
+ * @returns A Result with:
+ *   - Original value if Result was successful
+ *   - Transformed error if both Result was error and transform succeeded
+ *   - Transform error if transform threw an exception
+ *
+ * @example
+ * ```typescript
+ * // Safe error formatting
+ * const formatted = mapErrorTry(
+ *   err('not_found'),
+ *   e => e.toUpperCase(), // Might throw if e is not a string
+ *   () => 'FORMAT_ERROR' as const
+ * );
+ *
+ * // Complex error transformation
+ * const normalized = mapErrorTry(
+ *   result,
+ *   error => ({ type: 'NORMALIZED', message: String(error) }),
+ *   () => 'TRANSFORM_ERROR' as const
+ * );
+ * ```
+ */
+declare function mapErrorTry<T, E, F, G, C>(result: Result<T, E, C>, transform: (error: E) => F, onError: (cause: unknown) => G): Result<T, F | G, C | unknown>;
+type AllValues<T extends readonly Result<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: T[K] extends Result<infer V, unknown, unknown> ? V : never;
+};
+type AllErrors<T extends readonly Result<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: T[K] extends Result<unknown, infer E, unknown> ? E : never;
+}[number];
+type AllCauses<T extends readonly Result<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: T[K] extends Result<unknown, unknown, infer C> ? C : never;
+}[number];
+/**
+ * Combines multiple Results into one, requiring all to succeed.
+ *
+ * ## When to Use
+ *
+ * Use `all()` when:
+ * - You have multiple independent operations that all must succeed
+ * - You want to short-circuit on the first error (fail-fast)
+ * - You need all values together (e.g., combining API responses)
+ * - Performance matters (stops on first error, doesn't wait for all)
+ *
+ * ## Why Use This
+ *
+ * - **Fail-fast**: Stops immediately on first error (better performance)
+ * - **Type-safe**: TypeScript infers the array type from input
+ * - **Short-circuit**: Doesn't evaluate remaining Results after error
+ * - **Composable**: Can be chained with other operations
+ *
+ * ## Important
+ *
+ * - **Short-circuits**: Returns first error immediately, doesn't wait for all Results
+ * - **All must succeed**: If any Result fails, the entire operation fails
+ * - **Use `allSettled`**: If you need to collect all errors (e.g., form validation)
+ *
+ * @param results - Array of Results to combine (all must succeed)
+ * @returns A Result with an array of all success values, or the first error encountered
+ *
+ * @example
+ * ```typescript
+ * // Combine multiple successful Results
+ * const combined = all([ok(1), ok(2), ok(3)]);
+ * // combined: { ok: true, value: [1, 2, 3] }
+ *
+ * // Short-circuits on first error
+ * const error = all([ok(1), err('ERROR'), ok(3)]);
+ * // error: { ok: false, error: 'ERROR' }
+ * // Note: ok(3) is never evaluated
+ *
+ * // Combine API responses
+ * const data = all([
+ *   fetchUser(id),
+ *   fetchPosts(id),
+ *   fetchComments(id)
+ * ]);
+ * // data.value: [user, posts, comments] if all succeed
+ * ```
+ */
+declare function all<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): Result<AllValues<T>, AllErrors<T>, AllCauses<T>>;
+/**
+ * Combines multiple Results or Promises of Results into one (async version of `all`).
+ *
+ * ## When to Use
+ *
+ * Use `allAsync()` when:
+ * - You have multiple async operations that all must succeed
+ * - You want to run operations in parallel (better performance)
+ * - You want to short-circuit on the first error (fail-fast)
+ * - You need all values together from parallel operations
+ *
+ * ## Why Use This Instead of `all`
+ *
+ * - **Parallel execution**: All Promises start immediately (faster)
+ * - **Async support**: Works with Promises and AsyncResults
+ * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
+ *
+ * ## Important
+ *
+ * - **Short-circuits**: Returns first error immediately, cancels remaining operations
+ * - **Parallel**: All operations start simultaneously (unlike sequential `andThen`)
+ * - **Use `allSettledAsync`**: If you need to collect all errors
+ *
+ * @param results - Array of Results or Promises of Results to combine (all must succeed)
+ * @returns A Promise resolving to a Result with an array of all success values, or the first error
+ *
+ * @example
+ * ```typescript
+ * // Parallel API calls
+ * const combined = await allAsync([
+ *   fetchUser('1'),
+ *   fetchPosts('1'),
+ *   fetchComments('1')
+ * ]);
+ * // All three calls start simultaneously
+ * // combined: { ok: true, value: [user, posts, comments] } if all succeed
+ *
+ * // Mix Results and Promises
+ * const data = await allAsync([
+ *   ok(cachedUser), // Already resolved
+ *   fetchPosts(userId), // Promise
+ * ]);
+ * ```
+ */
+declare function allAsync<const T extends readonly (Result<unknown, unknown, unknown> | Promise<Result<unknown, unknown, unknown>>)[]>(results: T): Promise<Result<{
+    [K in keyof T]: T[K] extends Result<infer V, unknown, unknown> | Promise<Result<infer V, unknown, unknown>> ? V : never;
+}, {
+    [K in keyof T]: T[K] extends Result<unknown, infer E, unknown> | Promise<Result<unknown, infer E, unknown>> ? E : never;
+}[number] | PromiseRejectedError, {
+    [K in keyof T]: T[K] extends Result<unknown, unknown, infer C> | Promise<Result<unknown, unknown, infer C>> ? C : never;
+}[number] | PromiseRejectionCause>>;
+type SettledError<E, C = unknown> = {
+    error: E;
+    cause?: C;
+};
+type AllSettledResult<T extends readonly Result<unknown, unknown, unknown>[]> = Result<AllValues<T>, SettledError<AllErrors<T>, AllCauses<T>>[]>;
+/**
+ * Combines multiple Results, collecting all errors instead of short-circuiting.
+ *
+ * ## When to Use
+ *
+ * Use `allSettled()` when:
+ * - You need to see ALL errors, not just the first one
+ * - You're doing form validation (show all field errors)
+ * - You want to collect partial results (some succeed, some fail)
+ * - You need to process all Results regardless of failures
+ *
+ * ## Why Use This Instead of `all`
+ *
+ * - **Collects all errors**: Returns array of all errors, not just first
+ * - **No short-circuit**: Evaluates all Results even if some fail
+ * - **Partial success**: Can see which operations succeeded and which failed
+ * - **Better UX**: Show users all validation errors at once
+ *
+ * ## Important
+ *
+ * - **No short-circuit**: All Results are evaluated (slower if many fail early)
+ * - **Error array**: Returns array of `{ error, cause }` objects, not single error
+ * - **Use `all`**: If you want fail-fast behavior (better performance)
+ *
+ * @param results - Array of Results to combine (all are evaluated)
+ * @returns A Result with:
+ *   - Array of all success values if all succeed
+ *   - Array of `{ error, cause }` objects if any fail
+ *
+ * @example
+ * ```typescript
+ * // Form validation - show all errors
+ * const validated = allSettled([
+ *   validateEmail(email),
+ *   validatePassword(password),
+ *   validateAge(age),
+ * ]);
+ * // If email and password fail:
+ * // { ok: false, error: [
+ * //   { error: 'INVALID_EMAIL' },
+ * //   { error: 'WEAK_PASSWORD' }
+ * // ]}
+ *
+ * // Collect partial results
+ * const results = allSettled([
+ *   fetchUser('1'), // succeeds
+ *   fetchUser('2'), // fails
+ *   fetchUser('3'), // succeeds
+ * ]);
+ * // Can see which succeeded and which failed
+ * ```
+ */
+declare function allSettled<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): AllSettledResult<T>;
+/**
+ * Splits an array of Results into separate arrays of success values and errors.
+ *
+ * ## When to Use
+ *
+ * Use `partition()` when:
+ * - You have an array of Results and need to separate successes from failures
+ * - You want to process successes and errors separately
+ * - You're collecting results from multiple operations (some may fail)
+ * - You need to handle partial success scenarios
+ *
+ * ## Why Use This
+ *
+ * - **Simple separation**: One call splits successes and errors
+ * - **Type-safe**: TypeScript knows `values` is `T[]` and `errors` is `E[]`
+ * - **No unwrapping**: Doesn't require manual `if (r.ok)` checks
+ * - **Preserves order**: Maintains original array order in both arrays
+ *
+ * ## Common Pattern
+ *
+ * Often used after `Promise.all()` with Results:
+ * ```typescript
+ * const results = await Promise.all(ids.map(id => fetchUser(id)));
+ * const { values: users, errors } = partition(results);
+ * // Process successful users, handle errors separately
+ * ```
+ *
+ * @param results - Array of Results to partition
+ * @returns An object with:
+ *   - `values`: Array of all success values (type `T[]`)
+ *   - `errors`: Array of all error values (type `E[]`)
+ *
+ * @example
+ * ```typescript
+ * // Split successes and errors
+ * const results = [ok(1), err('ERROR_1'), ok(3), err('ERROR_2')];
+ * const { values, errors } = partition(results);
+ * // values: [1, 3]
+ * // errors: ['ERROR_1', 'ERROR_2']
+ *
+ * // Process batch operations
+ * const userResults = await Promise.all(userIds.map(id => fetchUser(id)));
+ * const { values: users, errors: fetchErrors } = partition(userResults);
+ *
+ * // Process successful users
+ * users.forEach(user => processUser(user));
+ *
+ * // Handle errors
+ * fetchErrors.forEach(error => logError(error));
+ * ```
+ */
+declare function partition<T, E, C>(results: readonly Result<T, E, C>[]): {
+    values: T[];
+    errors: E[];
+};
+type AnyValue<T extends readonly Result<unknown, unknown, unknown>[]> = T[number] extends Result<infer U, unknown, unknown> ? U : never;
+type AnyErrors<T extends readonly Result<unknown, unknown, unknown>[]> = {
+    -readonly [K in keyof T]: T[K] extends Result<unknown, infer E, unknown> ? E : never;
+}[number];
+type AnyCauses<T extends readonly Result<unknown, unknown, unknown>[]> = {
+    -readonly [K in keyof T]: T[K] extends Result<unknown, unknown, infer C> ? C : never;
+}[number];
+/**
+ * Returns the first successful Result from an array (succeeds fast).
+ *
+ * ## When to Use
+ *
+ * Use `any()` when:
+ * - You have multiple fallback options and need the first that succeeds
+ * - You're trying multiple strategies (e.g., cache → DB → API)
+ * - You want fail-fast success (stops on first success)
+ * - You have redundant data sources and any one will do
+ *
+ * ## Why Use This
+ *
+ * - **Succeeds fast**: Returns immediately on first success (better performance)
+ * - **Fallback pattern**: Perfect for trying multiple options
+ * - **Short-circuits**: Stops evaluating after first success
+ * - **Type-safe**: TypeScript infers the success type
+ *
+ * ## Important
+ *
+ * - **First success wins**: Returns first successful Result, ignores rest
+ * - **All errors**: If all fail, returns first error (not all errors)
+ * - **Empty array**: Returns `EmptyInputError` if array is empty
+ * - **Use `all`**: If you need ALL to succeed
+ *
+ * @param results - Array of Results to check (evaluated in order)
+ * @returns The first successful Result, or first error if all fail, or `EmptyInputError` if empty
+ *
+ * @example
+ * ```typescript
+ * // Try multiple fallback strategies
+ * const data = any([
+ *   fetchFromCache(id),
+ *   fetchFromDB(id),
+ *   fetchFromAPI(id)
+ * ]);
+ * // Returns first that succeeds
+ *
+ * // Try multiple formats
+ * const parsed = any([
+ *   parseJSON(input),
+ *   parseXML(input),
+ *   parseYAML(input)
+ * ]);
+ *
+ * // All errors case
+ * const allErrors = any([err('A'), err('B'), err('C')]);
+ * // allErrors: { ok: false, error: 'A' } (first error)
+ * ```
+ */
+declare function any<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): Result<AnyValue<T>, AnyErrors<T> | EmptyInputError, AnyCauses<T>>;
+type AnyAsyncValue<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = Awaited<T[number]> extends Result<infer U, unknown, unknown> ? U : never;
+type AnyAsyncErrors<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
+    -readonly [K in keyof T]: Awaited<T[K]> extends Result<unknown, infer E, unknown> ? E : never;
+}[number];
+type AnyAsyncCauses<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
+    -readonly [K in keyof T]: Awaited<T[K]> extends Result<unknown, unknown, infer C> ? C : never;
+}[number];
+/**
+ * Returns the first successful Result from an array of Results or Promises (async version of `any`).
+ *
+ * ## When to Use
+ *
+ * Use `anyAsync()` when:
+ * - You have multiple async fallback options and need the first that succeeds
+ * - You're trying multiple async strategies in parallel (cache → DB → API)
+ * - You want fail-fast success from parallel operations
+ * - You have redundant async data sources and any one will do
+ *
+ * ## Why Use This Instead of `any`
+ *
+ * - **Parallel execution**: All Promises start immediately (faster)
+ * - **Async support**: Works with Promises and AsyncResults
+ * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
+ *
+ * ## Important
+ *
+ * - **First success wins**: Returns first successful Result (from any Promise)
+ * - **Parallel**: All operations run simultaneously
+ * - **All errors**: If all fail, returns first error encountered
+ *
+ * @param results - Array of Results or Promises of Results to check (all start in parallel)
+ * @returns A Promise resolving to the first successful Result, or first error if all fail
+ *
+ * @example
+ * ```typescript
+ * // Try multiple async fallbacks in parallel
+ * const data = await anyAsync([
+ *   fetchFromCache(id), // Fastest wins
+ *   fetchFromDB(id),
+ *   fetchFromAPI(id)
+ * ]);
+ *
+ * // Try multiple API endpoints
+ * const response = await anyAsync([
+ *   fetch('/api/v1/data'),
+ *   fetch('/api/v2/data'),
+ *   fetch('/backup-api/data')
+ * ]);
+ * ```
+ */
+declare function anyAsync<const T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]>(results: T): Promise<Result<AnyAsyncValue<T>, AnyAsyncErrors<T> | EmptyInputError | PromiseRejectedError, AnyAsyncCauses<T> | PromiseRejectionCause>>;
+type AllAsyncValues<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: Awaited<T[K]> extends Result<infer V, unknown, unknown> ? V : never;
+};
+type AllAsyncErrors<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: Awaited<T[K]> extends Result<unknown, infer E, unknown> ? E : never;
+}[number];
+type AllAsyncCauses<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
+    [K in keyof T]: Awaited<T[K]> extends Result<unknown, unknown, infer C> ? C : never;
+}[number];
+/**
+ * Combines multiple Results or Promises of Results, collecting all errors (async version of `allSettled`).
+ *
+ * ## When to Use
+ *
+ * Use `allSettledAsync()` when:
+ * - You have multiple async operations and need ALL errors
+ * - You're doing async form validation (show all field errors)
+ * - You want to run operations in parallel and collect all results
+ * - You need partial results from parallel operations
+ *
+ * ## Why Use This Instead of `allSettled`
+ *
+ * - **Parallel execution**: All Promises start immediately (faster)
+ * - **Async support**: Works with Promises and AsyncResults
+ * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
+ *
+ * ## Important
+ *
+ * - **No short-circuit**: All operations complete (even if some fail)
+ * - **Parallel**: All operations run simultaneously
+ * - **Error array**: Returns array of `{ error, cause }` objects
+ *
+ * @param results - Array of Results or Promises of Results to combine (all are evaluated)
+ * @returns A Promise resolving to a Result with:
+ *   - Array of all success values if all succeed
+ *   - Array of `{ error, cause }` objects if any fail
+ *
+ * @example
+ * ```typescript
+ * // Async form validation
+ * const validated = await allSettledAsync([
+ *   validateEmailAsync(email),
+ *   validatePasswordAsync(password),
+ *   checkUsernameAvailableAsync(username),
+ * ]);
+ *
+ * // Parallel API calls with error collection
+ * const results = await allSettledAsync([
+ *   fetchUser('1'),
+ *   fetchUser('2'),
+ *   fetchUser('3'),
+ * ]);
+ * // Can see which succeeded and which failed
+ * ```
+ */
+declare function allSettledAsync<const T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]>(results: T): Promise<Result<AllAsyncValues<T>, SettledError<AllAsyncErrors<T> | PromiseRejectedError, AllAsyncCauses<T> | PromiseRejectionCause>[]>>;
+
+export { type AsyncResult, type CauseOf, EARLY_EXIT_SYMBOL, type EarlyExit, type EmptyInputError, type ErrorOf, type Errors, type ExtractCause, type ExtractError, type ExtractValue, type MaybeAsyncResult, type PromiseRejectedError, type PromiseRejectionCause, type Result, type RunOptions, type RunOptionsWithCatch, type RunOptionsWithoutCatch, type RunStep, type SettledError, type StepFailureMeta, type StepOptions, type UnexpectedCause, type UnexpectedError, type UnexpectedStepFailureCause, UnwrapError, type WorkflowEvent, all, allAsync, allSettled, allSettledAsync, andThen, any, anyAsync, createEarlyExit, err, from, fromNullable, fromPromise, isEarlyExit, isErr, isOk, isUnexpectedError, map, mapError, mapErrorTry, mapTry, match, ok, partition, run, tap, tapError, tryAsync, unwrap, unwrapOr, unwrapOrElse };