awaitly 1.34.0 → 2.0.0

package/dist/tagged-error.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/slugs.ts","../src/tagged-error.ts"],"sourcesContent":["/**\n * awaitly/slugs\n *\n * Source-of-truth slug namespace. Every concept that surfaces as a runtime\n * error, lint rule, static-analyzer diagnostic, visualizer event, or skill rule\n * has exactly one canonical kebab-case slug here.\n *\n * Slugs are public API. Renames are a major version bump. Adds are non-breaking.\n *\n * Categories:\n * - step-*       step() discipline\n * - workflow-*   createWorkflow / run / runWithState shape\n * - result-*     Result usage\n * - error-*      Boundary handling\n * - concurrency-* step.all/map/race vs Promise.*\n * - runtime-*    Failures only observable at runtime\n */\n\nexport const AWAITLY_SLUGS = {\n  // --- step-* ---\n  \"step-require-id\": \"step-require-id\",\n  \"step-no-immediate-execution\": \"step-no-immediate-execution\",\n  \"step-require-thunk-for-key\": \"step-require-thunk-for-key\",\n  \"step-no-bare-await\": \"step-no-bare-await\",\n  \"step-no-try-catch-wrap\": \"step-no-try-catch-wrap\",\n  \"step-stable-cache-keys\": \"step-stable-cache-keys\",\n\n  // --- workflow-* ---\n  \"workflow-no-floating\": \"workflow-no-floating\",\n  \"workflow-options-position\": \"workflow-options-position\",\n  \"workflow-callback-shape\": \"workflow-callback-shape\",\n  \"workflow-no-callable-form\": \"workflow-no-callable-form\",\n  \"workflow-no-dynamic-import\": \"workflow-no-dynamic-import\",\n\n  // --- result-* ---\n  \"result-no-floating\": \"result-no-floating\",\n  \"result-require-handling\": \"result-require-handling\",\n  \"result-no-double-wrap\": \"result-no-double-wrap\",\n  \"result-no-manual-propagation\": \"result-no-manual-propagation\",\n  \"result-no-direct-ok-err\": \"result-no-direct-ok-err\",\n\n  // --- error-* ---\n  \"error-check-unexpected-first\": \"error-check-unexpected-first\",\n  \"error-access-cause\": \"error-access-cause\",\n  \"error-normalize\": \"error-normalize\",\n  \"error-no-throw-in-deps\": \"error-no-throw-in-deps\",\n\n  // --- concurrency-* ---\n  \"concurrency-no-promise-all\": \"concurrency-no-promise-all\",\n  \"concurrency-no-promise-race\": \"concurrency-no-promise-race\",\n  \"concurrency-no-promise-allsettled\": \"concurrency-no-promise-allsettled\",\n\n  // --- runtime-* ---\n  \"runtime-step-timeout\": \"runtime-step-timeout\",\n  \"runtime-step-aborted\": \"runtime-step-aborted\",\n  \"runtime-retry-exhausted\": \"runtime-retry-exhausted\",\n  \"runtime-rate-limit\": \"runtime-rate-limit\",\n  \"runtime-circuit-open\": \"runtime-circuit-open\",\n  \"runtime-unexpected\": \"runtime-unexpected\",\n  \"runtime-resolver-not-found\": \"runtime-resolver-not-found\",\n  \"runtime-saga-compensation\": \"runtime-saga-compensation\",\n} as const;\n\n/** All canonical awaitly slugs as a string-literal union. */\nexport type AwaitlySlug = keyof typeof AWAITLY_SLUGS;\n\n/** Categories derived from slug prefixes. */\nexport type AwaitlySlugCategory =\n  | \"step\"\n  | \"workflow\"\n  | \"result\"\n  | \"error\"\n  | \"concurrency\"\n  | \"runtime\";\n\n/** Returns the category (prefix) of a slug. */\nexport function slugCategory(slug: AwaitlySlug): AwaitlySlugCategory {\n  return slug.split(\"-\")[0] as AwaitlySlugCategory;\n}\n\n/**\n * Returns the canonical docs URL for a slug. Resolves to the matching\n * anchored section on the consolidated rule index page.\n */\nexport function slugDocsUrl(slug: AwaitlySlug): string {\n  return `https://jagreehal.github.io/awaitly/rules/#${slug}`;\n}\n\n/** Type guard: is a string a known awaitly slug? */\nexport function isAwaitlySlug(value: string): value is AwaitlySlug {\n  return Object.prototype.hasOwnProperty.call(AWAITLY_SLUGS, value);\n}\n\n/** All slugs as an array. */\n// Object.keys returns string[] — cast is safe because AWAITLY_SLUGS is `as const`\n// and the module's keys are never mutated.\nexport const ALL_SLUGS: readonly AwaitlySlug[] = Object.keys(\n  AWAITLY_SLUGS\n) as AwaitlySlug[];\n","/**\n * awaitly/tagged-error\n *\n * Factory for creating tagged error types with exhaustive pattern matching.\n * Enables TypeScript to enforce that all error variants are handled.\n *\n * @example\n * ```typescript\n * // Define error types (Props via generic)\n * class NotFoundError extends TaggedError(\"NotFoundError\")<{\n *   id: string;\n *   resource: string;\n * }> {}\n *\n * // Define with type-safe message (Props inferred from callback annotation)\n * class ValidationError extends TaggedError(\"ValidationError\", {\n *   message: (p: { field: string; reason: string }) => `Invalid ${p.field}: ${p.reason}`,\n * }) {}\n *\n * // Create instances\n * const error = new NotFoundError({ id: \"123\", resource: \"User\" });\n *\n * // Runtime type check: instanceof TaggedError works!\n * console.log(error instanceof TaggedError); // true\n *\n * // Exhaustive matching\n * type AppError = NotFoundError | ValidationError;\n * const message = TaggedError.match(error as AppError, {\n *   NotFoundError: (e) => `Missing: ${e.resource} ${e.id}`,\n *   ValidationError: (e) => `Invalid ${e.field}: ${e.reason}`,\n * });\n * ```\n */\n\nimport { type AwaitlySlug, slugDocsUrl } from \"./slugs\";\n\n/**\n * Options for Error constructor (compatible with ES2022 ErrorOptions).\n */\nexport interface TaggedErrorOptions {\n  cause?: unknown;\n}\n\n/**\n * Options for TaggedError factory with type-safe message callback.\n */\nexport interface TaggedErrorCreateOptions<Props extends Record<string, unknown>> {\n  /** Custom message generator from props. Annotate parameter for type safety. */\n  message: (props: Props) => string;\n  /**\n   * Canonical awaitly slug for this error class. When set, instances carry\n   * `code`, `hint`, and `docsUrl` populated from the slugs namespace.\n   * Required together with `hint` for awaitly-system errors.\n   */\n  slug?: AwaitlySlug;\n  /**\n   * One-line \"do X instead\" guidance shown alongside the error.\n   * Required when `slug` is set.\n   */\n  hint?: string;\n}\n\n/**\n * Base interface for all tagged errors.\n */\nexport interface TaggedErrorBase extends Error {\n  readonly _tag: string;\n  /** Canonical slug for awaitly-system errors. Undefined for user errors that opt out. */\n  readonly code?: AwaitlySlug;\n  /** One-line guidance. Undefined when no slug is set. */\n  readonly hint?: string;\n  /** Canonical docs URL. Undefined when no slug is set. */\n  readonly docsUrl?: string;\n}\n\n/**\n * Internal base class for instanceof checks.\n * All TaggedError-created classes extend this.\n * @internal\n */\nclass InternalTaggedErrorBase extends Error implements TaggedErrorBase {\n  readonly _tag!: string;\n}\n\n/**\n * Instance type for factory-created TaggedErrors.\n */\ntype TaggedErrorInstance<Tag extends string, Props> = TaggedErrorBase & {\n  readonly _tag: Tag;\n} & Readonly<Props>;\n\n/**\n * Constructor args type - conditionally optional based on whether Props has required fields.\n * - If Props is empty or all properties are optional: props argument is optional\n * - If Props has any required properties: props argument is required\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-empty-object-type\ntype ConstructorArgs<Props extends Record<string, unknown>> = {} extends Props\n  ? [props?: Props | void, options?: TaggedErrorOptions]\n  : [props: Props, options?: TaggedErrorOptions];\n\n/**\n * Constructor type returned by TaggedError factory.\n */\nexport interface TaggedErrorConstructor<\n  Tag extends string,\n  Props extends Record<string, unknown>,\n> {\n  new (...args: ConstructorArgs<Props>): TaggedErrorInstance<Tag, Props>;\n  readonly prototype: TaggedErrorInstance<Tag, Props>;\n}\n\n/**\n * Generic class factory type that allows `<Props>` parameterization.\n * This enables the Effect.js-style syntax: `class X extends TaggedError(\"X\")<Props> {}`\n * @internal\n */\nexport interface TaggedErrorClassFactory<Tag extends string> {\n  new <Props extends Record<string, unknown> = Record<string, never>>(\n    ...args: ConstructorArgs<Props>\n  ): TaggedErrorInstance<Tag, Props>;\n}\n\n/**\n * Helper type to extract return type from a function type.\n * @internal\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\ntype FnReturnType<T> = T extends (...args: any[]) => infer R ? R : never;\n\n/**\n * Helper type to get union of return types from all handlers.\n * @internal\n */\ntype HandlersReturnType<H> = { [K in keyof H]: FnReturnType<H[K]> }[keyof H];\n\n/**\n * Helper type to extract keys whose values are definitely functions (not undefined).\n * Only excludes a tag from the fallback type if its handler is guaranteed to be\n * a function. Keys where the value type includes undefined are NOT excluded,\n * ensuring type safety with dynamic/conditional handlers.\n * @internal\n */\ntype DefinitelyHandledKeys<H> = {\n  [K in keyof H]-?: undefined extends H[K] ? never : K;\n}[keyof H];\n\n/**\n * Factory function to create tagged error classes.\n *\n * Two usage patterns:\n *\n * 1. **Props via generic** (default message is tag name):\n *    ```typescript\n *    class NotFoundError extends TaggedError(\"NotFoundError\")<{ id: string }> {}\n *    ```\n *\n * 2. **Props inferred from message callback** (type-safe message):\n *    ```typescript\n *    class NotFoundError extends TaggedError(\"NotFoundError\", {\n *      message: (p: { id: string }) => `Not found: ${p.id}`,\n *    }) {}\n *    ```\n *\n * Both support `instanceof TaggedError` checks at runtime.\n *\n * @param tag - The unique tag string for this error type\n * @param options - Optional configuration with message generator (annotate param for type safety)\n * @returns A class constructor that can be extended\n */\n\n// Overload 1: No options - use <Props> generic syntax, default message is tag\nfunction TaggedError<Tag extends string>(\n  tag: Tag\n): TaggedErrorClassFactory<Tag>;\n\n// Overload 2: With message option - Props inferred from callback parameter annotation\nfunction TaggedError<Tag extends string, Props extends Record<string, unknown>>(\n  tag: Tag,\n  options: TaggedErrorCreateOptions<Props>\n): TaggedErrorConstructor<Tag, Props>;\n\n// Implementation\nfunction TaggedError<Tag extends string, Props extends Record<string, unknown>>(\n  tag: Tag,\n  options?: TaggedErrorCreateOptions<Props>\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n): any {\n  return class extends InternalTaggedErrorBase {\n    override readonly _tag: Tag = tag;\n\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    constructor(props?: any, errorOptions?: TaggedErrorOptions) {\n      // Generate message: call callback if provided (even for prop-less errors), else use tag\n      const message = options?.message ? options.message(props ?? {}) : tag;\n\n      super(message);\n      this.name = tag;\n\n      // Spine fields: populate when factory was given a slug\n      if (options?.slug !== undefined) {\n        if (!options.hint) {\n          throw new TypeError(\n            `TaggedError: 'hint' is required when 'slug' is set (slug: \"${options.slug}\")`\n          );\n        }\n        Object.defineProperty(this, \"code\", {\n          value: options.slug,\n          enumerable: true,\n          writable: false,\n          configurable: false,\n        });\n        Object.defineProperty(this, \"hint\", {\n          value: options.hint,\n          enumerable: true,\n          writable: false,\n          configurable: false,\n        });\n        Object.defineProperty(this, \"docsUrl\", {\n          value: slugDocsUrl(options.slug),\n          enumerable: true,\n          writable: false,\n          configurable: false,\n        });\n      }\n\n      // Maintains proper prototype chain for instanceof checks\n      Object.setPrototypeOf(this, new.target.prototype);\n\n      // Assign props to instance, stripping reserved keys:\n      // - _tag: discriminant for pattern matching (cannot be forged)\n      // - name, message, stack: Error internals (preserve for logging/debugging)\n      // - code, hint, docsUrl: spine fields stripped when slug is set, to prevent\n      //   Object.assign from clobbering the non-configurable/non-writable own props\n      // Note: 'cause' is allowed as a user prop (common for domain errors)\n      if (props && typeof props === \"object\") {\n        let safeProps: Record<string, unknown>;\n        if (options?.slug !== undefined) {\n          const {\n            _tag: _,\n            name: _n,\n            message: _m,\n            stack: _s,\n            code: _c,\n            hint: _h,\n            docsUrl: _d,\n            ...rest\n          } = props;\n          safeProps = rest;\n        } else {\n          const {\n            _tag: _,\n            name: _n,\n            message: _m,\n            stack: _s,\n            ...rest\n          } = props;\n          safeProps = rest;\n        }\n\n        const hasUserCause = Object.prototype.hasOwnProperty.call(\n          safeProps,\n          \"cause\"\n        );\n        const userCause = hasUserCause\n          ? (safeProps as { cause?: unknown }).cause\n          : undefined;\n        if (hasUserCause) {\n          delete (safeProps as { cause?: unknown }).cause;\n        }\n\n        const hasOptionsCause = errorOptions?.cause !== undefined;\n        if (hasUserCause && hasOptionsCause) {\n          throw new TypeError(\n            \"TaggedError: cannot provide 'cause' in props when also setting ErrorOptions.cause\"\n          );\n        }\n\n        Object.assign(this, safeProps);\n\n        if (hasUserCause) {\n          (this as { cause?: unknown }).cause = userCause;\n        }\n        if (hasOptionsCause) {\n          (this as { cause?: unknown }).cause = errorOptions?.cause;\n        }\n      } else if (errorOptions?.cause !== undefined) {\n        (this as { cause?: unknown }).cause = errorOptions.cause;\n      }\n    }\n  };\n}\n\n// Add Symbol.hasInstance so `instanceof TaggedError` works\nObject.defineProperty(TaggedError, Symbol.hasInstance, {\n  value: (instance: unknown): boolean => instance instanceof InternalTaggedErrorBase,\n});\n\n/**\n * Namespace for static methods on TaggedError.\n */\n// eslint-disable-next-line @typescript-eslint/no-namespace\nnamespace TaggedError {\n  /**\n   * Type guard to check if a value is an Error instance.\n   */\n  export function isError(value: unknown): value is Error {\n    return value instanceof Error;\n  }\n\n  /**\n   * Type guard to check if a value is a TaggedError instance.\n   * Uses the same check as `instanceof TaggedError` - only genuine\n   * TaggedError instances (created via the factory) pass this guard.\n   */\n  export function isTaggedError(value: unknown): value is TaggedErrorBase {\n    return value instanceof InternalTaggedErrorBase;\n  }\n\n  /**\n   * Exhaustively matches on a tagged error, requiring handlers for all variants.\n   *\n   * TypeScript will error if any variant in the error union is not handled.\n   *\n   * @remarks When to use: You want compile-time enforcement that every tagged variant is handled.\n   *\n   * @param error - The tagged error to match\n   * @param handlers - Object mapping _tag values to handler functions\n   * @returns The return value of the matched handler\n   *\n   * @example\n   * ```typescript\n   * type AppError = NotFoundError | ValidationError;\n   *\n   * const message = TaggedError.match(error, {\n   *   NotFoundError: (e) => `Not found: ${e.id}`,\n   *   ValidationError: (e) => `Invalid: ${e.field}`,\n   * });\n   * ```\n   */\n  export function match<\n    E extends TaggedErrorBase,\n    H extends { [K in E[\"_tag\"]]: (e: Extract<E, { _tag: K }>) => unknown },\n  >(error: E, handlers: H): HandlersReturnType<H> {\n    const tag = error._tag as E[\"_tag\"];\n    const handler = handlers[tag];\n    return handler(\n      error as Extract<E, { _tag: typeof tag }>\n    ) as HandlersReturnType<H>;\n  }\n\n  /**\n   * Partially matches on a tagged error with a fallback for unhandled variants.\n   *\n   * The fallback receives variants that are NOT definitely handled. A tag is\n   * considered \"definitely handled\" only if its handler is a function (not\n   * `undefined`). This ensures type safety even with dynamic/conditional handlers:\n   *\n   * ```typescript\n   * const maybeHandle = featureFlag ? (e) => e.id : undefined;\n   * TaggedError.matchPartial(\n   *   error,\n   *   { NotFoundError: maybeHandle },  // maybeHandle might be undefined\n   *   (e) => e._tag  // e correctly includes NotFoundError\n   * );\n   * ```\n   *\n   * @param error - The tagged error to match\n   * @param handlers - Partial object mapping _tag values to handler functions\n   * @param otherwise - Fallback handler for unmatched variants\n   * @returns The return value of the matched handler or fallback\n   *\n   * @example\n   * ```typescript\n   * const message = TaggedError.matchPartial(\n   *   error,\n   *   { NotFoundError: (e) => `Not found: ${e.id}` },\n   *   (e) => `Other error: ${e.message}`\n   * );\n   * ```\n   */\n  export function matchPartial<\n    E extends TaggedErrorBase,\n    H extends Partial<{\n      [K in E[\"_tag\"]]: (e: Extract<E, { _tag: K }>) => unknown;\n    }>,\n    T,\n  >(\n    error: E,\n    handlers: H,\n    otherwise: (e: Exclude<E, { _tag: DefinitelyHandledKeys<H> }>) => T\n  ): HandlersReturnType<H> | T {\n    const tag = error._tag as E[\"_tag\"];\n    const handler = handlers[tag];\n    if (handler) {\n      return handler(\n        error as Extract<E, { _tag: typeof tag }>\n      ) as HandlersReturnType<H>;\n    }\n    return otherwise(error as Exclude<E, { _tag: DefinitelyHandledKeys<H> }>);\n  }\n}\n\nexport { TaggedError };\n\n/**\n * Helper type to extract the _tag literal type from a TaggedError.\n *\n * @example\n * ```typescript\n * class MyError extends TaggedError(\"MyError\")<{ id: string }> {}\n * type Tag = TagOf<MyError>; // \"MyError\"\n * ```\n */\nexport type TagOf<E extends TaggedErrorBase> = E[\"_tag\"];\n\n/**\n * Helper type to extract a specific variant from a TaggedError union by tag.\n *\n * @example\n * ```typescript\n * type AppError = NotFoundError | ValidationError;\n * type NotFound = ErrorByTag<AppError, \"NotFoundError\">; // NotFoundError\n * ```\n */\nexport type ErrorByTag<\n  E extends TaggedErrorBase,\n  Tag extends E[\"_tag\"],\n> = Extract<E, { _tag: Tag }>;\n\n/**\n * Reserved keys that are stripped from user props at runtime.\n * These keys cannot be used as user-defined properties:\n * - _tag: discriminant for pattern matching\n * - name, message, stack: Error internals (preserved for logging/debugging)\n * - code, hint, docsUrl: spine fields (non-configurable own properties when slug is set)\n *\n * Note: 'cause' is NOT reserved - it can be used as a user prop.\n */\ntype ReservedErrorKeys = \"_tag\" | \"name\" | \"message\" | \"stack\" | \"code\" | \"hint\" | \"docsUrl\";\n\n/**\n * Helper type to extract props from a TaggedError.\n * Excludes reserved keys that are stripped at runtime.\n *\n * @example\n * ```typescript\n * class MyError extends TaggedError(\"MyError\")<{ id: string }> {}\n * type Props = PropsOf<MyError>; // { id: string }\n *\n * // 'cause' is allowed as a user prop\n * class DomainError extends TaggedError(\"DomainError\")<{ cause: { field: string } }> {}\n * type DomainProps = PropsOf<DomainError>; // { cause: { field: string } }\n * ```\n */\nexport type PropsOf<E extends TaggedErrorBase> = Omit<E, ReservedErrorKeys>;\n"],"mappings":"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","names":["AWAITLY_SLUGS","slugDocsUrl","slug","ALL_SLUGS","AWAITLY_SLUGS","InternalTaggedErrorBase","TaggedError","tag","options","props","errorOptions","message","slugDocsUrl","safeProps","_","_n","_m","_s","_c","_h","_d","rest","hasUserCause","userCause","hasOptionsCause","instance","isError","value","isTaggedError","match","error","handlers","handler","matchPartial","otherwise"]}

package/dist/types-DQmzO9f4.d.ts

@@ -1,323 +0,0 @@
-import { c as AsyncResult } from './run-entry-Dduz-is2.js';
-
-/**
- * awaitly/streaming - Types
- *
- * Core types for Result-aware streaming in workflows.
- * All stream operations return Result types, enabling typed error handling
- * throughout the streaming pipeline.
- */
-
-/** Discriminant for stream write errors */
-declare const STREAM_WRITE_ERROR: "STREAM_WRITE_ERROR";
-/** Discriminant for stream read errors */
-declare const STREAM_READ_ERROR: "STREAM_READ_ERROR";
-/** Discriminant for stream close errors */
-declare const STREAM_CLOSE_ERROR: "STREAM_CLOSE_ERROR";
-/** Discriminant for stream store errors */
-declare const STREAM_STORE_ERROR: "STREAM_STORE_ERROR";
-/** Discriminant for stream ended marker */
-declare const STREAM_ENDED: "STREAM_ENDED";
-/** Discriminant for stream backpressure errors */
-declare const STREAM_BACKPRESSURE_ERROR: "STREAM_BACKPRESSURE_ERROR";
-/**
- * Error returned when a write operation fails.
- */
-type StreamWriteError = {
-    type: typeof STREAM_WRITE_ERROR;
-    reason: "closed" | "aborted" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned when a read operation fails.
- */
-type StreamReadError = {
-    type: typeof STREAM_READ_ERROR;
-    reason: "closed" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned when closing a stream fails.
- */
-type StreamCloseError = {
-    type: typeof STREAM_CLOSE_ERROR;
-    reason: "already_closed" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned from StreamStore operations.
- */
-type StreamStoreError = {
-    type: typeof STREAM_STORE_ERROR;
-    reason: "read_error" | "write_error" | "metadata_error" | "close_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Marker indicating stream has ended (not an error, but a terminal state).
- * Used as the "error" type when stream is exhausted.
- */
-type StreamEndedMarker = {
-    type: typeof STREAM_ENDED;
-    finalPosition: number;
-};
-/**
- * Backpressure error when writer is paused.
- */
-type StreamBackpressureError = {
-    type: typeof STREAM_BACKPRESSURE_ERROR;
-    bufferedCount: number;
-    highWaterMark: number;
-};
-/**
- * Union of all stream errors.
- */
-type StreamError = StreamWriteError | StreamReadError | StreamCloseError | StreamStoreError | StreamBackpressureError;
-/**
- * A single item in the stream with metadata.
- */
-interface StreamItem<T> {
-    /** The value stored in this stream item */
-    value: T;
-    /** Position in the stream (0-indexed) */
-    position: number;
-    /** Timestamp when item was written */
-    ts: number;
-}
-/**
- * Metadata about a stream.
- */
-interface StreamMetadata {
-    /** Unique identifier for the stream (workflowId + namespace) */
-    id: string;
-    /** Namespace within the workflow */
-    namespace: string;
-    /** Workflow ID that owns this stream */
-    workflowId: string;
-    /** Number of items in the stream */
-    length: number;
-    /** Whether the stream has been closed */
-    closed: boolean;
-    /** Timestamp when stream was created */
-    createdAt: number;
-    /** Timestamp when stream was last written to */
-    lastWriteAt?: number;
-    /** Timestamp when stream was closed */
-    closedAt?: number;
-}
-/**
- * Options for creating a writable stream.
- */
-interface StreamOptions {
-    /** Named streams (default: 'default') */
-    namespace?: string;
-    /** Backpressure threshold (default: 16) */
-    highWaterMark?: number;
-}
-/**
- * Options for creating a readable stream.
- */
-interface StreamReadOptions {
-    /** Named streams (default: 'default') */
-    namespace?: string;
-    /** Resume from position (0-indexed) */
-    startIndex?: number;
-}
-/**
- * Options for streamForEach operation.
- */
-interface StreamForEachOptions {
-    /** Name for the operation (used in events) */
-    name?: string;
-    /** Checkpoint after every N items (default: 1 = checkpoint each item) */
-    checkpointInterval?: number;
-    /** Maximum concurrent processors (default: 1 = sequential) */
-    concurrency?: number;
-}
-/**
- * Result from streamForEach operation.
- */
-interface StreamForEachResult<R> {
-    /** Results from each processed item */
-    results: R[];
-    /** Total items processed */
-    processedCount: number;
-    /** Position of last processed item */
-    lastPosition: number;
-}
-/**
- * Writable stream interface - never throws, returns Results.
- *
- * Use within a step to write values to a stream that can be consumed
- * by readers (e.g., HTTP response streaming, AI token streaming).
- *
- * @template T - Type of values written to the stream
- *
- * @example
- * ```typescript
- * const writer = step.getWritable<string>({ namespace: 'ai-response' });
- *
- * await step(() => generateAI({
- *   prompt: 'Hello',
- *   onToken: async (token) => { await writer.write(token); }
- * }), { key: 'generate' });
- *
- * await writer.close();
- * ```
- */
-interface StreamWriter<T> {
-    /**
-     * Write a value to the stream.
-     * Returns an error if the stream is closed, aborted, or store fails.
-     */
-    write(value: T): AsyncResult<void, StreamWriteError>;
-    /**
-     * Close the stream normally.
-     * Signals to readers that no more data will be written.
-     */
-    close(): AsyncResult<void, StreamCloseError>;
-    /**
-     * Abort the stream with a reason.
-     * Use for error conditions that should terminate the stream.
-     */
-    abort(reason: unknown): void;
-    /** Whether the stream is still writable */
-    readonly writable: boolean;
-    /** Current write position (number of items written) */
-    readonly position: number;
-    /** Stream namespace */
-    readonly namespace: string;
-}
-/**
- * Readable stream interface - returns STREAM_ENDED marker when complete.
- *
- * Use to consume values from a stream, with support for resuming from
- * a specific position.
- *
- * @template T - Type of values read from the stream
- *
- * @example
- * ```typescript
- * const reader = getStreamReader<string>(runId, { namespace: 'ai-response' });
- *
- * let result = await reader.read();
- * while (result.ok) {
- *   response.write(result.value);
- *   result = await reader.read();
- * }
- *
- * if (result.error.type === 'STREAM_ENDED') {
- *   console.log('Stream complete at position', result.error.finalPosition);
- * }
- * ```
- */
-interface StreamReader<T> {
-    /**
-     * Read the next value from the stream.
-     * Returns StreamEndedMarker when stream is exhausted.
-     */
-    read(): AsyncResult<T, StreamReadError | StreamEndedMarker>;
-    /**
-     * Close the reader (stop consuming).
-     * Does not affect the underlying stream.
-     */
-    close(): void;
-    /** Whether there may be more data to read */
-    readonly readable: boolean;
-    /** Current read position */
-    readonly position: number;
-    /** Stream namespace */
-    readonly namespace: string;
-}
-/** Unsubscribe function returned by subscribe */
-type Unsubscribe = () => void;
-/**
- * Storage backend for stream data.
- * Follows the same patterns as persistence.ts adapters.
- *
- * @example In-memory store
- * ```typescript
- * const store = createMemoryStreamStore();
- * ```
- *
- * @example File-based store
- * ```typescript
- * const store = createFileStreamStore({ directory: './streams', fs });
- * ```
- */
-interface StreamStore {
-    /**
-     * Append an item to the stream.
-     */
-    append<T>(workflowId: string, namespace: string, item: StreamItem<T>): AsyncResult<void, StreamStoreError>;
-    /**
-     * Read items from the stream starting at an index.
-     * @param startIndex - Position to start reading from (0-indexed)
-     * @param limit - Maximum number of items to read (default: all remaining)
-     */
-    read<T>(workflowId: string, namespace: string, startIndex: number, limit?: number): AsyncResult<StreamItem<T>[], StreamStoreError>;
-    /**
-     * Get metadata about a stream.
-     * Returns undefined if stream doesn't exist.
-     */
-    getMetadata(workflowId: string, namespace: string): AsyncResult<StreamMetadata | undefined, StreamStoreError>;
-    /**
-     * Mark stream as closed.
-     */
-    closeStream(workflowId: string, namespace: string): AsyncResult<void, StreamStoreError>;
-    /**
-     * Subscribe to new items in a stream.
-     * Callback is invoked for each new item written.
-     * Returns unsubscribe function.
-     */
-    subscribe<T>(workflowId: string, namespace: string, callback: (item: StreamItem<T>) => void): Unsubscribe;
-}
-/**
- * Check if an error is a StreamEndedMarker.
- */
-declare function isStreamEnded(error: unknown): error is StreamEndedMarker;
-/**
- * Check if an error is a StreamWriteError.
- */
-declare function isStreamWriteError(error: unknown): error is StreamWriteError;
-/**
- * Check if an error is a StreamReadError.
- */
-declare function isStreamReadError(error: unknown): error is StreamReadError;
-/**
- * Check if an error is a StreamStoreError.
- */
-declare function isStreamStoreError(error: unknown): error is StreamStoreError;
-/**
- * Check if an error is a StreamBackpressureError.
- */
-declare function isStreamBackpressureError(error: unknown): error is StreamBackpressureError;
-/**
- * Create a StreamWriteError.
- */
-declare function streamWriteError(reason: StreamWriteError["reason"], message: string, cause?: unknown): StreamWriteError;
-/**
- * Create a StreamReadError.
- */
-declare function streamReadError(reason: StreamReadError["reason"], message: string, cause?: unknown): StreamReadError;
-/**
- * Create a StreamCloseError.
- */
-declare function streamCloseError(reason: StreamCloseError["reason"], message: string, cause?: unknown): StreamCloseError;
-/**
- * Create a StreamStoreError.
- */
-declare function streamStoreError(reason: StreamStoreError["reason"], message: string, cause?: unknown): StreamStoreError;
-/**
- * Create a StreamEndedMarker.
- */
-declare function streamEnded(finalPosition: number): StreamEndedMarker;
-/**
- * Create a StreamBackpressureError.
- */
-declare function streamBackpressureError(bufferedCount: number, highWaterMark: number): StreamBackpressureError;
-
-export { streamBackpressureError as A, streamCloseError as B, streamEnded as C, streamReadError as D, streamStoreError as E, streamWriteError as F, type StreamStore as S, type Unsubscribe as U, type StreamReader as a, STREAM_BACKPRESSURE_ERROR as b, STREAM_CLOSE_ERROR as c, STREAM_ENDED as d, STREAM_READ_ERROR as e, STREAM_STORE_ERROR as f, STREAM_WRITE_ERROR as g, type StreamBackpressureError as h, type StreamCloseError as i, type StreamEndedMarker as j, type StreamError as k, type StreamForEachOptions as l, type StreamForEachResult as m, type StreamItem as n, type StreamMetadata as o, type StreamOptions as p, type StreamReadError as q, type StreamReadOptions as r, type StreamStoreError as s, type StreamWriteError as t, type StreamWriter as u, isStreamBackpressureError as v, isStreamEnded as w, isStreamReadError as x, isStreamStoreError as y, isStreamWriteError as z };