ai-stream-utils 2.1.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);
     },
@@ -170,10 +197,19 @@ const stream = pipe(result.toUIMessageStream())
 
 - `chunkType("text-delta")` or `chunkType(["start", "finish"])`: Observe specific chunk types
 - `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
 
 > [!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
+- `output-available`: Tool execution completed
+- `output-error`: Tool execution failed
+- `output-denied`: User denied approval
+
 #### Examples
 
 Log stream lifecycle events.
@@ -187,10 +223,45 @@ 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 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();
+```
+
+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();
 ```

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-B4nePmEd.mjs";
+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
 /**
@@ -345,6 +345,21 @@ type ToolChunkTypes<UI_MESSAGE extends UIMessage> = Extract<InferUIMessageChunkT
  * Content chunk types remaining after excluding all tool chunks.
  */
 type ExcludeToolChunkTypes<UI_MESSAGE extends UIMessage> = Exclude<ContentChunkType<UI_MESSAGE>, ToolChunkTypes<UI_MESSAGE>>;
+/**
+ * Tool states that have corresponding stream chunks.
+ * These are the "final" states from UIToolInvocation, not streaming events.
+ */
+type ToolCallState = "input-available" | "approval-requested" | "output-available" | "output-error" | "output-denied";
+/**
+ * Map tool states to their corresponding chunk types.
+ */
+type ToolStateToChunkType = {
+  "input-available": "tool-input-available";
+  "approval-requested": "tool-approval-request";
+  "output-available": "tool-output-available";
+  "output-error": "tool-output-error";
+  "output-denied": "tool-output-denied";
+};
 //#endregion
 //#region src/flat-map/flat-map-ui-message-stream.d.ts
 /**
@@ -538,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.
@@ -576,8 +633,8 @@ declare class ChunkPipeline<UI_MESSAGE extends UIMessage, CHUNK extends InferUIM
    * 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 CHUNK, NARROWED_PART extends {
-    type: PART[`type`];
+  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.
@@ -790,5 +847,58 @@ declare function excludeTools<UI_MESSAGE extends UIMessage>(): FilterGuard<UI_ME
 declare function excludeTools<UI_MESSAGE extends UIMessage, TOOL_NAME extends InferToolName<UI_MESSAGE>>(toolNames: TOOL_NAME | Array<TOOL_NAME>): FilterGuard<UI_MESSAGE, InferUIMessageChunk<UI_MESSAGE>, {
   type: Exclude<InferUIMessagePartType<UI_MESSAGE>, `tool-${TOOL_NAME}`>;
 }>;
+/**
+ * Creates an observe guard that matches tool call chunks by tool name and/or state.
+ * Use with `.on()` to observe tool call state transitions without filtering.
+ *
+ * @example
+ * ```typescript
+ * // Match all tool state transitions (any tool, any state)
+ * pipe<MyUIMessage>(stream)
+ *   .on(toolCall(), ({ chunk, part }) => {
+ *     // Observes: tool-input-available, tool-approval-request,
+ *     // tool-output-available, tool-output-error, tool-output-denied
+ *   });
+ *
+ * // Match specific tool (any state)
+ * pipe<MyUIMessage>(stream)
+ *   .on(toolCall({ tool: "weather" }), ({ chunk, part }) => {
+ *     // part.type is 'tool-weather'
+ *   });
+ *
+ * // Match specific state (all tools)
+ * pipe<MyUIMessage>(stream)
+ *   .on(toolCall({ state: "output-available" }), ({ chunk, part }) => {
+ *     // chunk.type is 'tool-output-available'
+ *   });
+ *
+ * // Match specific tool AND state
+ * pipe<MyUIMessage>(stream)
+ *   .on(toolCall({ tool: "weather", state: "output-available" }), ({ chunk, part }) => {
+ *     // chunk.type is 'tool-output-available', part.type is 'tool-weather'
+ *   });
+ * ```
+ */
+declare function toolCall<UI_MESSAGE extends UIMessage>(): ObserveGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, ToolStateToChunkType[ToolCallState]>, {
+  type: `tool-${InferToolName<UI_MESSAGE>}` | "dynamic-tool";
+}>;
+declare function toolCall<UI_MESSAGE extends UIMessage, TOOL_NAME extends InferToolName<UI_MESSAGE>, STATE extends ToolCallState>(options: {
+  tool: TOOL_NAME;
+  state: STATE;
+}): ObserveGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, ToolStateToChunkType[STATE]>, {
+  type: `tool-${TOOL_NAME}`;
+}>;
+declare function toolCall<UI_MESSAGE extends UIMessage, TOOL_NAME extends InferToolName<UI_MESSAGE>>(options: {
+  tool: TOOL_NAME;
+  state?: undefined;
+}): ObserveGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, ToolStateToChunkType[ToolCallState]>, {
+  type: `tool-${TOOL_NAME}`;
+}>;
+declare function toolCall<UI_MESSAGE extends UIMessage, STATE extends ToolCallState>(options: {
+  tool?: undefined;
+  state: STATE;
+}): ObserveGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, ToolStateToChunkType[STATE]>, {
+  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 };
+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
 /**
@@ -937,6 +993,35 @@ function excludeTools(toolNames) {
 	};
 	return guard;
 }
+/**
+* Reverse mapping from chunk type to state.
+*/
+const chunkTypeToState = Object.fromEntries(Object.entries({
+	"input-available": "tool-input-available",
+	"approval-requested": "tool-approval-request",
+	"output-available": "tool-output-available",
+	"output-error": "tool-output-error",
+	"output-denied": "tool-output-denied"
+}).map(([state, chunkType]) => [chunkType, state]));
+function toolCall(options) {
+	const toolName = options?.tool;
+	const state = options?.state;
+	const guard = (input) => {
+		const chunkType = input.chunk.type;
+		const partType = input.part?.type;
+		/** Must be a tool chunk type that maps to a state */
+		const matchingState = chunkTypeToState[chunkType];
+		if (!matchingState) return false;
+		/** Check state match */
+		if (state && matchingState !== state) return false;
+		/** Check tool name match */
+		if (toolName && partType) {
+			if (partType !== `tool-${toolName}`) return false;
+		}
+		return true;
+	};
+	return guard;
+}
 
 //#endregion
-export { chunkType, consumeUIMessageStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream, excludeChunks, excludeParts, excludeTools, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, includeTools, mapUIMessageStream, partType, partTypeIs, pipe };
+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/dist/{types-B4nePmEd.d.mts → types-CNApJ39t.d.mts}

@@ -1,4 +1,4 @@
-import { AsyncIterableStream, AsyncIterableStream as AsyncIterableStream$1, UIMessageChunk } from "ai";
+import { AsyncIterableStream, AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, UIMessage, UIMessageChunk } from "ai";
 
 //#region src/utils/convert-array-to-async-iterable.d.ts
 /**
@@ -29,7 +29,7 @@ declare function convertAsyncIterableToStream<T>(iterable: AsyncIterable<T>): Re
 /**
  * Converts an SSE stream to a UI message stream.
  */
-declare function convertSSEToUIMessageStream(stream: ReadableStream<string>): ReadableStream<UIMessageChunk>;
+declare function convertSSEToUIMessageStream<UI_MESSAGE extends UIMessage = UIMessage>(stream: ReadableStream<string>): ReadableStream<InferUIMessageChunk<UI_MESSAGE>>;
 //#endregion
 //#region src/utils/convert-stream-to-array.d.ts
 /**

package/dist/utils/index.d.mts

@@ -1,2 +1,2 @@
-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 { 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";
 export { type AsyncIterableStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-stream-utils",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "AI SDK: Filter and transform UI messages while streaming to the client",
   "keywords": [
     "ai",
@@ -41,10 +41,12 @@
     "@ai-sdk/openai": "^3.0.29",
     "@ai-sdk/provider": "^3.0.8",
     "@ai-sdk/provider-utils": "^4.0.15",
+    "@ai-sdk/react": "^3.0.110",
     "@arethetypeswrong/cli": "^0.18.2",
     "@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",