ai-test-kit 0.0.1 → 1.0.1

package/README.md

@@ -1,26 +1,21 @@
 # ai-test-kit
 
-<p align="center">Test utilities for the AI SDK: mock models, content and stream-part builders, fully type-safe</p>
+<p align="center">Test Kit for AI SDK: mock models, content builders and stream helpers, fully type-safe</p>
 <p align="center">
   <a href="https://www.npmjs.com/package/ai-test-kit" alt="ai-test-kit"><img src="https://img.shields.io/npm/dt/ai-test-kit?label=ai-test-kit"></a> <a href="https://github.com/zirkelc/ai-test-kit/actions/workflows/ci.yml" alt="CI"><img src="https://img.shields.io/github/actions/workflow/status/zirkelc/ai-test-kit/ci.yml?branch=main"></a>
 </p>
 
-This library provides ergonomic, type-safe helpers for testing code built on the AI SDK: a fluent API to mock [`generateText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) / [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text), build content and stream parts, and assert on results. It implements its own `LanguageModelV3` mock and builds on the AI SDK's own stream helpers (`simulateReadableStream` and the stream converters).
+This library provides a simple, type-safe API for testing AI SDK-powered apps. It gives you small, composable builders for mocking models, generating content and stream parts, and asserting on the results, so your tests stay short, deterministic, and fully typed.
 
 ### Why?
 
-The AI SDK ships `MockLanguageModelV3` and other helpers under `ai/test`, but they are deliberately low-level. In practice every project ends up rebuilding the same helpers to:
+The AI SDK ships `MockLanguageModelV3` and a few other test primitives, but they are deliberately low-level. In practice every project ends up rebuilding the same helpers to:
 
 - **Mock a model**: return text, throw an error, or replay a scripted response per call
-- **Build content and stream parts**: assemble valid `text-start` → `text-delta` → `text-end` → `finish` streams by hand
+- **Generate content and stream parts**: assemble valid `text-start` → `text-delta` → `text-end` → `finish` streams by hand
 - **Keep tests deterministic**: pin message ids and timestamps so snapshots are stable
 
-This library provides those helpers as small, composable builders. Models are `vi.fn()` spies, so you can assert on calls with the full Vitest API while also reading the recorded call arguments directly.
-
-Helpers are split by layer, each under its own entry point so an import only pulls in the types it needs:
-
-- `ai-test-kit/language` — the model layer: mock a `LanguageModelV3`, build `LanguageModelV3Content` and stream parts (and later `ai-test-kit/embedding`, `ai-test-kit/image`)
-- `ai-test-kit/ui` — the UI layer: build `UIMessagePart`, `UIMessageChunk`, and `UIMessage` fixtures, optionally typed to your own `UIMessage`
+This library ships those helpers, ready to use. Models are `vi.fn()` spies, so you can assert on calls with the full Vitest API while also reading the recorded call arguments directly.
 
 ### Installation
 
@@ -32,6 +27,11 @@ npm install -D ai-test-kit
 
 ## Usage
 
+The API is split by layer, each under its own entry point so an import only pulls in the types it needs:
+
+- `ai-test-kit/language` — the model layer: mock a `LanguageModelV3`, generate `LanguageModelV3Content` for [`generateText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text) and stream parts `LanguageModelV3StreamPart[]` for [`streamText()`](https://ai-sdk.dev/docs/reference/ai-sdk-core/stream-text)
+- `ai-test-kit/ui` — the UI layer: build `UIMessagePart`, `UIMessageChunk`, and `UIMessage` fixtures, optionally typed to your own `UIMessage`
+
 ### Language Models
 
 Helpers from `ai-test-kit/language` to mock a model and build the content and stream parts it returns.
@@ -108,14 +108,14 @@ result.toolCalls[0].toolName; // 'weather'
 
 #### Usage and Finish Reason
 
-By default a mock reports a `stop` finish reason and a small fixed token usage. Override them via the `{ content, finishReason, usage }` form to test code that branches on the finish reason or tracks token usage.
+By default a mock reports a `stop` finish reason and a small fixed token usage. Override them via the `{ content, finishReason, usage }` form to test code that branches on the finish reason or tracks token usage. `finishReason` accepts a bare unified string (`'length'`) or a full object via `MockLanguageModel.finishReason(...)`.
 
 ```typescript
 import { Content, MockLanguageModel } from 'ai-test-kit/language';
 
 const model = MockLanguageModel.from({
   content: [Content.text('truncated…')],
-  finishReason: MockLanguageModel.finishReason('length'),
+  finishReason: 'length',
   usage: MockLanguageModel.usage({ outputTokens: { total: 50 } }),
 });
 
@@ -154,6 +154,23 @@ const model = MockLanguageModel.from({
 });
 ```
 
+#### Aborting a Stream
+
+The call's `abortSignal` is wired into the simulated stream automatically, so a stream aborted mid-flight errors with an `AbortError` just like a real provider — no custom `ReadableStream` needed. Pair it with `chunkDelayInMs` so the abort can land between chunks.
+
+```typescript
+import { MockLanguageModel, StreamParts } from 'ai-test-kit/language';
+
+const controller = new AbortController();
+
+const model = MockLanguageModel.from({
+  stream: { chunks: [...StreamParts.text('Hello World'), StreamParts.finish()], chunkDelayInMs: 10 },
+});
+
+const result = streamText({ model, prompt: 'Hi', abortSignal: controller.signal });
+// ...later, controller.abort() makes the stream reject with an AbortError
+```
+
 #### Different Responses per Method
 
 Use the `{ generate, stream }` form to drive `doGenerate` and `doStream` independently — for example to return plain text non-streaming but a richer sequence when streamed.
@@ -167,6 +184,18 @@ const model = MockLanguageModel.from({
 });
 ```
 
+#### Input-Dependent Responses
+
+For a response that depends on the call (the prompt, tools, or settings), pass a function to `generate` / `stream`. It receives the `doGenerate` / `doStream` call options and returns the result directly — the escape hatch for cases the declarative forms can't express, including a fully custom `LanguageModelV3StreamResult`. The result builders pair well here.
+
+```typescript
+import { MockLanguageModel } from 'ai-test-kit/language';
+
+const model = MockLanguageModel.from({
+  generate: async ({ prompt }) => MockLanguageModel.generateResult(prompt.length > 1 ? 'multi-turn' : 'single-turn'),
+});
+```
+
 #### Inspecting Streams
 
 Use `Stream` to build, drain, and read stream parts when asserting.
@@ -307,6 +336,7 @@ MockLanguageModel.from(input?: MockResponse | MockResponse[], options?: MockLang
 // MockLanguageModel.from(new Error('429')): a model that throws from generate and stream
 // MockLanguageModel.from({ content: [Content.text('Hi')] }): a model returning those parts (stream derived from them)
 // MockLanguageModel.from({ generate: 'A', stream: [...] }): drives doGenerate and doStream independently
+// MockLanguageModel.from({ generate: (options) => result }): a function of the call options (input-dependent)
 // MockLanguageModel.from([new Error('429'), 'ok']): sequences responses per call, clamping to the last
 ```
 
@@ -332,9 +362,10 @@ MockLanguageModel.generateResult(input: string | { content: LanguageModelV3Conte
 #### `.streamResult(input, options?)`
 
 ```ts
-MockLanguageModel.streamResult(input: string | LanguageModelV3StreamPart[], options?: StreamDelayOptions): LanguageModelV3StreamResult
+MockLanguageModel.streamResult(input: string | LanguageModelV3StreamPart[] | ReadableStream<LanguageModelV3StreamPart>, options?: StreamDelayOptions): LanguageModelV3StreamResult
 // MockLanguageModel.streamResult('hi'): { stream } — a ReadableStream of stream-start → text → finish
 // MockLanguageModel.streamResult([...StreamParts.text('hi'), StreamParts.finish()]): { stream } — a ReadableStream of the given parts
+// MockLanguageModel.streamResult(Stream.from(parts)): { stream } — wraps an existing ReadableStream as-is (delays ignored)
 ```
 
 #### `.usage(overrides?)`
@@ -510,6 +541,13 @@ Stream.toArray<T>(stream: ReadableStream<T>): Promise<T[]>
 // Stream.toArray(stream): Promise<[a, b]>
 ```
 
+#### `.toIterable(stream)`
+
+```ts
+Stream.toIterable<T>(stream: ReadableStream<T>): ReadableStream<T> & AsyncIterable<T>
+// for await (const part of Stream.toIterable(stream)) { ... } — consume a stream via for-await
+```
+
 #### `.text(parts)`
 
 ```ts
@@ -524,6 +562,31 @@ Stream.finishReason(parts: LanguageModelV3StreamPart[]): LanguageModelV3FinishRe
 // Stream.finishReason([StreamParts.finish()]): { unified: 'stop', raw: 'stop' }
 ```
 
+#### `Iterable`
+
+The async-iterable complement to `Stream`: build, drain, and convert `AsyncIterable`s (async generators, and anything consumed via `for await`). Use it when the code under test produces or consumes a plain async iterable rather than a `ReadableStream`. Cross back to the `Stream` toolbox with `.toStream`.
+
+#### `.from(items)`
+
+```ts
+Iterable.from<T>(items: T[]): AsyncIterable<T>
+// Iterable.from([a, b]): an async iterable yielding a, then b
+```
+
+#### `.toArray(iterable)`
+
+```ts
+Iterable.toArray<T>(iterable: AsyncIterable<T>): Promise<T[]>
+// Iterable.toArray(iterable): Promise<[a, b]>
+```
+
+#### `.toStream(iterable)`
+
+```ts
+Iterable.toStream<T>(iterable: AsyncIterable<T>): ReadableStream<T>
+// Iterable.toStream(iterable): a ReadableStream emitting a, then b
+```
+
 #### `Options`
 
 Determinism helpers to spread into `generateText()` / `streamText()`.
@@ -886,7 +949,7 @@ import type { MockLanguageModel } from 'ai-test-kit/language';
 
 ### `GenerateResponse` / `StreamResponse`
 
-The per-method response shapes used by the `{ generate, stream }` form of `MockResponse`. `stream` accepts a bare `Array<StreamPart>`, or a `{ chunks, initialDelayInMs?, chunkDelayInMs? }` object to simulate delays.
+The per-method response shapes used by the `{ generate, stream }` form of `MockResponse`. `stream` accepts a bare `Array<StreamPart>`, a `ReadableStream<StreamPart>` (used as-is), or a `{ chunks, initialDelayInMs?, chunkDelayInMs? }` object to simulate delays. Both also accept a `string`, an `Error`, or a **function** of the call options returning the result directly (the escape hatch for input-dependent responses).
 
 ```ts
 import type { GenerateResponse, StreamResponse } from 'ai-test-kit/language';
@@ -912,11 +975,11 @@ import type { StreamPartOptions } from 'ai-test-kit/language';
 
 ### `StreamDelayOptions`
 
-Simulated timing shared by `Stream.simulate`, `MockLanguageModel.streamResult`, and the `stream` chunks form.
+Simulated timing shared by `Stream.simulate`, `MockLanguageModel.streamResult`, and the `stream` chunks form. With an `abortSignal`, the stream errors with an `AbortError` the instant the signal fires (mid-delay), matching a real provider stream.
 
 ```ts
 import type { StreamDelayOptions } from 'ai-test-kit/language';
-// { initialDelayInMs?: number; chunkDelayInMs?: number }
+// { initialDelayInMs?: number | null; chunkDelayInMs?: number | null; abortSignal?: AbortSignal }
 ```
 
 ## License

package/dist/language/index.d.mts

@@ -4,29 +4,40 @@ import { LanguageModelV3, LanguageModelV3CallOptions, LanguageModelV3Content, La
 //#region src/language/stream.d.ts
 /** Simulated timing for a stream. Shared by `Stream.simulate`, `MockLanguageModel.streamResult`, and the `stream` chunks form. */
 type StreamDelayOptions = {
-  /** Delay before the first part is emitted. */initialDelayInMs?: number; /** Delay between each subsequent part. */
-  chunkDelayInMs?: number;
+  /** Delay before the first part is emitted; `null` skips the delay. Defaults to `0`. */initialDelayInMs?: number | null; /** Delay between each subsequent part; `null` skips the delay. Defaults to `0`. */
+  chunkDelayInMs?: number | null; /** When provided, the stream errors with an `AbortError` the instant the signal fires. */
+  abortSignal?: AbortSignal;
 };
 /** Operations for building, draining, and inspecting language model streams in tests. */
 declare const Stream: {
   /** Builds a `ReadableStream` from an array of parts. */from: <PART>(parts: Array<PART>) => ReadableStream<PART>; /** Builds a `ReadableStream` that emits parts with optional delays, for timing tests. */
   simulate: <PART>(chunks: Array<PART>, opts?: StreamDelayOptions) => ReadableStream<PART>; /** Reads a stream to completion and returns every part it emitted. */
-  toArray: <PART>(stream: ReadableStream<PART>) => Promise<Array<PART>>; /** Joins the `text-delta` parts of a stream-part sequence into the full text. */
+  toArray: <PART>(stream: ReadableStream<PART>) => Promise<Array<PART>>; /** Wraps a `ReadableStream` so it can also be consumed via `for await`. */
+  toIterable: <PART>(stream: ReadableStream<PART>) => ReadableStream<PART> & AsyncIterable<PART>; /** Joins the `text-delta` parts of a stream-part sequence into the full text. */
   text: (parts: Array<LanguageModelV3StreamPart>) => string; /** Returns the finish reason from a stream-part sequence, if a `finish` part is present. */
   finishReason: (parts: Array<LanguageModelV3StreamPart>) => LanguageModelV3FinishReason | undefined;
 };
 //#endregion
 //#region src/language/mock-language-model.d.ts
 /** A (possibly partial) non-streaming result; only `content` is required, the rest defaults. */
-type GenerateResultInput = Partial<LanguageModelV3GenerateResult> & {
-  content: Array<LanguageModelV3Content>;
+type GenerateResultInput = Omit<Partial<LanguageModelV3GenerateResult>, 'finishReason'> & {
+  content: Array<LanguageModelV3Content>; /** The finish reason, as a full object or a bare unified value (e.g. `'length'`). */
+  finishReason?: LanguageModelV3FinishReason | LanguageModelV3FinishReason['unified'];
 };
-/** How to respond to a `doGenerate` call. */
+/**
+ * How to respond to a `doGenerate` call. A function receives the call options and returns the generate
+ * result directly — the escape hatch for input-dependent responses.
+ */
 type GenerateResponse = string | Error | GenerateResultInput | LanguageModelV3['doGenerate'];
-/** How to respond to a `doStream` call. A bare array streams without delay; the object form adds delays. */
-type StreamResponse = string | Error | Array<LanguageModelV3StreamPart> | ({
+/**
+ * How to respond to a `doStream` call. A bare array (or `ReadableStream`) streams without delay; the
+ * `{ chunks, ... }` form adds delays and abort handling. A function receives the call options and
+ * returns the stream result directly — the escape hatch for input-dependent streams or a fully custom
+ * `LanguageModelV3StreamResult` (e.g. one carrying response metadata).
+ */
+type StreamResponse = string | Error | Array<LanguageModelV3StreamPart> | ReadableStream<LanguageModelV3StreamPart> | ({
   chunks: Array<LanguageModelV3StreamPart>;
-} & StreamDelayOptions) | LanguageModelV3StreamResult | LanguageModelV3['doStream'];
+} & StreamDelayOptions) | LanguageModelV3['doStream'];
 /**
  * A single mock response. A `string` or `Error` applies to whichever method is called;
  * the object forms target one method explicitly.
@@ -84,7 +95,7 @@ declare const MockLanguageModel: {
   from: (input?: MockResponse | Array<MockResponse>, options?: MockLanguageModelOptions) => LanguageModelMock;
   content: (input: string | Array<LanguageModelV3Content>) => Array<LanguageModelV3Content>;
   generateResult: (input: string | GenerateResultInput) => LanguageModelV3GenerateResult;
-  streamResult: (input: string | Array<LanguageModelV3StreamPart>, opts?: StreamDelayOptions) => LanguageModelV3StreamResult;
+  streamResult: (input: string | Array<LanguageModelV3StreamPart> | ReadableStream<LanguageModelV3StreamPart>, opts?: StreamDelayOptions) => LanguageModelV3StreamResult;
   usage: (overrides?: {
     inputTokens?: Partial<LanguageModelV3Usage["inputTokens"]>;
     outputTokens?: Partial<LanguageModelV3Usage["outputTokens"]>;
@@ -188,6 +199,20 @@ declare const StreamParts: {
   raw: (rawValue: unknown) => LanguageModelV3StreamPart;
 };
 //#endregion
+//#region src/language/iterable.d.ts
+/**
+ * Operations for building, draining, and converting async iterables in tests.
+ *
+ * The complement to `Stream`: where `Stream` works with `ReadableStream`s, `Iterable` works with
+ * `AsyncIterable`s (async generators and anything consumed via `for await`). Cross over to the full
+ * `Stream` toolbox with `Iterable.toStream`.
+ */
+declare const Iterable: {
+  /** Builds an `AsyncIterable` that yields each item in order, e.g. to feed code that consumes one. */from: <ITEM>(items: Array<ITEM>) => AsyncIterable<ITEM>; /** Reads an async iterable to completion and returns every item it yielded. */
+  toArray: <ITEM>(iterable: AsyncIterable<ITEM>) => Promise<Array<ITEM>>; /** Converts an async iterable into a `ReadableStream`, e.g. to feed a `ReadableStream`-consuming API. */
+  toStream: <ITEM>(iterable: AsyncIterable<ITEM>) => ReadableStream<ITEM>;
+};
+//#endregion
 //#region src/language/options.d.ts
 /**
  * Determinism helpers to spread into `generateText`/`streamText` so ids and timestamps are stable.
@@ -215,4 +240,4 @@ declare const Options: {
   };
 };
 //#endregion
-export { Content, type GenerateResponse, MockLanguageModel, type MockLanguageModelOptions, type MockResponse, Options, Stream, type StreamDelayOptions, type StreamPartOptions, StreamParts, type StreamResponse };
+export { Content, type GenerateResponse, Iterable, MockLanguageModel, type MockLanguageModelOptions, type MockResponse, Options, Stream, type StreamDelayOptions, type StreamPartOptions, StreamParts, type StreamResponse };

package/dist/language/index.mjs

@@ -1,5 +1,4 @@
-import { t as tokenize } from "../tokenize-C-Zp26iY.mjs";
-import { simulateReadableStream } from "ai";
+import { n as toJSONString, t as tokenize } from "../tokenize-Cy46iVSX.mjs";
 import { vi } from "vitest";
 import { convertArrayToReadableStream, convertReadableStreamToArray } from "@ai-sdk/provider-utils/test";
 
@@ -29,11 +28,6 @@ const toFinishReason = (reason) => typeof reason === "string" ? {
 	raw: reason
 } : reason;
 
-//#endregion
-//#region src/internal/json.ts
-/** Stringifies tool input to the JSON string the provider spec expects, leaving strings untouched. */
-const toJSONString = (input) => typeof input === "string" ? input : JSON.stringify(input);
-
 //#endregion
 //#region src/language/content.ts
 /** Builders for the static content parts a language model returns from `doGenerate`. */
@@ -75,14 +69,108 @@ const Content = {
 
 //#endregion
 //#region src/language/stream.ts
+/** The error a real provider stream rejects with when its request is aborted. */
+const abortError = () => new DOMException("The user aborted a request.", "AbortError");
+/** Waits `ms` (`null` resolves at once), resolving early if the signal aborts so the caller can react immediately. */
+const delay = (ms, signal) => new Promise((resolve) => {
+	if (ms == null) {
+		resolve();
+		return;
+	}
+	const onAbort = () => {
+		clearTimeout(timer);
+		resolve();
+	};
+	const timer = setTimeout(() => {
+		signal?.removeEventListener("abort", onAbort);
+		resolve();
+	}, ms);
+	signal?.addEventListener("abort", onAbort, { once: true });
+});
+/**
+* Builds a delayed `ReadableStream`, a port of the AI SDK's `simulateReadableStream` (delay before each
+* part, `null` to skip) extended with abort handling: when an `abortSignal` fires it errors with an
+* `AbortError` at once (even mid-delay), matching a real provider stream. Inert without a signal.
+*/
+const simulateStream = (chunks, opts = {}) => {
+	const { abortSignal, initialDelayInMs = 0, chunkDelayInMs = 0 } = opts;
+	let index = 0;
+	return new ReadableStream({ async pull(controller) {
+		if (abortSignal?.aborted) {
+			controller.error(abortError());
+			return;
+		}
+		if (index >= chunks.length) {
+			controller.close();
+			return;
+		}
+		await delay(index === 0 ? initialDelayInMs : chunkDelayInMs, abortSignal);
+		if (abortSignal?.aborted) {
+			controller.error(abortError());
+			return;
+		}
+		controller.enqueue(chunks[index]);
+		index += 1;
+	} });
+};
+/**
+* Wraps a `ReadableStream` so it can also be consumed via `for await`, piping through a fresh
+* `TransformStream` so the source stays unlocked. Ported from the AI SDK's `createAsyncIterableStream`.
+*/
+const streamToAsyncIterable = (source) => {
+	const stream = source.pipeThrough(new TransformStream());
+	return Object.assign(stream, { [Symbol.asyncIterator]() {
+		const reader = stream.getReader();
+		let finished = false;
+		const cleanup = async () => {
+			finished = true;
+			try {
+				await reader.cancel();
+			} finally {
+				try {
+					reader.releaseLock();
+				} catch {}
+			}
+		};
+		return {
+			async next() {
+				if (finished) return {
+					done: true,
+					value: void 0
+				};
+				const { done, value } = await reader.read();
+				if (done) {
+					await cleanup();
+					return {
+						done: true,
+						value: void 0
+					};
+				}
+				return {
+					done: false,
+					value
+				};
+			},
+			async return() {
+				await cleanup();
+				return {
+					done: true,
+					value: void 0
+				};
+			},
+			async throw(error) {
+				await cleanup();
+				throw error;
+			}
+		};
+	} });
+};
 /** Operations for building, draining, and inspecting language model streams in tests. */
 const Stream = {
 	from: (parts) => convertArrayToReadableStream(parts),
-	simulate: (chunks, opts = {}) => simulateReadableStream({
-		chunks,
-		...opts
-	}),
+	simulate: (chunks, opts = {}) => simulateStream(chunks, opts),
 	toArray: (stream) => convertReadableStreamToArray(stream),
+	toIterable: (stream) => streamToAsyncIterable(stream),
 	text: (parts) => parts.filter((part) => part.type === "text-delta").map((part) => part.delta).join(""),
 	finishReason: (parts) => parts.find((part) => part.type === "finish")?.finishReason
 };
@@ -206,19 +294,18 @@ const contentToStream = (content, finishReason, usage) => [
 ];
 /** The streamed form of a string is the streamed form of a single text content part. */
 const textToStream = (text) => contentToStream([Content.text(text)]);
-/** Fills a partial generate result with default finish reason, usage, and warnings. */
-const buildGenerateResult = (input) => ({
-	finishReason: defaultFinishReason,
-	usage: defaultUsage,
-	warnings: [],
-	...input
-});
-/** Wraps stream parts into a stream result, with optional simulated delays. */
-const buildStreamResult = (chunks, initialDelayInMs, chunkDelayInMs) => ({ stream: simulateReadableStream({
-	chunks,
-	initialDelayInMs,
-	chunkDelayInMs
-}) });
+/** Fills a partial generate result with default finish reason, usage, and warnings; coerces a string finish reason. */
+const buildGenerateResult = (input) => {
+	const { finishReason, ...rest } = input;
+	return {
+		finishReason: finishReason === void 0 ? defaultFinishReason : toFinishReason(finishReason),
+		usage: defaultUsage,
+		warnings: [],
+		...rest
+	};
+};
+/** Wraps stream parts into a stream result, with optional simulated delays and abort handling. */
+const buildStreamResult = (chunks, opts = {}) => ({ stream: simulateStream(chunks, opts) });
 /** Resolves the `generate` form of an explicit response into a generate result. */
 const resolveGenerateResponse = async (response, options) => {
 	if (typeof response === "string") return buildGenerateResult({ content: [Content.text(response)] });
@@ -228,12 +315,17 @@ const resolveGenerateResponse = async (response, options) => {
 };
 /** Resolves the `stream` form of an explicit response into a stream result. */
 const resolveStreamResponse = async (response, options) => {
-	if (typeof response === "string") return buildStreamResult(textToStream(response));
+	const { abortSignal } = options;
+	if (typeof response === "string") return buildStreamResult(textToStream(response), { abortSignal });
 	if (response instanceof Error) throw response;
-	if (Array.isArray(response)) return buildStreamResult(response);
+	if (Array.isArray(response)) return buildStreamResult(response, { abortSignal });
+	if (response instanceof ReadableStream) return { stream: response };
 	if (typeof response === "function") return response(options);
-	if ("chunks" in response) return buildStreamResult(response.chunks, response.initialDelayInMs, response.chunkDelayInMs);
-	return response;
+	return buildStreamResult(response.chunks, {
+		initialDelayInMs: response.initialDelayInMs,
+		chunkDelayInMs: response.chunkDelayInMs,
+		abortSignal: response.abortSignal ?? abortSignal
+	});
 };
 /** Resolves a top-level response for a `doGenerate` call. */
 const resolveGenerate = async (response, options) => {
@@ -245,10 +337,11 @@ const resolveGenerate = async (response, options) => {
 };
 /** Resolves a top-level response for a `doStream` call. */
 const resolveStream = async (response, options) => {
-	if (typeof response === "string") return buildStreamResult(textToStream(response));
+	const { abortSignal } = options;
+	if (typeof response === "string") return buildStreamResult(textToStream(response), { abortSignal });
 	if (response instanceof Error) throw response;
 	if (isExplicit(response)) return response.stream === void 0 ? notImplemented("doStream") : resolveStreamResponse(response.stream, options);
-	if ("content" in response) return buildStreamResult(contentToStream(response.content, response.finishReason, response.usage));
+	if ("content" in response) return buildStreamResult(contentToStream(response.content, response.finishReason, response.usage), { abortSignal });
 	return notImplemented("doStream");
 };
 /** Picks the response for the current call: a single response repeats, an array advances and clamps. */
@@ -300,7 +393,10 @@ const content = (input) => typeof input === "string" ? [Content.text(input)] : i
 /** Builds a full generate result, filling finish reason, usage, and warnings. */
 const generateResult = (input) => buildGenerateResult(typeof input === "string" ? { content: [Content.text(input)] } : input);
 /** Builds a full stream result; a string is assembled into `stream-start` → text → `finish`. */
-const streamResult = (input, opts = {}) => buildStreamResult(typeof input === "string" ? textToStream(input) : input, opts.initialDelayInMs, opts.chunkDelayInMs);
+const streamResult = (input, opts = {}) => {
+	if (input instanceof ReadableStream) return { stream: input };
+	return buildStreamResult(typeof input === "string" ? textToStream(input) : input, opts);
+};
 /** Builds a usage object, overriding individual token fields on top of the defaults. */
 const usage = (overrides = {}) => ({
 	inputTokens: {
@@ -335,6 +431,50 @@ const MockLanguageModel = {
 	finishReason
 };
 
+//#endregion
+//#region src/language/iterable.ts
+/** Yields each array item in order as an async iterable. */
+async function* fromArray(items) {
+	for (const item of items) yield item;
+}
+/**
+* Operations for building, draining, and converting async iterables in tests.
+*
+* The complement to `Stream`: where `Stream` works with `ReadableStream`s, `Iterable` works with
+* `AsyncIterable`s (async generators and anything consumed via `for await`). Cross over to the full
+* `Stream` toolbox with `Iterable.toStream`.
+*/
+const Iterable = {
+	from: (items) => fromArray(items),
+	toArray: async (iterable) => {
+		const items = [];
+		for await (const item of iterable) items.push(item);
+		return items;
+	},
+	toStream: (iterable) => {
+		const iterator = iterable[Symbol.asyncIterator]();
+		let cancelled = false;
+		return new ReadableStream({
+			async pull(controller) {
+				if (cancelled) return;
+				try {
+					const { value, done } = await iterator.next();
+					if (done) controller.close();
+					else controller.enqueue(value);
+				} catch (error) {
+					controller.error(error);
+				}
+			},
+			async cancel(reason) {
+				cancelled = true;
+				try {
+					await iterator.return?.(reason);
+				} catch {}
+			}
+		});
+	}
+};
+
 //#endregion
 //#region src/language/options.ts
 /** Deterministic id generator so generated message ids are stable across runs. */
@@ -360,4 +500,4 @@ const Options = {
 };
 
 //#endregion
-export { Content, MockLanguageModel, Options, Stream, StreamParts };
+export { Content, Iterable, MockLanguageModel, Options, Stream, StreamParts };

package/dist/{tokenize-C-Zp26iY.mjs → tokenize-Cy46iVSX.mjs}

@@ -1,3 +1,8 @@
+//#region src/internal/json.ts
+/** Stringifies tool input to the JSON string the provider spec expects, leaving strings untouched. */
+const toJSONString = (input) => typeof input === "string" ? input : JSON.stringify(input);
+
+//#endregion
 //#region src/internal/tokenize.ts
 /**
 * Splits text into tokens. Shared by every streamed-text builder so chunking behavior lives
@@ -10,4 +15,4 @@ const tokenize = (text, { length, separator } = {}) => {
 };
 
 //#endregion
-export { tokenize as t };
+export { toJSONString as n, tokenize as t };