ai-stream-utils 1.5.0 → 2.0.0

package/dist/index.d.mts

@@ -1,122 +1,145 @@
-import { AsyncIterableStream, InferUIMessageChunk, UIMessage } from "ai";
+import { a as convertSSEToUIMessageStream, c as convertArrayToStream, i as convertStreamToArray, l as convertArrayToAsyncIterable, n as createAsyncIterableStream, o as convertAsyncIterableToStream, r as convertUIMessageToSSEStream, s as convertAsyncIterableToArray, t as AsyncIterableStream } from "./types-B4nePmEd.mjs";
+import "./utils/index.mjs";
+import { AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, UIMessage } from "ai";
 
-//#region src/types.d.ts
-type InferUIMessagePart<UI_MESSAGE extends UIMessage> = UI_MESSAGE['parts'][number];
-type InferUIMessagePartType<UI_MESSAGE extends UIMessage> = InferUIMessagePart<UI_MESSAGE>['type'];
-//#endregion
-//#region src/map-ui-message-stream.d.ts
-/**
- * Input object provided to the chunk map function.
- */
-type MapInput<UI_MESSAGE extends UIMessage> = {
-  /** The current chunk */chunk: InferUIMessageChunk<UI_MESSAGE>;
-  /**
-       * The assembled part this chunk belongs to (from readUIMessageStream).
-       * Use `part.type` to determine the part type.
-       */
-  part: InferUIMessagePart<UI_MESSAGE>;
-};
+//#region src/consume/consume-ui-message-stream.d.ts
 /**
- * Map function for chunk-level transformation.
- * Return:
- * - A single chunk (possibly transformed) to include it
- * - An array of chunks to emit multiple chunks
- * - An empty array or null to filter out the chunk
- */
-type MapUIMessageStreamFn<UI_MESSAGE extends UIMessage> = (input: MapInput<UI_MESSAGE>) => InferUIMessageChunk<UI_MESSAGE> | InferUIMessageChunk<UI_MESSAGE>[] | null;
-/**
- * Maps/filters a UIMessageStream at the chunk level using readUIMessageStream.
- *
- * This function processes each chunk as it arrives and allows you to:
- * - Transform chunks by returning a modified chunk
- * - Filter out chunks by returning null or an empty array
- * - Emit multiple chunks by returning an array
+ * Consumes a UIMessageStream by fully reading it and returning the final UI message.
  *
- * Meta chunks (start, finish, abort, message-metadata, error) always pass through.
- * Step boundaries (start-step, finish-step) are handled automatically:
- * - start-step is buffered and only emitted if subsequent content is included
- * - finish-step is only emitted if the corresponding start-step was emitted
+ * This function uses `readUIMessageStream` to process all chunks from the stream
+ * and returns the last assembled message, which contains the complete content
+ * with all parts fully resolved.
  *
  * @example
  * ```typescript
- * // Filter out reasoning chunks using part.type
- * const stream = mapUIMessageStream(
- *   inputStream,
- *   ({ chunk, part }) => part.type === 'reasoning' ? null : chunk
- * );
- *
- * // Transform text chunks
- * const stream = mapUIMessageStream(
- *   inputStream,
- *   ({ chunk, part }) => {
- *     if (chunk.type === 'text-delta') {
- *       return { ...chunk, delta: chunk.delta.toUpperCase() };
- *     }
- *     return chunk;
- *   }
- * );
+ * const message = await consumeUIMessageStream(stream);
+ * console.log(message.parts); // All parts fully assembled
+ * ```
  *
- * // Buffer text deltas and split into word-by-word chunks (smooth streaming)
- * let buffer = '';
- * let textStartChunk = null;
- * const stream = mapUIMessageStream(
- *   inputStream,
- *   ({ chunk }) => {
- *     if (chunk.type === 'text-start') {
- *       textStartChunk = chunk;
- *       return []; // Buffer, don't emit yet
- *     }
- *     if (chunk.type === 'text-delta') {
- *       buffer += chunk.delta;
- *       return []; // Buffer, don't emit yet
- *     }
- *     if (chunk.type === 'text-end') {
- *       // Emit buffered content as word chunks
- *       const words = buffer.split(' ');
- *       const wordChunks = words.map((word, i) => ({
- *         type: 'text-delta' as const,
- *         id: chunk.id,
- *         delta: i === 0 ? word : ` ${word}`,
- *       }));
- *       buffer = '';
- *       const result = [...wordChunks, chunk];
- *       if (textStartChunk) {
- *         result.unshift(textStartChunk);
- *         textStartChunk = null;
- *       }
- *       return result;
- *     }
- *     return chunk;
- *   }
- * );
+ * @example
+ * ```typescript
+ * const stream = result.toUIMessageStream();
+ * const filteredStream = filterUIMessageStream(stream, includeParts(['text']));
+ * const message = await consumeUIMessageStream(filteredStream);
  * ```
  */
