ai-stream-utils 2.1.0 → 2.2.0

package/README.md

@@ -170,6 +170,15 @@ 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
+
+The `toolCall()` 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
 
 > [!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`.
@@ -195,6 +204,19 @@ const stream = pipe(result.toUIMessageStream())
   .toStream();
 ```
 
+Observe tool state transitions.
+
+```typescript
+const stream = pipe(result.toUIMessageStream())
+  .on(toolCall({ tool: "weather", state: "approval-requested" }), ({ chunk }) => {
+    console.log("Weather tool needs approval");
+  })
+  .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.
+
 ### `.toStream()`
 
 Convert the pipeline back to a `AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>` that can be returned to the client or consumed.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-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";
 
@@ -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
 /**
@@ -576,8 +591,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 +805,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 };

package/dist/index.mjs

@@ -937,6 +937,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 };

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.2.0",
   "description": "AI SDK: Filter and transform UI messages while streaming to the client",
   "keywords": [
     "ai",
@@ -41,6 +41,7 @@
     "@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",