ai-stream-utils 2.0.0 → 2.1.0

package/README.md

@@ -15,9 +15,9 @@ This library provides composable filter and transformation utilities for UI mess
 
 The AI SDK UI message stream created by [`toUIMessageStream()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text#to-ui-message-stream) streams all parts (text, tools, reasoning, etc.) to the client by default. However, you may want to:
 
-- **Filter**: Tool calls like database queries often contain large amounts of data or sensitive information that should not be streamed to the client
+- **Filter**: Tool calls like database searches often contain large amounts of data or sensitive information that should not be streamed to the client
 - **Transform**: Modify text or tool outputs while they are streamed to the client
-- **Observe**: Log stream lifecycle events, tool calls, or other chunks without consuming or modifying the stream
+- **Observe**: Log stream lifecycle events, update states, or run side-effects without modifying the stream
 
 This library provides type-safe, composable utilities for all these use cases.
 
@@ -52,21 +52,56 @@ const stream = pipe(result.toUIMessageStream())
   .toStream();
 ```
 
-**Type guards** provide a simpler API for common filtering patterns:
+#### Type Guards
 
-- `includeChunks("text-delta")` or `includeChunks(["text-delta", "text-end"])`: Include specific chunk types
-- `excludeChunks("text-delta")` or `excludeChunks(["text-delta", "text-end"])`: Exclude specific chunk types
-- `includeParts("text")` or `includeParts(["text", "reasoning"])`: Include specific part types
-- `excludeParts("reasoning")` or `excludeParts(["reasoning", "tool-database"])`: Exclude specific part types
+Generic type guards provide a simpler API for common filtering patterns:
 
-**Example:** Exclude tool calls from the client.
+- `includeChunks("text-delta")` or `includeChunks(["text-delta", "text-end"])`: Include **only** specific chunk types
+- `excludeChunks("text-delta")` or `excludeChunks(["text-delta", "text-end"])`: Exclude **only** specific chunk types
+- `includeParts("text")` or `includeParts(["text", "reasoning"])`: Include **only** specific part types
+- `excludeParts("reasoning")` or `excludeParts(["reasoning", "tool-database"])`: Exclude **only** specific part types
+
+Filtering tools is the most common use case and the tool-filter type guards provide a convenient API for filtering tool chunks by tool name:
+
+- `excludeTools()` or `excludeTools("weather")` or `excludeTools(["weather", "database"])`: Exclude all tools or specific tools by name
+- `includeTools()` or `includeTools("weather")` or `includeTools(["weather", "database"])`: Include all tools or specific tools by name
+
+> [!NOTE]
+> The tool-filter type guards only affect tool chunks. Non-tool chunks will pass through.
+
+#### Examples
+
+Exclude tool calls from the client.
 
 ```typescript
+// Exclude by part type (requires "tool-" prefix)
 const stream = pipe(result.toUIMessageStream())
   .filter(excludeParts(["tool-weather", "tool-database"]))
   .toStream();
+
+// Exclude by tool name (without "tool-" prefix)
+const stream = pipe(result.toUIMessageStream())
+  .filter(excludeTools(["weather", "database"]))
+  .toStream();
+
+// Exclude all tools
+const stream = pipe(result.toUIMessageStream()).filter(excludeTools()).toStream();
+
+// Include only specific tools (without "tool-" prefix)
+const stream = pipe(result.toUIMessageStream())
+  .filter(includeTools(["weather"]))
+  .toStream();
 ```
 
+> [!NOTE]
+> `excludeTools()` and `includeTools()` filters tool chunks on the server before streaming to the client. This affects all tool types including:
+>
+> - Server-side tools with `execute` functions
+> - Client-side tools without `execute` functions
+> - Tools that require human approval via `needsApproval`
+>
+> Excluded tools will not appear in the client's message parts, so users won't see tool call UI or be able to approve/reject filtered tools.
+
 ### `.map()`
 
 Transform chunks by returning a chunk, an array of chunks, or `null` to exclude.
@@ -94,7 +129,9 @@ const stream = pipe(result.toUIMessageStream())
   .toStream();
 ```
 
-**Example:** Convert text to uppercase.
+#### Examples
+
+Convert text to uppercase.
 
 ```typescript
 const stream = pipe(result.toUIMessageStream())
@@ -127,6 +164,8 @@ const stream = pipe(result.toUIMessageStream())
   .toStream();
 ```
 
+#### Type Guards
+
 **Type guard** provides a type-safe way to observe specific chunk types:
 
 - `chunkType("text-delta")` or `chunkType(["start", "finish"])`: Observe specific chunk types
@@ -135,18 +174,23 @@ const stream = pipe(result.toUIMessageStream())
 > [!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`.
 
-**Example:** Log stream lifecycle events.
+#### Examples
+
+Log stream lifecycle events.
 
 ```typescript
 const stream = pipe(result.toUIMessageStream())
-  .on(chunkType("start"), () => {
-    console.log("Stream started");
+  .on(chunkType("start"), ({ chunk }) => {
+    console.log("Stream started:", chunk.messageId);
   })
   .on(chunkType("finish"), ({ chunk }) => {
     console.log("Stream finished:", chunk.finishReason);
   })
   .on(chunkType("tool-input-available"), ({ chunk }) => {
-    console.log("Tool called:", chunk.toolName, chunk.input);
+    console.log("Tool input:", chunk.toolName, chunk.input);
+  })
+  .on(chunkType("tool-output-available"), ({ chunk }) => {
+    console.log("Tool output:", chunk.toolName, chunk.output);
   })
   .toStream();
 ```
@@ -183,8 +227,8 @@ Multiple operators can be chained together. After filtering with type guards, ch
 const stream = pipe<MyUIMessage>(result.toUIMessageStream())
   .filter(includeParts("text"))
   .map(({ chunk, part }) => {
-    // chunk is narrowed to text chunks only
-    // part.type is narrowed to "text"
+    // chunk is narrowed to text chunks: "text-start" | "text-delta" | "text-end"
+    // part is narrowed to "text"
     return chunk;
   })
   .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 "./utils/index.mjs";
-import { AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, UIMessage } from "ai";
+import { AsyncIterableStream as AsyncIterableStream$1, InferUIMessageChunk, UIDataTypes, UIMessage, UITools } from "ai";
 
 //#region src/consume/consume-ui-message-stream.d.ts
 /**
@@ -181,6 +181,7 @@ declare function filterUIMessageStream<UI_MESSAGE extends UIMessage>(stream: Rea
 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"];
+type InferUIMessageTools<UI_MESSAGE extends UIMessage> = UI_MESSAGE extends UIMessage<unknown, UIDataTypes, infer TOOLS> ? TOOLS : UITools;
 /**
  * Extracts chunk type strings that match the prefix exactly or as `${PREFIX}-*`.
  * Dynamically derives chunk types from the actual UIMessageChunk union.
@@ -318,6 +319,32 @@ type InferPartForChunk<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends string>
  * ```
  */
 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>];
