ai-stream-utils 2.2.0 → 2.3.0

package/README.md

@@ -145,6 +145,31 @@ const stream = pipe(result.toUIMessageStream())
   .toStream();
 ```
 
+#### Helpers
+
+`transformProviderMetadata()` changes `providerMetadata` on the chunks that carry it (`text-*`, `reasoning-*`, `tool-input-*`, `source-*`, `file`). Every other chunk passes through untouched, so you don't have to narrow by chunk type yourself.
+
+The callback receives the current `metadata` (may be `undefined`) and returns one of three things:
+
+- an **object** to set/replace the metadata (merge by spreading `metadata`)
+- **`undefined`** to leave the chunk unchanged
+- **`null`** to remove the `providerMetadata` field entirely (the chunk still passes through)
+
+```typescript
+const stream = pipe(result.toUIMessageStream())
+  .map(
+    transformProviderMetadata(({ chunk, part, metadata }) => {
+      if (chunk.type === "tool-input-available")
+        return { ...metadata, app: { toolCallId: chunk.toolCallId } }; // add to tool input chunks
+
+      if (part.type === "text") return null; // delete for text parts
+
+      return undefined; // leave everything else unchanged
+    }),
+  )
+  .toStream();
+```
+
 ### `.on()`
 
 Observe chunks without modifying the stream. The callback is invoked for matching chunks.
@@ -152,11 +177,13 @@ Observe chunks without modifying the stream. The callback is invoked for matchin
 ```typescript
 const stream = pipe(result.toUIMessageStream())
   .on(
-    ({ chunk, part }) => {
+    (predicate) => {
+      const { chunk, part } = predicate;
       // return true to invoke callback, false to skip
       return chunk.type === "text-delta";
     },
-    ({ chunk, part }) => {
+    (callback) => {
+      const { chunk, part } = callback;
       // callback invoked for matching chunks
       console.log(chunk, part);
     },
@@ -172,7 +199,10 @@ const stream = pipe(result.toUIMessageStream())
 - `partType("text")` or `partType(["text", "reasoning"])`: Observe chunks belonging to specific part types
 - `toolCall()` or `toolCall({ tool: "weather" })` or `toolCall({ state: "output-available" })`: Observe tool state transitions
 
-The `toolCall()` guard matches tool chunks representing state transitions (not streaming events):
+> [!NOTE]
+> The `partType` type guard still operates on chunks. That means `partType("text")` will match any text chunks such as `text-start`, `text-delta`, and `text-end`.
+
+The `toolCall()` type guard matches tool chunks representing state transitions (not streaming events):
 
 - `input-available`: Tool input fully parsed
 - `approval-requested`: Tool awaiting user approval
@@ -180,9 +210,6 @@ The `toolCall()` guard matches tool chunks representing state transitions (not s
 - `output-error`: Tool execution failed
 - `output-denied`: User denied approval
 
-> [!NOTE]
-> The `partType` type guard still operates on chunks. That means `partType("text")` will match any text chunks such as `text-start`, `text-delta`, and `text-end`.
-
 #### Examples
 
 Log stream lifecycle events.
@@ -196,26 +223,48 @@ const stream = pipe(result.toUIMessageStream())
     console.log("Stream finished:", chunk.finishReason);
   })
   .on(chunkType("tool-input-available"), ({ chunk }) => {
-    console.log("Tool input:", chunk.toolName, chunk.input);
+    console.log("Tool input:", chunk.input);
   })
   .on(chunkType("tool-output-available"), ({ chunk }) => {
-    console.log("Tool output:", chunk.toolName, chunk.output);
+    console.log("Tool output:", chunk.output);
   })
   .toStream();
 ```
 
-Observe tool state transitions.
+Observe tool state transitions for a specific tool.
 
 ```typescript
 const stream = pipe(result.toUIMessageStream())
   .on(toolCall({ tool: "weather", state: "approval-requested" }), ({ chunk }) => {
     console.log("Weather tool needs approval");
   })
+  .on(toolCall({ tool: "weather", state: "output-available" }), ({ chunk }) => {
+    console.log("Weather output:", chunk.output);
+  })
+  .on(toolCall({ tool: "weather", state: "input-available" }), ({ chunk }) => {
+    console.log("Weather input:", chunk.input);
+  })
   .toStream();
 ```
 
-> [!NOTE]
-> The `tool` option filters by part type (`tool-{name}`). Dynamic tools have part type `dynamic-tool`, so `toolCall({ tool: "myTool" })` will not match dynamic tools. Use `toolCall()` without the `tool` option to observe all tools including dynamic ones.
+Observe all tool calls.
+
+```typescript
+const stream = pipe(result.toUIMessageStream())
+  // on
+  .on(toolCall({ state: `input-available` }), ({ chunk, part }) => {
+    console.log(`Tool call ${part.type} (${chunk.toolCallId}) input=`, chunk.input);
+  })
+  /** onResult */
+  .on(toolCall({ state: `output-available` }), ({ chunk, part }) => {
+    console.log(`Tool result ${part.type} (${chunk.toolCallId}) output=`, chunk.output);
+  })
+  /** onError */
+  .on(toolCall({ state: `output-error` }), ({ chunk, part }) => {
+    console.log(`Tool error ${part.type} (${chunk.toolCallId}) error=`, chunk.errorText);
+  })
+  .toStream();
+```
 
 ### `.toStream()`
 

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 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-CNApJ39t.mjs";
 import "./utils/index.mjs";
-import { AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, UIDataTypes, UIMessage, UITools } from "ai";
+import { AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, ProviderMetadata, UIDataTypes, UIMessage, UITools } from "ai";
 
 //#region src/consume/consume-ui-message-stream.d.ts
 /**
@@ -553,6 +553,48 @@ type MapUIMessageStreamFn<UI_MESSAGE extends UIMessage> = (input: MapInput<UI_ME
  */
 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/transform-provider-metadata.d.ts
+/**
+ * A composable helper that plugs into the `.map()` operator to change provider
+ * metadata on the chunks that carry it:
+ *
+ * @example
+ * ```typescript
+ * pipe<MyUIMessage>(stream)
+ *   .map(transformProviderMetadata(({ metadata }) => ({ ...metadata, app: { id } })))
+ *   .toStream();
+ * ```
+ */
+/**
+ * Chunk variants in UI_MESSAGE that actually carry a `providerMetadata` field.
+ * Optional keys are still present in `keyof`, so this discriminates correctly:
+ * variants without the field (error, tool-output-*, start, finish, ...) drop to never.
+ */
+type ProviderMetadataChunk<UI_MESSAGE extends UIMessage> = InferUIMessageChunk<UI_MESSAGE> extends infer CHUNK ? CHUNK extends unknown ? "providerMetadata" extends keyof CHUNK ? CHUNK : never : never : never;
+/**
+ * Mapper invoked for every metadata-bearing chunk. Receives the chunk, its part
+ * type, and the current `providerMetadata` (may be undefined). Return value:
+ * - an object to set/replace `providerMetadata` (merge by spreading `metadata`)
+ * - `undefined` to leave the chunk unchanged
+ * - `null` to remove the `providerMetadata` field entirely
+ *
+ * `null` removes the field, not the chunk: the chunk always passes through.
+ */
+type ProviderMetadataTransformFn<UI_MESSAGE extends UIMessage> = (input: {
+  chunk: ProviderMetadataChunk<UI_MESSAGE>;
+  part: {
+    type: string;
+  };
+  metadata: ProviderMetadata | undefined;
+}) => ProviderMetadata | null | undefined;
+/**
+ * Creates a `.map()` callback that rewrites `providerMetadata` on metadata-bearing
+ * chunks and passes every other chunk through unchanged.
+ */
+declare function transformProviderMetadata<UI_MESSAGE extends UIMessage>(fn: ProviderMetadataTransformFn<UI_MESSAGE>): ChunkMapFn<UI_MESSAGE, InferUIMessageChunk<UI_MESSAGE>, {
+  type: string;
+}>;
+//#endregion
 //#region src/pipe/chunk-pipeline.d.ts
 /**
  * Pipeline for chunk-based operations.
@@ -859,4 +901,4 @@ declare function toolCall<UI_MESSAGE extends UIMessage, STATE extends ToolCallSt
   type: `tool-${InferToolName<UI_MESSAGE>}` | "dynamic-tool";
 }>;
 //#endregion
-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, excludeTools, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, includeTools, mapUIMessageStream, partType, partTypeIs, pipe, toolCall };
+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, excludeTools, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, includeTools, mapUIMessageStream, partType, partTypeIs, pipe, toolCall, transformProviderMetadata };

package/dist/index.mjs

@@ -606,6 +606,62 @@ function flatMapUIMessageStream(...args) {
 	return createAsyncIterableStream(convertAsyncIterableToStream(processChunks()));
 }
 
+//#endregion
+//#region src/pipe/transform-provider-metadata.ts
+/**
+* Runtime allow-list whose keys are pinned to `ProviderMetadataChunkType` by the
+* compiler. The AI SDK does not expose its zod chunk union for runtime
+* introspection (`uiMessageChunkSchema` is an async, non-introspectable `Schema`
+* wrapper), so completeness is enforced at the type level instead: if the SDK
+* adds or removes a metadata-bearing chunk, `ProviderMetadataChunkType` changes
+* and this literal stops compiling (missing key, or unknown key) until updated.
+*/
+const PROVIDER_METADATA_CHUNK_TYPES = {
+	"text-start": true,
+	"text-delta": true,
+	"text-end": true,
+	"reasoning-start": true,
+	"reasoning-delta": true,
+	"reasoning-end": true,
+	"tool-input-start": true,
+	"tool-input-available": true,
+	"tool-input-error": true,
+	"source-url": true,
+	"source-document": true,
+	file: true
+};
+/** Narrows any chunk to the metadata-bearing union via the pinned allow-list. */
+function isProviderMetadataChunk(chunk) {
+	return Object.hasOwn(PROVIDER_METADATA_CHUNK_TYPES, chunk.type);
+}
+/**
+* Creates a `.map()` callback that rewrites `providerMetadata` on metadata-bearing
+* chunks and passes every other chunk through unchanged.
+*/
+function transformProviderMetadata(fn) {
+	return ({ chunk, part }) => {
+		if (!isProviderMetadataChunk(chunk)) return chunk;
+		const metadata = chunk.providerMetadata;
+		const next = fn({
+			chunk,
+			part,
+			metadata
+		});
+		/** undefined leaves the chunk unchanged. */
+		if (next === void 0) return chunk;
+		/** null removes the field while keeping the chunk. */
+		if (next === null) {
+			const { providerMetadata: _omit, ...rest } = chunk;
+			return rest;
+		}
+		/** an object sets/replaces the field. */
+		return {
+			...chunk,
+			providerMetadata: next
+		};
+	};
+}
+
 //#endregion
 //#region src/pipe/chunk-pipeline.ts
 /**
@@ -968,4 +1024,4 @@ function toolCall(options) {
 }
 
 //#endregion
-export { chunkType, consumeUIMessageStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream, excludeChunks, excludeParts, excludeTools, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, includeTools, mapUIMessageStream, partType, partTypeIs, pipe, toolCall };
+export { chunkType, consumeUIMessageStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream, excludeChunks, excludeParts, excludeTools, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, includeTools, mapUIMessageStream, partType, partTypeIs, pipe, toolCall, transformProviderMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-stream-utils",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "AI SDK: Filter and transform UI messages while streaming to the client",
   "keywords": [
     "ai",
@@ -46,6 +46,7 @@
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/node": "^25.2.3",
     "ai": "^6.0.86",
+    "dotenv": "^17.4.2",
     "husky": "^9.1.7",
     "lint-staged": "^16.2.7",
     "msw": "^2.12.10",