-declare function mapUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, mapFn: MapUIMessageStreamFn<UI_MESSAGE>): AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>;
+declare function consumeUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>): Promise<UI_MESSAGE>;
 //#endregion
-//#region src/filter-ui-message-stream.d.ts
+//#region src/pipe/base-pipeline.d.ts
 /**
- * Filter function that receives the same input as mapUIMessageStream.
- * Return true to include the chunk, false to filter it out.
+ * Internal chunk representation used within the pipeline.
+ * Includes the original chunk and the part type (or undefined for meta chunks).
  */
-type FilterUIMessageStreamPredicate<UI_MESSAGE extends UIMessage> = (input: MapInput<UI_MESSAGE>) => boolean;
+type InternalChunk<UI_MESSAGE extends UIMessage> = {
+  chunk: InferUIMessageChunk<UI_MESSAGE>;
+  partType: string | undefined;
+};
 /**
- * Creates a filter predicate that includes only the specified part types.
- *
- * @example
- * ```typescript
- * filterUIMessageStream(stream, includeParts(['text', 'tool-weather']));
- * ```
+ * Base interface for all pipeline types.
  */
-declare function includeParts<UI_MESSAGE extends UIMessage>(includePartTypes: Array<InferUIMessagePartType<UI_MESSAGE>>): FilterUIMessageStreamPredicate<UI_MESSAGE>;
+interface BasePipeline<UI_MESSAGE extends UIMessage> {
+  toStream(): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
+}
+//#endregion
+//#region src/pipe/types.d.ts
 /**
- * Creates a filter predicate that excludes the specified part types.
- *
- * @example
- * ```typescript
- * filterUIMessageStream(stream, excludeParts(['reasoning', 'tool-calculator']));
- * ```
+ * Input for chunk-based operations.
+ */
+type ChunkInput<CHUNK, PART extends {
+  type: string;
+}> = {
+  chunk: CHUNK;
+  part: Pick<PART, `type`>;
+};
+/**
+ * Filter predicate for chunk-based operations.
+ * Returns true to include the chunk, false to exclude.
+ * The __brand exclusion prevents type guards from matching this type.
+ */
+type ChunkFilterFn<CHUNK, PART extends {
+  type: string;
+}> = ((input: ChunkInput<CHUNK, PART>) => boolean) & {
+  __brand?: never;
+};
+/**
+ * Map function for chunk-based operations.
+ * Returns transformed chunk(s) or null to remove.
+ */
+type ChunkMapFn<UI_MESSAGE extends UIMessage, CHUNK extends InferUIMessageChunk<UI_MESSAGE>, PART extends {
+  type: string;
+}> = (input: ChunkInput<CHUNK, PART>) => InferUIMessageChunk<UI_MESSAGE> | Array<InferUIMessageChunk<UI_MESSAGE>> | null;
+/**
+ * Input for observer operations.
+ * Part is optional since meta chunks don't have a part type.
+ */
+type ChunkObserveInput<CHUNK, PART extends {
+  type: string;
+} | undefined = {
+  type: string;
+} | undefined> = {
+  chunk: CHUNK;
+  part: PART;
+};
+/**
+ * Callback function for observer operations.
+ * Called for each matching chunk. Can be sync or async.
+ */
+type ChunkObserveFn<CHUNK, PART extends {
+  type: string;
+} | undefined = undefined> = (input: ChunkObserveInput<CHUNK, PART>) => void | Promise<void>;
+/**
+ * Builder function for ChunkPipeline operations.
+ */
+type ChunkBuilder<UI_MESSAGE extends UIMessage> = (iterable: AsyncIterable<InternalChunk<UI_MESSAGE>>) => AsyncIterable<InternalChunk<UI_MESSAGE>>;
+/**
+ * Generic guard for filter() that carries pre-computed narrowed types.
+ * The __brand property distinguishes this from plain predicates.
+ */
+type FilterGuard<UI_MESSAGE extends UIMessage, NARROWED_CHUNK extends InferUIMessageChunk<UI_MESSAGE>, NARROWED_PART extends {
+  type: string;
+}> = {
+  <T extends {
+    chunk: InferUIMessageChunk<UI_MESSAGE>;
+    part?: {
+      type: string;
+    } | undefined;
+  }>(input: T): input is T & {
+    chunk: NARROWED_CHUNK;
+    part: NARROWED_PART;
+  }; /** @internal Type brand - never exists at runtime */
+  readonly __brand: `FilterGuard`;
+};
+/**
+ * Generic guard for on() that carries pre-computed narrowed types.
+ * Part can be undefined for meta chunks.
+ * The __brand property distinguishes this from plain predicates.
+ */
+type ObserveGuard<UI_MESSAGE extends UIMessage, NARROWED_CHUNK extends InferUIMessageChunk<UI_MESSAGE>, NARROWED_PART extends {
+  type: string;
+} | undefined> = {
+  <T extends {
+    chunk: InferUIMessageChunk<UI_MESSAGE>;
+    part?: {
+      type: string;
+    } | undefined;
+  }>(input: T): input is T & {
+    chunk: NARROWED_CHUNK;
+    part: NARROWED_PART;
+  }; /** @internal Type brand - never exists at runtime */
+  readonly __brand: `ObserveGuard`;
+};
+//#endregion
+//#region src/filter/filter-ui-message-stream.d.ts
+/**
+ * Filter function type for filterUIMessageStream.
+ * Can be either a FilterGuard (from includeParts/excludeParts) or a plain predicate.
  */
