feat(language): add singular stream-part builders

Expose the primitives the streamText/streamReasoning/streamToolInput blocks
compose: streamTextStart/Delta/End, streamReasoningStart/Delta/End, and
streamToolInputStart/Delta/End. The block builders now build from them.

Delta builders take the delta string first, then an optional { id } (id
defaults to '1'), mirroring the block builders; start/end take options only
and streamToolInputStart takes the tool name first. Each returns a single
LanguageModelV4StreamPart.

Author: zirkelc

README.md

@@ -684,19 +684,84 @@ Language.custom(args: { kind: `${string}.${string}`; providerMetadata?: SharedV4
 
 ##### Stream parts
 
+#### `.streamTextStart(options?)`
+
+```ts
+Language.streamTextStart(options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamTextStart(): { type: 'text-start', id: '1' } — id defaults to '1'
+```
+
+#### `.streamTextDelta(text, options?)`
+
+```ts
+Language.streamTextDelta(text: string, options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamTextDelta('Hi'): { type: 'text-delta', id: '1', delta: 'Hi' } — the delta string comes first, mirroring streamText
+```
+
+#### `.streamTextEnd(options?)`
+
+```ts
+Language.streamTextEnd(options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamTextEnd(): { type: 'text-end', id: '1' }
+```
+
 #### `.streamText(text, options?)`
 
 ```ts
 Language.streamText(text: string | string[], options?: StreamPartOptions): LanguageModelV4StreamPart[]
 // Language.streamText('Hi'): [{ type: 'text-start', id: '1' }, { type: 'text-delta', id: '1', delta: 'Hi' }, { type: 'text-end', id: '1' }]
 // Language.streamText(['He', 'llo']): an explicit two-delta split (string[] used as the deltas verbatim; length/separator ignored)
+// Composed from streamTextStart / streamTextDelta / streamTextEnd.
+```
+
+#### `.streamReasoningStart(options?)`
+
+```ts
+Language.streamReasoningStart(options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamReasoningStart(): { type: 'reasoning-start', id: '1' }
+```
+
+#### `.streamReasoningDelta(text, options?)`
+
+```ts
+Language.streamReasoningDelta(text: string, options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamReasoningDelta('Hmm'): { type: 'reasoning-delta', id: '1', delta: 'Hmm' }
+```
+
+#### `.streamReasoningEnd(options?)`
+
+```ts
+Language.streamReasoningEnd(options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamReasoningEnd(): { type: 'reasoning-end', id: '1' }
 ```
 
 #### `.streamReasoning(text, options?)`
 
 ```ts
 Language.streamReasoning(text: string | string[], options?: StreamPartOptions): LanguageModelV4StreamPart[]
 // Language.streamReasoning('Hmm'): [{ type: 'reasoning-start', id: '1' }, { type: 'reasoning-delta', id: '1', delta: 'Hmm' }, { type: 'reasoning-end', id: '1' }]
+// Composed from streamReasoningStart / streamReasoningDelta / streamReasoningEnd.
+```
+
+#### `.streamToolInputStart(toolName, options?)`
+
+```ts
+Language.streamToolInputStart(toolName: string, options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamToolInputStart('weather', { id: 't1' }): { type: 'tool-input-start', id: 't1', toolName: 'weather' }
+```
+
+#### `.streamToolInputDelta(text, options?)`
+
+```ts
+Language.streamToolInputDelta(text: string, options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamToolInputDelta('{"city":"Tokyo"}', { id: 't1' }): { type: 'tool-input-delta', id: 't1', delta: '{"city":"Tokyo"}' }
+```
+
+#### `.streamToolInputEnd(options?)`
+
+```ts
+Language.streamToolInputEnd(options?: { id?: string }): LanguageModelV4StreamPart
+// Language.streamToolInputEnd({ id: 't1' }): { type: 'tool-input-end', id: 't1' }
 ```
 
 #### `.streamToolInput(args)`
@@ -705,6 +770,7 @@ Language.streamReasoning(text: string | string[], options?: StreamPartOptions):
 Language.streamToolInput<TOOLS extends ToolSet = never>(args: { id: string; toolName: string; input: unknown; length?: number }): LanguageModelV4StreamPart[]
 // Language.streamToolInput({ id: 't1', toolName: 'weather', input: { city: 'Tokyo' } }): [{ type: 'tool-input-start', id: 't1', toolName: 'weather' }, { type: 'tool-input-delta', id: 't1', delta: '{"city":"Tokyo"}' }, { type: 'tool-input-end', id: 't1' }]
 // Pass <typeof tools> to constrain toolName to a tool key and input to that tool's input type; omit it to stay loose.
+// Composed from streamToolInputStart / streamToolInputDelta / streamToolInputEnd.
 ```
 
 #### `.streamStart(warnings?)`
@@ -1331,7 +1397,7 @@ import type { MockLanguageModelOptions } from 'ai-test-kit/language';
 
 #### `StreamPartOptions`
 
-Options for the streamed-text part builders (`Language.streamText` / `Language.streamReasoning`).
+Options for the streamed-text block builders (`Language.streamText` / `Language.streamReasoning`).
 
 ```ts
 import type { StreamPartOptions } from 'ai-test-kit/language';

src/language/language.test-d.ts

@@ -122,3 +122,25 @@ describe('Language exhaustiveness', () => {
     expectTypeOf<BuiltStreamTag>().toEqualTypeOf<LanguageModelV4StreamPart['type']>();
   });
 });
