@jagreehal/workflow 1.1.0 → 1.3.0

package/dist/core.js.map

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