-declare function excludeParts<UI_MESSAGE extends UIMessage>(excludePartTypes: Array<InferUIMessagePartType<UI_MESSAGE>>): FilterUIMessageStreamPredicate<UI_MESSAGE>;
+type FilterFn<UI_MESSAGE extends UIMessage> = FilterGuard<UI_MESSAGE, any, any> | ((input: {
+  chunk: InferUIMessageChunk<UI_MESSAGE>;
+  part: {
+    type: string;
+  };
+}) => boolean);
 /**
  * Filters a UIMessageStream to include or exclude specific chunks.
  *
@@ -152,9 +175,151 @@ declare function excludeParts<UI_MESSAGE extends UIMessage>(excludePartTypes: Ar
  * );
  * ```
  */
-declare function filterUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, predicate: FilterUIMessageStreamPredicate<UI_MESSAGE>): AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>;
+declare function filterUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, predicate: FilterFn<UI_MESSAGE>): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
 //#endregion
-//#region src/flat-map-ui-message-stream.d.ts
+//#region src/types.d.ts
+type InferUIMessagePart<UI_MESSAGE extends UIMessage> = UI_MESSAGE["parts"][number];
+type InferUIMessagePartType<UI_MESSAGE extends UIMessage> = InferUIMessagePart<UI_MESSAGE>["type"];
+type InferUIMessageChunkType<UI_MESSAGE extends UIMessage> = InferUIMessageChunk<UI_MESSAGE>["type"];
+/**
+ * Extracts chunk type strings that match the prefix exactly or as `${PREFIX}-*`.
+ * Dynamically derives chunk types from the actual UIMessageChunk union.
+ *
+ * @example
+ * ```typescript
+ * type TextChunks = ExtractChunkTypesByPrefix<MyUIMessage, 'text'>;
+ * // => 'text-start' | 'text-delta' | 'text-end'
+ *
+ * type FileChunks = ExtractChunkTypesByPrefix<MyUIMessage, 'file'>;
+ * // => 'file' (exact match)
+ * ```
+ */
+type ExtractChunkTypesByPrefix<UI_MESSAGE extends UIMessage, PREFIX extends string> = InferUIMessageChunk<UI_MESSAGE> extends infer CHUNK ? CHUNK extends {
+  type: infer T extends string;
+} ? T extends PREFIX | `${PREFIX}-${string}` ? T : never : never : never;
+/**
+ * Maps a part type string to its corresponding chunk type(s).
+ * Dynamically extracts from UIMessageChunk.
+ *
+ * Special handling:
+ * - `tool-{NAME}` parts map to all `tool-*` chunk types (tool-input-start, tool-output-available, etc.)
+ * - `dynamic-tool` parts also map to all `tool-*` chunk types
+ * - `step-start` part maps to `start-step` chunk (naming inconsistency in AI SDK)
+ *
+ * @example
+ * ```typescript
+ * type TextChunkTypes = PartTypeToChunkTypes<MyUIMessage, 'text'>;
+ * // => 'text-start' | 'text-delta' | 'text-end'
+ *
+ * type ToolChunkTypes = PartTypeToChunkTypes<MyUIMessage, 'tool-weather'>;
+ * // => 'tool-input-start' | 'tool-input-delta' | ... (all tool chunk types)
+ * ```
+ */
+type PartTypeToChunkTypes<UI_MESSAGE extends UIMessage, PART_TYPE extends string> = PART_TYPE extends `tool-${string}` | "dynamic-tool" ? ExtractChunkTypesByPrefix<UI_MESSAGE, "tool"> : PART_TYPE extends "step-start" ? "start-step" : ExtractChunkTypesByPrefix<UI_MESSAGE, PART_TYPE>;
+/**
+ * Extracts the chunk type(s) for a given part or part union.
+ *
+ * @example
+ * ```typescript
+ * type TextChunk = ExtractChunkForPart<MyUIMessage, TextPart>;
+ * // => { type: 'text-start'; ... } | { type: 'text-delta'; ... } | { type: 'text-end'; ... }
+ * ```
+ */
+type ExtractChunkForPart<UI_MESSAGE extends UIMessage, PART extends InferUIMessagePart<UI_MESSAGE>> = Extract<InferUIMessageChunk<UI_MESSAGE>, {
+  type: PartTypeToChunkTypes<UI_MESSAGE, PART["type"]>;
+}>;
+/**
+ * Extract a specific part type from UIMessage
+ */
+type ExtractPart<UI_MESSAGE extends UIMessage, PART_TYPE extends string> = Extract<InferUIMessagePart<UI_MESSAGE>, {
+  type: PART_TYPE;
+}>;
+/**
+ * Extract a specific chunk type from UIMessage
+ */
+type ExtractChunk<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string> = Extract<InferUIMessageChunk<UI_MESSAGE>, {
+  type: CHUNK_TYPE;
+}>;
+/**
+ * Maps chunk type string(s) back to the corresponding part type string(s).
+ * Reverse of `PartTypeToChunkTypes`.
+ *
+ * @example
+ * ```typescript
+ * type TextPartType = ChunkTypeToPartType<MyUIMessage, 'text-delta'>;
+ * // => 'text'
+ *
+ * type ToolPartType = ChunkTypeToPartType<MyUIMessage, 'tool-input-delta'>;
+ * // => 'tool-weather' | 'dynamic-tool' (all tool part types)
+ * ```
+ */
+type ChunkTypeToPartType<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string> = InferUIMessagePart<UI_MESSAGE> extends infer PART ? PART extends {
+  type: infer PT extends string;
+} ? CHUNK_TYPE extends PartTypeToChunkTypes<UI_MESSAGE, PT> ? PT : never : never : never;
+/**
+ * Extracts content chunk types (chunks that have a corresponding part type).
+ * Excludes meta chunks like 'start', 'finish', etc.
+ */
+type ContentChunkType<UI_MESSAGE extends UIMessage> = { [CT in InferUIMessageChunkType<UI_MESSAGE>]: [ChunkTypeToPartType<UI_MESSAGE, CT>] extends [never] ? never : CT }[InferUIMessageChunkType<UI_MESSAGE>];
+/**
+ * Distributing helper to collect all part types for chunk types.
+ * Distributes over union chunk types to get all corresponding part types.
+ */
+type CollectPartTypesForChunk<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string> = CHUNK_TYPE extends string ? ChunkTypeToPartType<UI_MESSAGE, CHUNK_TYPE> : never;
+/**
+ * Detects if any chunk type in the union is a meta chunk (has no corresponding part type).
+ * Returns `true` for meta chunks, `never` otherwise.
+ */
+type HasMetaChunk<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string> = CHUNK_TYPE extends string ? [ChunkTypeToPartType<UI_MESSAGE, CHUNK_TYPE>] extends [never] ? true : never : never;
+/**
+ * Infer part type from chunk type for .on() callback.
+ * Returns { type: PART_TYPE } for content chunks, undefined for meta chunks.
+ * For union chunk types, returns union of their part types.
+ * When mixing content and meta chunks, includes undefined in the union.
+ *
+ * @example
+ * ```typescript
+ * // Content chunk: part is { type: 'text' }
+ * type TextPart = InferPartForChunk<MyUIMessage, 'text-delta'>;
+ * // => { type: 'text' }
+ *
+ * // Meta chunk: part is undefined
+ * type MetaPart = InferPartForChunk<MyUIMessage, 'start'>;
+ * // => undefined
+ *
+ * // Union of content chunks: part type is union
+ * type UnionPart = InferPartForChunk<MyUIMessage, 'text-delta' | 'reasoning-delta'>;
+ * // => { type: 'text' | 'reasoning' }
+ *
+ * // Mixed content and meta chunks: includes undefined
+ * type MixedPart = InferPartForChunk<MyUIMessage, 'text-delta' | 'start'>;
+ * // => { type: 'text' } | undefined
+ * ```
+ */
+type InferPartForChunk<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string> = [CollectPartTypesForChunk<UI_MESSAGE, CHUNK_TYPE>] extends [never] ? undefined : [HasMetaChunk<UI_MESSAGE, CHUNK_TYPE>] extends [never] ? {
+  type: CollectPartTypesForChunk<UI_MESSAGE, CHUNK_TYPE>;
+} : {
+  type: CollectPartTypesForChunk<UI_MESSAGE, CHUNK_TYPE>;
+} | undefined;
+/**
+ * Computes which part types remain after excluding specific chunk types.
+ * A part type is excluded only if ALL its chunk types are excluded.
+ *
+ * @example
+ * ```typescript
+ * // Excluding 'text-delta' still leaves 'text-start' and 'text-end'
+ * // So 'text' part type is NOT excluded
+ * type RemainingParts = ExcludePartForChunks<MyUIMessage, 'text-delta'>;
+ * // => 'text' | 'reasoning' | ... (all part types)
+ *
+ * // Excluding all text chunks removes 'text' part type
+ * type RemainingParts2 = ExcludePartForChunks<MyUIMessage, 'text-start' | 'text-delta' | 'text-end'>;
+ * // => 'reasoning' | ... (all part types except 'text')
+ * ```
+ */
+type ExcludePartForChunks<UI_MESSAGE extends UIMessage, EXCLUDED_CHUNK_TYPE extends string> = { [PT in InferUIMessagePartType<UI_MESSAGE>]: [Exclude<PartTypeToChunkTypes<UI_MESSAGE, PT>, EXCLUDED_CHUNK_TYPE>] extends [never] ? never : PT }[InferUIMessagePartType<UI_MESSAGE>];
+//#endregion
+//#region src/flat-map/flat-map-ui-message-stream.d.ts
 /**
  * Input object provided to the part flatMap function.
  */