+
+describe('Language singular stream builders', () => {
+  test('each singular builder should return the wide stream-part type', () => {
+    expectTypeOf(Language.streamTextStart()).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamTextDelta('a')).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamTextEnd()).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamReasoningStart()).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamReasoningDelta('a')).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamReasoningEnd()).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamToolInputStart('w')).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamToolInputDelta('a')).toEqualTypeOf<LanguageModelV4StreamPart>();
+    expectTypeOf(Language.streamToolInputEnd()).toEqualTypeOf<LanguageModelV4StreamPart>();
+  });
+
+  test('the delta builders should take the delta string first, then options', () => {
+    expectTypeOf(Language.streamTextDelta).toBeCallableWith('hi');
+    expectTypeOf(Language.streamTextDelta).toBeCallableWith('hi', { id: '2' });
+    expectTypeOf(Language.streamReasoningDelta).toBeCallableWith('hmm', { id: 'r' });
+    expectTypeOf(Language.streamToolInputStart).toBeCallableWith('weather', { id: 't1' });
+    expectTypeOf(Language.streamToolInputDelta).toBeCallableWith('{', { id: 't1' });
+  });
+});

src/language/language.test.ts

@@ -100,6 +100,49 @@ describe('Language', () => {
       ]);
     });
 
+    test('the singular text builders should build their parts and default the id to "1"', () => {
+      // Assert
+      expect(Language.streamTextStart()).toEqual({ type: 'text-start', id: '1' });
+      expect(Language.streamTextDelta('hi')).toEqual({ type: 'text-delta', id: '1', delta: 'hi' });
+      expect(Language.streamTextEnd()).toEqual({ type: 'text-end', id: '1' });
+    });
+
+    test('the singular reasoning builders should build their parts with a custom id', () => {
+      // Assert
+      expect(Language.streamReasoningStart({ id: 'r' })).toEqual({ type: 'reasoning-start', id: 'r' });
+      expect(Language.streamReasoningDelta('hm', { id: 'r' })).toEqual({
+        type: 'reasoning-delta',
+        id: 'r',
+        delta: 'hm',
+      });
+      expect(Language.streamReasoningEnd({ id: 'r' })).toEqual({ type: 'reasoning-end', id: 'r' });
+    });
+
+    test('the singular tool-input builders should build their parts', () => {
+      // Assert
+      expect(Language.streamToolInputStart('weather', { id: 't1' })).toEqual({
+        type: 'tool-input-start',
+        id: 't1',
+        toolName: 'weather',
+      });
+      expect(Language.streamToolInputDelta('{', { id: 't1' })).toEqual({
+        type: 'tool-input-delta',
+        id: 't1',
+        delta: '{',
+      });
+      expect(Language.streamToolInputEnd({ id: 't1' })).toEqual({ type: 'tool-input-end', id: 't1' });
+    });
+
+    test('streamText() should compose the singular text builders', () => {
+      // Assert
+      expect(Language.streamText('ab', { length: 1 })).toEqual([
+        Language.streamTextStart(),
+        Language.streamTextDelta('a'),
+        Language.streamTextDelta('b'),
+        Language.streamTextEnd(),
+      ]);
+    });
+
     test('streamStart() should default warnings to an empty array', () => {
       // Assert
       expect(Language.streamStart()).toEqual({ type: 'stream-start', warnings: [] });

src/language/language.ts

@@ -21,10 +21,14 @@ import { toJSONString } from '../internal/json.js';
 import { tokenize } from '../internal/tokenize.js';
 import { simulateStream, type StreamDelayOptions } from '../streams.js';
 
-/** Options for the streamed-text builders: a stable part `id` plus a tokenization strategy. */
-export type StreamPartOptions = {
-  /** Stable id shared by the start/delta/end parts. */
+/** Options for a singular stream-part builder: the stable part `id`, defaulting to `'1'`. */
+type StreamPartIdOptions = {
+  /** Stable id shared by the start/delta/end parts of one block. */
   id?: string;
+};
+
+/** Options for the streamed-text block builders: a stable part `id` plus a tokenization strategy. */
+export type StreamPartOptions = StreamPartIdOptions & {
   /** Split the text into fixed-size slices of at most this many characters. */
   length?: number;
   /** Split the text on this delimiter, re-appending it to each token. */
@@ -179,6 +183,22 @@ const reasoningFile = (args: { mediaType: string; data: string | Uint8Array }):
 const toDeltas = (text: string | Array<string>, length?: number, separator?: string): Array<string> =>
   Array.isArray(text) ? text : tokenize(text, { length, separator });
 
+/** A `text-start` part opening a streamed text block. */
+const streamTextStart = ({ id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'text-start',
+  id,
+});
+
+/** A `text-delta` part carrying a slice of streamed text. */
+const streamTextDelta = (text: string, { id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'text-delta',
+  id,
+  delta: text,
+});
+
+/** A `text-end` part closing a streamed text block. */
+const streamTextEnd = ({ id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({ type: 'text-end', id });
+
 /**
  * A streamed text block: `text-start` → `text-delta`* → `text-end`. A `string` is split per
  * `length`/`separator`; an `Array<string>` is used as the deltas verbatim.
@@ -187,35 +207,72 @@ const streamText = (
   text: string | Array<string>,
   { id = '1', length, separator }: StreamPartOptions = {},
 ): Array<LanguageModelV4StreamPart> => [
-  { type: 'text-start', id },
-  ...toDeltas(text, length, separator).map((delta) => ({ type: 'text-delta' as const, id, delta })),
-  { type: 'text-end', id },
+  streamTextStart({ id }),
+  ...toDeltas(text, length, separator).map((delta) => streamTextDelta(delta, { id })),
+  streamTextEnd({ id }),
 ];
 
+/** A `reasoning-start` part opening a streamed reasoning block. */
+const streamReasoningStart = ({ id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'reasoning-start',
+  id,
+});
+
+/** A `reasoning-delta` part carrying a slice of streamed reasoning. */
+const streamReasoningDelta = (text: string, { id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'reasoning-delta',
+  id,
+  delta: text,
+});
+
+/** A `reasoning-end` part closing a streamed reasoning block. */
+const streamReasoningEnd = ({ id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'reasoning-end',
+  id,
+});
+
 /** A streamed reasoning block: `reasoning-start` → `reasoning-delta`* → `reasoning-end`. */
 const streamReasoning = (
   text: string | Array<string>,
   { id = '1', length, separator }: StreamPartOptions = {},
 ): Array<LanguageModelV4StreamPart> => [
-  { type: 'reasoning-start', id },
-  ...toDeltas(text, length, separator).map((delta) => ({ type: 'reasoning-delta' as const, id, delta })),
-  { type: 'reasoning-end', id },
+  streamReasoningStart({ id }),
+  ...toDeltas(text, length, separator).map((delta) => streamReasoningDelta(delta, { id })),
+  streamReasoningEnd({ id }),
 ];
 
+/** A `tool-input-start` part opening a streamed tool input. */
+const streamToolInputStart = (toolName: string, { id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'tool-input-start',
+  id,
+  toolName,
+});
+
+/** A `tool-input-delta` part carrying a slice of the streamed tool input. */
+const streamToolInputDelta = (text: string, { id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'tool-input-delta',
+  id,
+  delta: text,
+});
+
+/** A `tool-input-end` part closing a streamed tool input. */
+const streamToolInputEnd = ({ id = '1' }: StreamPartIdOptions = {}): LanguageModelV4StreamPart => ({
+  type: 'tool-input-end',
+  id,
+});
+
 /**
  * A streamed tool input: `tool-input-start` → `tool-input-delta`* → `tool-input-end`.
  * Pass a tool-set as `TOOLS` to constrain `toolName` and `input`.
  */
 const streamToolInput = <TOOLS extends ToolSet = never>(
   args: StreamToolInputArgs<TOOLS>,
 ): Array<LanguageModelV4StreamPart> => [
-  { type: 'tool-input-start', id: args.id, toolName: args.toolName },
-  ...tokenize(toJSONString(args.input), { length: args.length }).map((delta) => ({
-    type: 'tool-input-delta' as const,
-    id: args.id,
-    delta,
-  })),
-  { type: 'tool-input-end', id: args.id },
+  streamToolInputStart(args.toolName, { id: args.id }),
+  ...tokenize(toJSONString(args.input), { length: args.length }).map((delta) =>
+    streamToolInputDelta(delta, { id: args.id }),
+  ),
+  streamToolInputEnd({ id: args.id }),
 ];
 
 /** The opening `stream-start` part carrying call warnings. */
@@ -321,8 +378,17 @@ export const Language = {
   source,
   custom,
   reasoningFile,
+  streamTextStart,
+  streamTextDelta,
+  streamTextEnd,
   streamText,
+  streamReasoningStart,
+  streamReasoningDelta,
+  streamReasoningEnd,
   streamReasoning,
+  streamToolInputStart,
+  streamToolInputDelta,
+  streamToolInputEnd,
   streamToolInput,
   streamStart,
   streamFinish,