awaitly 2.0.0 → 3.0.0

package/dist/types-d8q8iQlk.d.cts

@@ -0,0 +1,323 @@
+import { A as AsyncResult } from './index-ICmfQi08.cjs';
+
+/**
+ * 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 };

package/dist/types-sObbY4mX.d.ts

@@ -0,0 +1,323 @@
+import { A as AsyncResult } from './index-Cv4K_3sZ.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 };