@@ -254,7 +419,293 @@ declare function partTypeIs<UI_MESSAGE extends UIMessage, PART_TYPE extends Infe
  * );
  * ```
  */
-declare function flatMapUIMessageStream<UI_MESSAGE extends UIMessage, PART extends InferUIMessagePart<UI_MESSAGE>>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, predicate: FlatMapUIMessageStreamPredicate<UI_MESSAGE, PART>, flatMapFn: FlatMapUIMessageStreamFn<UI_MESSAGE, PART>): AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>;
-declare function flatMapUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, flatMapFn: FlatMapUIMessageStreamFn<UI_MESSAGE>): AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>;
+declare function flatMapUIMessageStream<UI_MESSAGE extends UIMessage, PART extends InferUIMessagePart<UI_MESSAGE>>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, predicate: FlatMapUIMessageStreamPredicate<UI_MESSAGE, PART>, flatMapFn: FlatMapUIMessageStreamFn<UI_MESSAGE, PART>): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
+declare function flatMapUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, flatMapFn: FlatMapUIMessageStreamFn<UI_MESSAGE>): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
+//#endregion
+//#region src/map/map-ui-message-stream.d.ts
+/**
+ * Input object provided to the chunk map function.
+ */
+type MapInput<UI_MESSAGE extends UIMessage> = {
+  /** The current chunk */chunk: InferUIMessageChunk<UI_MESSAGE>;
+  /**
+   * The assembled part this chunk belongs to (from readUIMessageStream).
+   * Use `part.type` to determine the part type.
+   */
+  part: InferUIMessagePart<UI_MESSAGE>;
+};
+/**
+ * Map function for chunk-level transformation.
+ * Return:
+ * - A single chunk (possibly transformed) to include it
+ * - An array of chunks to emit multiple chunks
+ * - An empty array or null to filter out the chunk
+ */
+type MapUIMessageStreamFn<UI_MESSAGE extends UIMessage> = (input: MapInput<UI_MESSAGE>) => InferUIMessageChunk<UI_MESSAGE> | InferUIMessageChunk<UI_MESSAGE>[] | null;
+/**
+ * Maps/filters a UIMessageStream at the chunk level using readUIMessageStream.
+ *
+ * This function processes each chunk as it arrives and allows you to:
+ * - Transform chunks by returning a modified chunk
+ * - Filter out chunks by returning null or an empty array
+ * - Emit multiple chunks by returning an array
+ *
+ * Meta chunks (start, finish, abort, message-metadata, error) always pass through.
+ * Step boundaries (start-step, finish-step) are handled automatically:
+ * - start-step is buffered and only emitted if subsequent content is included
+ * - finish-step is only emitted if the corresponding start-step was emitted
+ *
+ * @example
+ * ```typescript
+ * // Filter out reasoning chunks using part.type
+ * const stream = mapUIMessageStream(
+ *   inputStream,
+ *   ({ chunk, part }) => part.type === 'reasoning' ? null : chunk
+ * );
+ *
+ * // Transform text chunks
+ * const stream = mapUIMessageStream(
+ *   inputStream,
+ *   ({ chunk, part }) => {
+ *     if (chunk.type === 'text-delta') {
+ *       return { ...chunk, delta: chunk.delta.toUpperCase() };
+ *     }
+ *     return chunk;
+ *   }
+ * );
+ *
+ * // Buffer text deltas and split into word-by-word chunks (smooth streaming)
+ * let buffer = '';
+ * let textStartChunk = null;
+ * const stream = mapUIMessageStream(
+ *   inputStream,
+ *   ({ chunk }) => {
+ *     if (chunk.type === 'text-start') {
+ *       textStartChunk = chunk;
+ *       return []; // Buffer, don't emit yet
+ *     }
+ *     if (chunk.type === 'text-delta') {
+ *       buffer += chunk.delta;
+ *       return []; // Buffer, don't emit yet
+ *     }
+ *     if (chunk.type === 'text-end') {
+ *       // Emit buffered content as word chunks
+ *       const words = buffer.split(' ');
+ *       const wordChunks = words.map((word, i) => ({
+ *         type: 'text-delta' as const,
+ *         id: chunk.id,
+ *         delta: i === 0 ? word : ` ${word}`,
+ *       }));
+ *       buffer = '';
+ *       const result = [...wordChunks, chunk];
+ *       if (textStartChunk) {
+ *         result.unshift(textStartChunk);
+ *         textStartChunk = null;
+ *       }
+ *       return result;
+ *     }
+ *     return chunk;
+ *   }
+ * );
+ * ```
+ */
+declare function mapUIMessageStream<UI_MESSAGE extends UIMessage>(stream: ReadableStream<InferUIMessageChunk<UI_MESSAGE>>, mapFn: MapUIMessageStreamFn<UI_MESSAGE>): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
+//#endregion
+//#region src/pipe/chunk-pipeline.d.ts
+/**
+ * Pipeline for chunk-based operations.
+ * Operations receive individual chunks with their associated part type.
+ */
+declare class ChunkPipeline<UI_MESSAGE extends UIMessage, CHUNK extends InferUIMessageChunk<UI_MESSAGE>, PART extends {
+  type: string;
+}> implements BasePipeline<UI_MESSAGE>, AsyncIterable<InferUIMessageChunk<UI_MESSAGE>> {
+  private consumed;
+  private sourceIterable;
+  private prevBuilder;
+  constructor(sourceIterable: AsyncIterable<InternalChunk<UI_MESSAGE>>, prevBuilder?: ChunkBuilder<UI_MESSAGE>);
+  private assertNotConsumed;
+  /**
+   * Filters chunks using a type guard and narrows both chunk and part types.
+   * Use with includeChunks(), includeParts(), excludeChunks(), or excludeParts().
+   * The callback only receives content chunks because meta chunks pass through unchanged.
+   */
+  filter<NARROWED_CHUNK extends InferUIMessageChunk<UI_MESSAGE>, NARROWED_PART extends {
+    type: string;
+  }>(guard: FilterGuard<UI_MESSAGE, NARROWED_CHUNK, NARROWED_PART>): ChunkPipeline<UI_MESSAGE, NARROWED_CHUNK, NARROWED_PART>;
+  /**
+   * Filters chunks using a generic predicate function.
+   * The callback only receives content chunks because meta chunks pass through unchanged.
+   */
+  filter(predicate: ChunkFilterFn<CHUNK & ExtractChunk<UI_MESSAGE, ContentChunkType<UI_MESSAGE>>, PART>): ChunkPipeline<UI_MESSAGE, CHUNK, PART>;
+  /**
+   * Transforms chunks by applying a mapping function.
+   * The callback only receives content chunks because meta chunks pass through unchanged.
+   * Returning null filters out the chunk, while returning an array yields multiple chunks.
+   */
+  map(fn: ChunkMapFn<UI_MESSAGE, CHUNK & ExtractChunk<UI_MESSAGE, ContentChunkType<UI_MESSAGE>>, PART>): ChunkPipeline<UI_MESSAGE, CHUNK, PART>;
+  /**
+   * Observes chunks matching a type guard without filtering them.
+   * The callback receives a narrowed chunk type and inferred part type.
+   * Content chunks include a part object with the type, while meta chunks have undefined part.
+   * All chunks pass through regardless of whether the callback is invoked.
+   */
+  on<NARROWED_CHUNK extends InferUIMessageChunk<UI_MESSAGE>, NARROWED_PART extends {
+    type: string;
+  } | undefined>(guard: ObserveGuard<UI_MESSAGE, NARROWED_CHUNK, NARROWED_PART>, callback: ChunkObserveFn<NARROWED_CHUNK, NARROWED_PART>): ChunkPipeline<UI_MESSAGE, CHUNK, PART>;
+  /**
+   * Observes chunks matching a predicate without filtering them.
+   * Uses the current pipeline types without type narrowing.
+   * All chunks pass through regardless of whether the callback is invoked.
+   */
+  on(predicate: (input: ChunkObserveInput<CHUNK>) => boolean, callback: ChunkObserveFn<CHUNK, {
+    type: PART[`type`];
+  } | undefined>): ChunkPipeline<UI_MESSAGE, CHUNK, PART>;
+  /**
+   * Executes the pipeline and returns the resulting stream.
+   * All chunks pass through including step boundaries and meta chunks.
+   */
+  toStream(): AsyncIterableStream$1<InferUIMessageChunk<UI_MESSAGE>>;
+  [Symbol.asyncIterator](): AsyncIterator<InferUIMessageChunk<UI_MESSAGE>>;
+}
+//#endregion
+//#region src/pipe/pipe.d.ts
+/**
+ * Input type for `pipe()` that accepts either a ReadableStream or an AsyncIterable.
+ */
+type PipeInput<UI_MESSAGE extends UIMessage> = ReadableStream<InferUIMessageChunk<UI_MESSAGE>> | AsyncIterable<InferUIMessageChunk<UI_MESSAGE>>;
+/**
+ * Creates a type-safe pipeline for UIMessageStream operations.
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .filter(isPartType('text'))
+ *   .map(({ chunk }) => chunk)
+ *   .toStream();
+ * ```
+ */
+declare function pipe<UI_MESSAGE extends UIMessage>(input: PipeInput<UI_MESSAGE>): ChunkPipeline<UI_MESSAGE, InferUIMessageChunk<UI_MESSAGE>, InferUIMessagePart<UI_MESSAGE>>;
+//#endregion
+//#region src/pipe/type-guards.d.ts
+/**
+ * Creates a filter guard that includes specific content chunk types.
+ * Use with `.filter()` to narrow to specific chunks.
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeChunks('text-delta'))
+ *   .map(({ chunk }) => chunk); // chunk is narrowed to text-delta chunk
+ *
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeChunks(['text-delta', 'text-end']))
+ *   .map(({ chunk }) => chunk); // chunk is narrowed to text-delta | text-end
+ * ```
+ */
+declare function includeChunks<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends ContentChunkType<UI_MESSAGE>>(types: CHUNK_TYPE | Array<CHUNK_TYPE>): FilterGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, CHUNK_TYPE>, {
+  type: ChunkTypeToPartType<UI_MESSAGE, CHUNK_TYPE>;
+}>;
+/**
+ * Creates a filter guard that includes specific part types.
+ * Use with `.filter()` to narrow to chunks belonging to specific parts.
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeParts('text'))
+ *   .map(({ chunk, part }) => chunk); // chunk is narrowed to text chunks
+ *
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeParts(['text', 'reasoning']))
+ *   .map(({ chunk }) => chunk); // chunk is text or reasoning chunks
+ * ```
+ */
+declare function includeParts<UI_MESSAGE extends UIMessage, PART_TYPE extends InferUIMessagePartType<UI_MESSAGE>>(types: PART_TYPE | Array<PART_TYPE>): FilterGuard<UI_MESSAGE, ExtractChunkForPart<UI_MESSAGE, ExtractPart<UI_MESSAGE, PART_TYPE>>, {
+  type: PART_TYPE;
+}>;
+/**
+ * Creates a filter guard that excludes specific content chunk types.
+ * Use with `.filter()` to keep all chunks except the specified types.
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeChunks('text-delta'))
+ *   .map(({ chunk }) => chunk); // chunk is all content chunks except text-delta
+ *
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeChunks(['text-start', 'text-end']))
+ *   .map(({ chunk }) => chunk); // excludes text-start and text-end
+ * ```
+ */
+declare function excludeChunks<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends ContentChunkType<UI_MESSAGE>>(types: CHUNK_TYPE | Array<CHUNK_TYPE>): FilterGuard<UI_MESSAGE, Exclude<ExtractChunk<UI_MESSAGE, ContentChunkType<UI_MESSAGE>>, ExtractChunk<UI_MESSAGE, CHUNK_TYPE>>, {
+  type: ExcludePartForChunks<UI_MESSAGE, CHUNK_TYPE>;
+}>;
+/**
+ * Creates a filter guard that excludes specific part types.
+ * Use with `.filter()` to keep all chunks except those belonging to specified parts.
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeParts('text'))
+ *   .map(({ chunk }) => chunk); // excludes all text chunks
+ *
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeParts(['text', 'reasoning']))
+ *   .map(({ chunk }) => chunk); // excludes text and reasoning chunks
+ * ```
+ */
+declare function excludeParts<UI_MESSAGE extends UIMessage, PART_TYPE extends InferUIMessagePartType<UI_MESSAGE>>(types: PART_TYPE | Array<PART_TYPE>): FilterGuard<UI_MESSAGE, Exclude<ExtractChunk<UI_MESSAGE, ContentChunkType<UI_MESSAGE>>, ExtractChunkForPart<UI_MESSAGE, ExtractPart<UI_MESSAGE, PART_TYPE>>>, {
+  type: Exclude<InferUIMessagePartType<UI_MESSAGE>, PART_TYPE>;
+}>;
+/**
+ * Creates an observe guard that matches specific chunk types, including meta chunks.
+ * Use with `.on()` to observe specific chunks without filtering.
+ *
+ * @example
+ * ```typescript
+ * // Observe content chunks
+ * pipe<MyUIMessage>(stream)
+ *   .on(chunkType('text-delta'), ({ chunk, part }) => {
+ *     // chunk is text-delta, part is { type: 'text' }
+ *   });
+ *
+ * // Observe meta chunks
+ * pipe<MyUIMessage>(stream)
+ *   .on(chunkType('start'), ({ chunk, part }) => {
+ *     // chunk is start chunk, part is undefined
+ *   });
+ *
+ * // Observe multiple chunk types
+ * pipe<MyUIMessage>(stream)
+ *   .on(chunkType(['text-delta', 'start']), ({ chunk, part }) => {
+ *     // chunk is text-delta | start, part is { type: 'text' } | undefined
+ *   });
+ * ```
+ */
+declare function chunkType<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends InferUIMessageChunkType<UI_MESSAGE>>(types: CHUNK_TYPE | Array<CHUNK_TYPE>): ObserveGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, CHUNK_TYPE>, InferPartForChunk<UI_MESSAGE, CHUNK_TYPE>>;
+/**
+ * Creates an observe guard that matches specific part types.
+ * Use with `.on()` to observe chunks belonging to specific parts without filtering.
+ *
+ * @example
+ * ```typescript
+ * // Observe text parts
+ * pipe<MyUIMessage>(stream)
+ *   .on(partType('text'), ({ chunk, part }) => {
+ *     // chunk is text chunk, part is { type: 'text' }
+ *   });
+ *
+ * // Observe multiple part types
+ * pipe<MyUIMessage>(stream)
+ *   .on(partType(['text', 'reasoning']), ({ chunk, part }) => {
+ *     // chunk is text | reasoning chunk, part is { type: 'text' | 'reasoning' }
+ *   });
+ * ```
+ */
+declare function partType<UI_MESSAGE extends UIMessage, PART_TYPE extends InferUIMessagePartType<UI_MESSAGE>>(types: PART_TYPE | Array<PART_TYPE>): ObserveGuard<UI_MESSAGE, ExtractChunkForPart<UI_MESSAGE, ExtractPart<UI_MESSAGE, PART_TYPE>>, {
+  type: PART_TYPE;
+}>;
 //#endregion
-export { type FilterUIMessageStreamPredicate, type FlatMapContext, type FlatMapInput, type FlatMapUIMessageStreamFn, type FlatMapUIMessageStreamPredicate, type InferUIMessagePart, type InferUIMessagePartType, type MapInput, type MapUIMessageStreamFn, excludeParts, filterUIMessageStream, flatMapUIMessageStream, includeParts, mapUIMessageStream, partTypeIs };
+export { AsyncIterableStream, type FlatMapContext, type FlatMapInput, type FlatMapUIMessageStreamFn, type FlatMapUIMessageStreamPredicate, type MapInput, type MapUIMessageStreamFn, chunkType, consumeUIMessageStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream, excludeChunks, excludeParts, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, mapUIMessageStream, partType, partTypeIs, pipe };