+/**
+ * Extract tool names from UIMessage tools.
+ *
+ * @example
+ * ```typescript
+ * type Tools = InferToolName<MyUIMessage>;
+ * // => 'weather' | 'calculator'
+ * ```
+ */
+type InferToolName<UI_MESSAGE extends UIMessage> = keyof InferUIMessageTools<UI_MESSAGE> & string;
+/**
+ * All tool-related part types (tool-* and dynamic-tool).
+ */
+type ToolPartTypes<UI_MESSAGE extends UIMessage> = Extract<InferUIMessagePartType<UI_MESSAGE>, `tool-${string}` | `dynamic-tool`>;
+/**
+ * Part types remaining after excluding all tools.
+ */
+type ExcludeToolPartTypes<UI_MESSAGE extends UIMessage> = Exclude<InferUIMessagePartType<UI_MESSAGE>, ToolPartTypes<UI_MESSAGE>>;
+/**
+ * Chunk types for tools (tool-input-*, tool-output-*, etc.).
+ */
+type ToolChunkTypes<UI_MESSAGE extends UIMessage> = Extract<InferUIMessageChunkType<UI_MESSAGE>, `tool-${string}`>;
+/**
+ * Content chunk types remaining after excluding all tool chunks.
+ */
+type ExcludeToolChunkTypes<UI_MESSAGE extends UIMessage> = Exclude<ContentChunkType<UI_MESSAGE>, ToolChunkTypes<UI_MESSAGE>>;
 //#endregion
 //#region src/flat-map/flat-map-ui-message-stream.d.ts
 /**
@@ -529,9 +556,9 @@ declare class ChunkPipeline<UI_MESSAGE extends UIMessage, CHUNK extends InferUIM
    * 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>;
+  filter<NARROWED_CHUNK extends CHUNK, NARROWED_PART extends {
+    type: PART[`type`];
+  }>(guard: FilterGuard<UI_MESSAGE, NARROWED_CHUNK, NARROWED_PART>): ChunkPipeline<UI_MESSAGE, CHUNK & NARROWED_CHUNK, PART & NARROWED_PART>;
   /**
    * Filters chunks using a generic predicate function.
    * The callback only receives content chunks because meta chunks pass through unchanged.
@@ -549,8 +576,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 InferUIMessageChunk<UI_MESSAGE>, NARROWED_PART extends {
-    type: string;
+  on<NARROWED_CHUNK extends CHUNK, NARROWED_PART extends {
+    type: PART[`type`];
   } | 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.
@@ -638,7 +665,7 @@ declare function includeParts<UI_MESSAGE extends UIMessage, PART_TYPE extends In
  *   .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>>, {
+declare function excludeChunks<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends ContentChunkType<UI_MESSAGE>>(types: CHUNK_TYPE | Array<CHUNK_TYPE>): FilterGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, Exclude<ContentChunkType<UI_MESSAGE>, CHUNK_TYPE>>, {
   type: ExcludePartForChunks<UI_MESSAGE, CHUNK_TYPE>;
 }>;
 /**
@@ -656,7 +683,7 @@ declare function excludeChunks<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends
  *   .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>>>, {
+declare function excludeParts<UI_MESSAGE extends UIMessage, PART_TYPE extends InferUIMessagePartType<UI_MESSAGE>>(types: PART_TYPE | Array<PART_TYPE>): FilterGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, Exclude<ContentChunkType<UI_MESSAGE>, PartTypeToChunkTypes<UI_MESSAGE, PART_TYPE>>>, {
   type: Exclude<InferUIMessagePartType<UI_MESSAGE>, PART_TYPE>;
 }>;
 /**
@@ -707,5 +734,61 @@ declare function chunkType<UI_MESSAGE extends UIMessage, CHUNK_TYPE extends Infe
 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;
 }>;
+/**
+ * Creates a filter guard that includes only specific tools while keeping non-tool chunks.
+ * Use with `.filter()` to include only specific tools.
+ *
+ * @example
+ * ```typescript
+ * // No-op: all chunks pass through
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeTools())
+ *   .map(({ chunk }) => chunk); // all chunks pass
+ *
+ * // Include specific tool (non-tool chunks still pass)
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeTools('weather'))
+ *   .map(({ chunk }) => chunk); // text + tool-weather chunks
+ *
+ * // Include multiple tools
+ * pipe<MyUIMessage>(stream)
+ *   .filter(includeTools(['weather', 'calculator']))
+ *   .map(({ chunk }) => chunk); // text + specified tool chunks
+ * ```
+ */
+declare function includeTools<UI_MESSAGE extends UIMessage>(): FilterGuard<UI_MESSAGE, InferUIMessageChunk<UI_MESSAGE>, {
+  type: InferUIMessagePartType<UI_MESSAGE>;
+}>;
+declare function includeTools<UI_MESSAGE extends UIMessage, TOOL_NAME extends InferToolName<UI_MESSAGE>>(toolNames: TOOL_NAME | Array<TOOL_NAME>): FilterGuard<UI_MESSAGE, InferUIMessageChunk<UI_MESSAGE>, {
+  type: ExcludeToolPartTypes<UI_MESSAGE> | `tool-${TOOL_NAME}`;
+}>;
+/**
+ * Creates a filter guard that excludes all or only specific tools while keeping non-tool chunks.
+ * Use with `.filter()` to exclude specific tools or all tools.
+ *
+ * @example
+ * ```typescript
+ * // Exclude all tools
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeTools())
+ *   .map(({ chunk }) => chunk); // no tool chunks
+ *
+ * // Exclude specific tool
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeTools('weather'))
+ *   .map(({ chunk }) => chunk); // excludes tool-weather chunks
+ *
+ * // Exclude multiple tools
+ * pipe<MyUIMessage>(stream)
+ *   .filter(excludeTools(['weather', 'calculator']))
+ *   .map(({ chunk }) => chunk); // excludes weather and calculator
+ * ```
+ */
+declare function excludeTools<UI_MESSAGE extends UIMessage>(): FilterGuard<UI_MESSAGE, ExtractChunk<UI_MESSAGE, ExcludeToolChunkTypes<UI_MESSAGE>>, {
+  type: ExcludeToolPartTypes<UI_MESSAGE>;
+}>;
+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}`>;
+}>;
 //#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, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, 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 };

package/dist/index.mjs

@@ -908,6 +908,35 @@ function partType(types) {
 	const guard = (input) => typeArray.includes(input.part?.type);
 	return guard;
 }
+function includeTools(toolNames) {
+	const toolNameArray = toolNames === void 0 ? void 0 : Array.isArray(toolNames) ? toolNames : [toolNames];
+	const guard = (input) => {
+		/** No args = no-op, all chunks pass */
+		if (toolNameArray === void 0) return true;
+		const partType = input.part?.type;
+		if (!partType) return true;
+		/** Non-tool chunks pass */
+		if (!partType.startsWith(`tool-`) && partType !== `dynamic-tool`) return true;
+		/** Only matching tool chunks pass */
+		for (const name of toolNameArray) if (partType === `tool-${name}`) return true;
+		return false;
+	};
+	return guard;
+}
+function excludeTools(toolNames) {
+	const toolNameArray = toolNames === void 0 ? void 0 : Array.isArray(toolNames) ? toolNames : [toolNames];
+	const guard = (input) => {
+		const partType = input.part?.type;
+		/** Meta chunks pass (no part type) */
+		if (!partType) return true;
+		/** No args = exclude all tool chunks */
+		if (toolNameArray === void 0) return !partType.startsWith(`tool-`) && partType !== `dynamic-tool`;
+		/** Exclude only matching tool chunks */
+		for (const name of toolNameArray) if (partType === `tool-${name}`) return false;
+		return true;
+	};
+	return guard;
+}
 
 //#endregion
-export { chunkType, consumeUIMessageStream, convertArrayToAsyncIterable, convertArrayToStream, convertAsyncIterableToArray, convertAsyncIterableToStream, convertSSEToUIMessageStream, convertStreamToArray, convertUIMessageToSSEStream, createAsyncIterableStream, excludeChunks, excludeParts, filterUIMessageStream, flatMapUIMessageStream, includeChunks, includeParts, 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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-stream-utils",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "AI SDK: Filter and transform UI messages while streaming to the client",
   "keywords": [
     "ai",