streamfold 0.1.4 → 0.1.6

package/src/internal/integration.js

@@ -1,34 +1,123 @@
-export const createIntegration = (pool, accept, finishActive) => {
+import {
+  annotateError,
+  isStructuredStreamError,
+  streamError,
+} from "./errors.js";
+import { emitDiagnostic } from "./diagnostics.js";
+
+export const createIntegration = (
+  pool,
+  accept,
+  finishActive,
+  adapter,
+  options = {},
+) => {
   const completed = [];
   let failure;
+  let batch;
+  let eventType;
+  let receivedEvents = false;
+  let matched = false;
+  let reportedNoMatch = false;
+
+  const diagnose = (diagnostic) =>
+    emitDiagnostic(options, { adapter, eventType, ...diagnostic });
+  const unmatched = (message, id) =>
+    diagnose({
+      code: "UNMATCHED_TOOL_EVENT",
+      message,
+      id,
+    });
+  const record = (type, result) => {
+    matched = true;
+    if (batch !== undefined) batch.push({ type, ...result });
+    return result;
+  };
+  const missingId = (id) => {
+    if (id !== undefined && id !== null) return false;
+    unmatched("Tool event is missing its call id");
+    return true;
+  };
 
   const complete = (id) => {
-    if (!pool.has(id)) return undefined;
+    if (missingId(id)) return undefined;
+    if (!pool.has(id)) {
+      if (
+        options.onDiagnostic &&
+        !completed.some((result) => result.id === id)
+      ) {
+        unmatched("Tool completion has no matching active call", id);
+      }
+      return undefined;
+    }
     const result = pool.finish(id);
     completed.push(result);
-    return result;
+    return record("complete", result);
+  };
+  const operations = {
+    start: (id, initialChunk) =>
+      missingId(id) ? undefined : record("start", pool.start(id, initialChunk)),
+    push: (id, delta) =>
+      missingId(id) ? undefined : record("update", pool.push(id, delta)),
+    has: (id) => pool.has(id),
+    complete,
+    unmatched,
   };
 
   const fail = (error) => {
-    failure = error instanceof Error ? error : new Error("Integration failed");
+    const original =
+      error instanceof Error ? error : new Error("Integration failed");
+    failure = isStructuredStreamError(original)
+      ? annotateError(original, { adapter, eventType })
+      : streamError(original, "INTEGRATION_ERROR", { adapter, eventType });
     for (const id of pool.activeIds) pool.abort(id);
+    diagnose({
+      code: "STREAM_ERROR",
+      message: failure.message,
+      error: failure,
+      id: failure.id,
+    });
     return failure;
   };
 
+  const push = (event, collect) => {
+    if (failure !== undefined) throw failure;
+    receivedEvents = true;
+    batch = collect ? [] : undefined;
+    try {
+      const type = event?.type ?? event?.event_type;
+      eventType =
+        typeof type === "string"
+          ? type
+          : event?.tool_call_chunks
+            ? "tool_call_chunks"
+            : undefined;
+      const update = accept(event, operations);
+      return collect ? batch : update;
+    } catch (error) {
+      throw fail(error);
+    } finally {
+      batch = undefined;
+      eventType = undefined;
+    }
+  };
+
   return {
-    push(event) {
-      if (failure !== undefined) throw failure;
-      try {
-        return accept(event, complete);
-      } catch (error) {
-        throw fail(error);
-      }
-    },
+    push: (event) => push(event, false),
+    pushAll: (event) => push(event, true),
     finish() {
       if (failure !== undefined) throw failure;
       try {
         finishActive?.(complete);
         for (const id of pool.activeIds) complete(id);
+        if (receivedEvents && !matched && !reportedNoMatch) {
+          reportedNoMatch = true;
+          diagnose({
+            code: "NO_TOOL_EVENTS",
+            message:
+              "No tool argument events matched this adapter; text-only streams are valid, otherwise check the event format",
+          });
+        }
         return [...completed];
       } catch (error) {
         throw fail(error);
@@ -37,7 +126,8 @@ export const createIntegration = (pool, accept, finishActive) => {
   };
 };
 
-export const append = (pool, id, delta) => {
-  if (!pool.has(id)) pool.start(id);
-  return pool.push(id, delta);
+export const append = (operations, id, delta) => {
+  if (!operations.has(id) && operations.start(id) === undefined)
+    return undefined;
+  return operations.push(id, delta);
 };

package/src/internal/snapshots.js

@@ -0,0 +1,58 @@
+const setOwn = (target, key, value) => {
+  Object.defineProperty(target, key, {
+    value,
+    enumerable: true,
+    configurable: true,
+    writable: true,
+  });
+};
+
+export const applyImmutableChanges = (previous, changes) => {
+  const owned = new Set();
+  const copy = (value) => {
+    if (owned.has(value)) return value;
+    const result = Array.isArray(value) ? value.slice() : { ...value };
+    owned.add(result);
+    return result;
+  };
+
+  let next = previous;
+  for (const change of changes) {
+    if (change.op === "complete") continue;
+    const replacement = (current) => {
+      if (change.op === "append") return current + change.value;
+      return change.value !== null && typeof change.value === "object"
+        ? copy(change.value)
+        : change.value;
+    };
+    if (change.path.length === 0) {
+      next = replacement(next);
+      continue;
+    }
+
+    // Copy each changed container once per batch, even for many array appends.
+    next = copy(next);
+    let target = next;
+    for (const key of change.path.slice(0, -1)) {
+      const child = copy(Object.hasOwn(target, key) ? target[key] : undefined);
+      setOwn(target, key, child);
+      target = child;
+    }
+    const key = change.path.at(-1);
+    setOwn(
+      target,
+      key,
+      replacement(Object.hasOwn(target, key) ? target[key] : undefined),
+    );
+  }
+  for (const value of owned) Object.freeze(value);
+  return next;
+};
+
+export const freezeJson = (value) => {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) freezeJson(child);
+    Object.freeze(value);
+  }
+  return value;
+};

package/src/internal/wasm-runtime.js

@@ -1,4 +1,5 @@
 import { wasmBinaryBase64 } from "./wasm-binary.js";
+import { streamError } from "./errors.js";
 
 const DEPTH_MASK = 0x00ff_ffff;
 const COMPLETE_FLAG = 1 << 24;
@@ -36,7 +37,7 @@ const getExports = () => {
   return exports;
 };
 
-const parserError = ({ wasm, handle, maxBytes, maxDepth }, code) => {
+const describeParserError = ({ wasm, handle, maxBytes, maxDepth }, code) => {
   const offset = wasm.streamfold_parser_error_offset(handle) >>> 0;
   const byte = wasm.streamfold_parser_error_byte(handle);
   if (code === 1) {
@@ -61,6 +62,28 @@ const parserError = ({ wasm, handle, maxBytes, maxDepth }, code) => {
   return new SyntaxError(`Rust parser failed with error code ${code}`);
 };
 
+const parserErrorCodes = [
+  "PARSER_ERROR",
+  "UNEXPECTED_TOKEN",
+  "MISMATCHED_CLOSING",
+  "TRAILING_DATA",
+  "EMPTY_INPUT",
+  "INCOMPLETE_JSON",
+  "INVALID_JSON",
+  "MAX_BYTES_EXCEEDED",
+  "MAX_DEPTH_EXCEEDED",
+];
+
+const parserError = (parser, code) =>
+  streamError(
+    describeParserError(parser, code),
+    parserErrorCodes[code] ?? "PARSER_ERROR",
+    {
+      byteOffset:
+        parser.wasm.streamfold_parser_error_offset(parser.handle) >>> 0,
+    },
+  );
+
 const readState = (parser, encoded) => {
   const { wasm, handle } = parser;
   const error = encoded >>> ERROR_SHIFT;
@@ -190,6 +213,12 @@ const pushChunk = (parser, chunk) => {
 };
 
 export const pushWasmParser = (parser, chunk) => {
+  if (typeof chunk !== "string") {
+    throw streamError(
+      new TypeError("A structured stream chunk must be a string"),
+      "INVALID_CHUNK",
+    );
+  }
   let input = parser.pendingHighSurrogate + chunk;
   parser.pendingHighSurrogate = "";
 
@@ -217,10 +246,7 @@ export const finishWasmParser = (parser) => {
 };
 
 export const readWasmParser = (parser) =>
-  readState(
-    parser,
-    parser.wasm.streamfold_parser_state(parser.handle),
-  );
+  readState(parser, parser.wasm.streamfold_parser_state(parser.handle));
 
 export const freeWasmParser = ({ wasm, handle }) => {
   wasm.streamfold_parser_free(handle);

package/src/langchain.d.ts

@@ -1,6 +1,7 @@
 import type {
-  EventStructuredStream,
-  StructuredStreamIntegration,
+  BatchEventStructuredStream,
+  BatchStructuredStreamIntegration,
+  StructuredStreamIntegrationOptions,
   StructuredStreamPool,
 } from "./index.js";
 
@@ -16,11 +17,12 @@ export interface LangChainToolCallMessage {
   readonly tool_call_chunks?: readonly LangChainToolCallChunk[];
 }
 
-export const langchain: StructuredStreamIntegration<
+export const langchain: BatchStructuredStreamIntegration<
   LangChainToolCallMessage,
   string
 >;
 
 export function createStructuredStream(
   pool?: StructuredStreamPool<string>,
-): EventStructuredStream<LangChainToolCallMessage, string>;
+  options?: StructuredStreamIntegrationOptions,
+): BatchEventStructuredStream<LangChainToolCallMessage, string>;

package/src/langchain.js

@@ -1,22 +1,24 @@
 import { createStructuredStreamPool } from "./index.js";
 import { createIntegration } from "./internal/integration.js";
 
-export const langchain = (pool = createStructuredStreamPool()) => {
+export const langchain = (pool = createStructuredStreamPool(), options) => {
   const idsByIndex = new Map();
 
   return createIntegration(
     pool,
-    (message) => {
+    (message, calls) => {
       let update;
       for (const chunk of message.tool_call_chunks ?? []) {
         let id = idsByIndex.get(chunk.index);
         if (id === undefined && chunk.id) {
           id = chunk.id;
           idsByIndex.set(chunk.index, id);
-          update = pool.start(id);
+          update = calls.start(id);
         }
         if (id !== undefined && chunk.args) {
-          update = pool.push(id, chunk.args);
+          update = calls.push(id, chunk.args);
+        } else if (id === undefined && chunk.args) {
+          calls.unmatched("Arguments delta has no matching tool call index");
         }
       }
       return update;
@@ -25,6 +27,8 @@ export const langchain = (pool = createStructuredStreamPool()) => {
       for (const id of idsByIndex.values()) complete(id);
       idsByIndex.clear();
     },
+    "langchain",
+    options,
   );
 };
 

package/src/openai.d.ts

@@ -1,6 +1,7 @@
 import type {
-  EventStructuredStream,
-  StructuredStreamIntegration,
+  BatchEventStructuredStream,
+  BatchStructuredStreamIntegration,
+  StructuredStreamIntegrationOptions,
   StructuredStreamPool,
 } from "./index.js";
 
@@ -27,11 +28,12 @@ export type OpenAiResponsesToolEvent =
       readonly [key: string]: unknown;
     };
 
-export const openAI: StructuredStreamIntegration<
+export const openAI: BatchStructuredStreamIntegration<
   OpenAiResponsesToolEvent,
   string
 >;
 
 export function createStructuredStream(
   pool?: StructuredStreamPool<string>,
-): EventStructuredStream<OpenAiResponsesToolEvent, string>;
+  options?: StructuredStreamIntegrationOptions,
+): BatchEventStructuredStream<OpenAiResponsesToolEvent, string>;

package/src/openai.js

@@ -1,20 +1,27 @@
 import { createStructuredStreamPool } from "./index.js";
 import { append, createIntegration } from "./internal/integration.js";
 
-export const openAI = (pool = createStructuredStreamPool()) =>
-  createIntegration(pool, (event, complete) => {
-    if (event.type === "response.output_item.added") {
-      if (event.item.type !== "function_call") return undefined;
-      return pool.start(event.item.id);
-    }
-    if (event.type === "response.function_call_arguments.delta") {
-      return append(pool, event.item_id, event.delta);
-    }
-    if (event.type === "response.function_call_arguments.done") {
-      if (!pool.has(event.item_id)) pool.start(event.item_id, event.arguments);
-      return complete(event.item_id);
-    }
-    return undefined;
-  });
+export const openAI = (pool = createStructuredStreamPool(), options) =>
+  createIntegration(
+    pool,
+    (event, calls) => {
+      if (event.type === "response.output_item.added") {
+        if (event.item.type !== "function_call") return undefined;
+        return calls.start(event.item.id);
+      }
+      if (event.type === "response.function_call_arguments.delta") {
+        return append(calls, event.item_id, event.delta);
+      }
+      if (event.type === "response.function_call_arguments.done") {
+        if (!calls.has(event.item_id))
+          calls.start(event.item_id, event.arguments);
+        return calls.complete(event.item_id);
+      }
+      return undefined;
+    },
+    undefined,
+    "openai",
+    options,
+  );
 
 export { openAI as createStructuredStream };

package/src/read-structured.js

@@ -0,0 +1,74 @@
+import { createStructuredStreamPool } from "./index.js";
+import { streamError } from "./internal/errors.js";
+import { abortableSource } from "./internal/abortable-source.js";
+
+export async function* readStructured(
+  events,
+  { adapter, integration, limits, onDiagnostic, signal },
+) {
+  if (
+    (adapter === undefined) === (integration === undefined) ||
+    (adapter !== undefined && typeof adapter !== "function") ||
+    (integration !== undefined && typeof integration !== "function")
+  ) {
+    throw streamError(
+      new TypeError("Choose exactly one adapter or integration factory"),
+      "INVALID_OPTIONS",
+    );
+  }
+  let pool;
+  let stream;
+  let source;
+  let failed = false;
+  const dispose = () => {
+    if (pool === undefined) stream?.dispose();
+    else for (const id of pool.activeIds) pool.abort(id);
+  };
+  try {
+    signal?.throwIfAborted();
+    if (integration !== undefined) {
+      pool = createStructuredStreamPool(limits);
+      stream = integration(pool, { onDiagnostic });
+    } else {
+      stream = adapter(
+        onDiagnostic === undefined ? limits : { ...limits, onDiagnostic },
+      );
+    }
+    signal?.throwIfAborted();
+    source = signal === undefined ? undefined : abortableSource(events, signal, dispose);
+    for await (const event of source ?? events) {
+      signal?.throwIfAborted();
+      for (const update of stream.pushAll(event)) {
+        signal?.throwIfAborted();
+        yield update;
+      }
+    }
+    signal?.throwIfAborted();
+    if (pool === undefined) {
+      for (const completed of stream.finish()) {
+        signal?.throwIfAborted();
+        yield completed;
+      }
+    } else {
+      // SDK finish() appends pending calls to its legacy completion history.
+      const pending = pool.size;
+      const completed = stream.finish();
+      if (pending > 0) {
+        for (const result of completed.slice(-pending)) {
+          signal?.throwIfAborted();
+          yield { type: "complete", ...result };
+        }
+      }
+    }
+  } catch (error) {
+    failed = true;
+    throw error;
+  } finally {
+    try { dispose(); }
+    catch (error) { if (!failed) throw error; }
+    finally {
+      try { await source?.dispose(); }
+      catch (error) { if (!failed) throw error; }
+    }
+  }
+}

package/src/testing.d.ts

@@ -0,0 +1,13 @@
+import type { StructuredStreamAdapter, StructuredStreamOperation } from "./index.js";
+
+export interface AdapterContractTest {
+  readonly name: string;
+  run(): Promise<void>;
+}
+
+/** Node-only helpers for node:test, Vitest, and other Node-based test runners. */
+export function adapterContractTests<Event>(options: {
+  readonly adapter: StructuredStreamAdapter<Event, string>;
+  /** Encode every operation in order; may split or batch your decoded events. */
+  readonly encode: (operations: readonly StructuredStreamOperation<string>[]) => Iterable<Event>;
+}): readonly AdapterContractTest[];

package/src/testing.js

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { readStructured } from "./read-structured.js";
+
+/** Contract tests for defineAdapter-compatible factories, not legacy SDK adapters. */
+export function adapterContractTests({ adapter, encode }) {
+  const start = (id) => ({ type: "start", id });
+  const delta = (id, text) => ({ type: "delta", id, text });
+  const end = (id) => ({ type: "end", id });
+  const push = (session, operations) => {
+    const updates = [];
+    for (const event of encode(operations)) updates.push(...session.pushAll(event));
+    return updates;
+  };
+  const check = (name, run) => ({
+    name,
+    async run() {
+      const session = adapter({ snapshots: "immutable" });
+      try { await run(session); }
+      finally { session.dispose(); }
+    },
+  });
+  return [
+    check("interleaved calls preserve lifecycle order and values", (session) => {
+      const updates = push(session, [
+        start("a"), start("b"), delta("a", '{"city":"San'),
+        delta("b", "42"), delta("a", ' Francisco"}'), end("b"), end("a"),
+      ]);
+      assert.deepEqual(updates.map(({ type, id }) => [type, id]), [
+        ["start", "a"], ["start", "b"], ["update", "a"], ["update", "b"],
+        ["update", "a"], ["complete", "b"], ["complete", "a"],
+      ]);
+      assert.deepEqual(updates[2].partialValue, { city: "San" });
+      assert.equal(updates[5].value, 42);
+      assert.deepEqual(updates[6].value, { city: "San Francisco" });
+      assert.deepEqual(session.finish(), []);
+    }),
+    check("immutable snapshots retain nested values across later events", (session) => {
+      const first = push(session, [start("a"), delta("a", '{"items":[{"name":"A')]).at(-1);
+      push(session, [delta("a", 'B"}]}'), end("a")]);
+      assert.deepEqual(first.partialValue, { items: [{ name: "A" }] });
+      assert.ok(Object.isFrozen(first.partialValue));
+      assert.ok(Object.isFrozen(first.partialValue.items[0]));
+    }),
+    check("EOF finishes pending calls exactly once", (session) => {
+      push(session, [start("a"), delta("a", "null"), start("b"), delta("b", "[]"), end("b")]);
+      const completed = session.finish();
+      assert.equal(completed.length, 1);
+      assert.equal(completed[0].id, "a");
+      assert.equal(completed[0].type, "complete");
+      assert.equal(completed[0].value, null);
+      assert.deepEqual(session.finish(), []);
+    }),
+    check("abort abandons incomplete JSON and allows ID reuse", (session) => {
+      const updates = push(session, [
+        start("a"), delta("a", "{"), { type: "abort", id: "a" },
+        start("a"), delta("a", "true"), end("a"),
+        start("a"), delta("a", "false"), end("a"),
+      ]);
+      assert.deepEqual(updates.filter(({ type }) => type === "complete").map(({ value }) => value), [true, false]);
+      assert.deepEqual(session.finish(), []);
+    }),
+    check("malformed input fails terminally instead of emitting a completion", (session) => {
+      assert.throws(() => push(session, [start("a"), delta("a", "{]")]), SyntaxError);
+      assert.throws(() => session.finish());
+      assert.throws(() => push(session, [start("b")]));
+    }),
+    check("unknown calls and duplicate starts are rejected", (session) => {
+      assert.throws(() => push(session, [delta("missing", "{}")]), { code: "UNKNOWN_STREAM" });
+      const other = adapter();
+      try {
+        assert.throws(() => push(other, [start("a"), start("a")]), { code: "DUPLICATE_STREAM" });
+      } finally { other.dispose(); }
+    }),
+    check("sessions are isolated and dispose is idempotent", (session) => {
+      push(session, [start("a"), delta("a", "{")]);
+      const other = adapter();
+      try {
+        const updates = push(other, [start("a"), delta("a", "42"), end("a")]);
+        assert.equal(updates.at(-1).value, 42);
+      } finally { other.dispose(); }
+      session.dispose();
+      session.dispose();
+      assert.throws(() => push(session, [start("b")]), { code: "STREAM_DISPOSED" });
+    }),
+    check("configured parser limits are forwarded", () => {
+      const limited = adapter({ maxActiveStreams: 1, maxBytes: 2 });
+      try {
+        assert.throws(() => push(limited, [start("a"), start("b")]), { code: "MAX_ACTIVE_STREAMS_EXCEEDED" });
+      } finally { limited.dispose(); }
+      const bytes = adapter({ maxBytes: 2 });
+      try {
+        assert.throws(() => push(bytes, [start("a"), delta("a", "true")]), { code: "MAX_BYTES_EXCEEDED" });
+      } finally { bytes.dispose(); }
+    }),
+    {
+      name: "managed early exit closes the source and disposes its session",
+      async run() {
+        let closed = false;
+        let disposed = false;
+        function* source() {
+          try { yield* encode([start("a"), delta("a", "{")]); }
+          finally { closed = true; }
+        }
+        const factory = (options) => {
+          const session = adapter(options);
+          return {
+            pushAll: (event) => session.pushAll(event),
+            finish: () => session.finish(),
+            dispose() { disposed = true; session.dispose(); },
+          };
+        };
+        for await (const update of readStructured(source(), { adapter: factory })) {
+          assert.equal(update.type, "start");
+          break;
+        }
+        assert.equal(closed, true);
+        assert.equal(disposed, true);
+      },
+    },
+  ];
+}

package/src/vercel-ai.d.ts

@@ -1,6 +1,7 @@
 import type {
-  EventStructuredStream,
-  StructuredStreamIntegration,
+  BatchEventStructuredStream,
+  BatchStructuredStreamIntegration,
+  StructuredStreamIntegrationOptions,
   StructuredStreamPool,
 } from "./index.js";
 
@@ -42,11 +43,12 @@ export type VercelAiToolInputEvent =
       readonly [key: string]: unknown;
     };
 
-export const vercelAI: StructuredStreamIntegration<
+export const vercelAI: BatchStructuredStreamIntegration<
   VercelAiToolInputEvent,
   string
 >;
 
 export function createStructuredStream(
   pool?: StructuredStreamPool<string>,
-): EventStructuredStream<VercelAiToolInputEvent, string>;
+  options?: StructuredStreamIntegrationOptions,
+): BatchEventStructuredStream<VercelAiToolInputEvent, string>;