streamfold 0.1.5 → 0.1.7

package/README.md

@@ -34,6 +34,11 @@ for frozen snapshots that preserve earlier values and share unchanged branches.
 Pools and custom adapter factories accept the same option; managed readers
 forward it through `limits`.
 
+Chunks must contain well-formed Unicode. Valid surrogate pairs may span chunks;
+raw unpaired UTF-16 code units fail with `INVALID_CHUNK` instead of being silently
+replaced during UTF-8 encoding. Use JSON Unicode escapes for unpaired code units
+(as produced by `JSON.stringify`).
+
 Use `streamfold/assistant-ui`, `streamfold/vercel-ai`, `streamfold/openai`,
 `streamfold/anthropic`, `streamfold/gemini`, `streamfold/langchain`, or
 `streamfold/ag-ui` for decoded SDK events. Integrations use structural event
@@ -50,6 +55,10 @@ same batch adapter, finalizes remaining calls at the end of the source, and
 disposes on completion, failure, or early exit. `limits` is optional.
 For a built-in SDK factory, use `{ integration: assistantUI, limits }` instead.
 Both paths yield the same lifecycle updates without replaying completions.
+Readable streams are consumed through `getReader()` even without an abort
+signal or native async-iterator support.
+Upstream failures close the iterator or reader while preserving the original
+error, even when no abort signal is supplied.
 
 Every built-in adapter supports `pushAll(event)`, returning all ordered
 `start`, `update`, and `complete` updates, including multiple calls in one event.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamfold",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Protocol-neutral incremental state for structured AI streams",
   "type": "module",
   "license": "MIT",
@@ -12,6 +12,10 @@
     "!src/**/*.test.js"
   ],
   "exports": {
+    "./testing": {
+      "types": "./src/testing.d.ts",
+      "default": "./src/testing.js"
+    },
     ".": {
       "types": "./src/index.d.ts",
       "default": "./src/index.js"

package/src/index.d.ts

@@ -175,6 +175,8 @@ export function defineAdapter<Event, Id = string>(
 
 export interface ReadStructuredOptions<Event, Id = string>
   extends StructuredStreamIntegrationOptions {
+  /** Stop waiting and release parsers; pass the same signal to the transport. */
+  readonly signal?: AbortSignal;
   readonly adapter: StructuredStreamAdapter<Event, Id>;
   readonly integration?: never;
   readonly limits?: StructuredStreamPoolOptions;
@@ -182,6 +184,8 @@ export interface ReadStructuredOptions<Event, Id = string>
 
 export interface ReadStructuredIntegrationOptions<Event, Id = string>
   extends StructuredStreamIntegrationOptions {
+  /** Stop waiting and release parsers; pass the same signal to the transport. */
+  readonly signal?: AbortSignal;
   readonly integration: BatchStructuredStreamIntegration<Event, Id>;
   readonly adapter?: never;
   readonly limits?: StructuredStreamPoolOptions;
@@ -189,7 +193,7 @@ export interface ReadStructuredIntegrationOptions<Event, Id = string>
 
 /** Consume decoded events, finalizing at EOF and disposing on every exit. */
 export function readStructured<Event, Id = string>(
-  events: AsyncIterable<Event> | Iterable<Event>,
+  events: AsyncIterable<Event> | Iterable<Event> | ReadableStream<Event>,
   options:
     | ReadStructuredOptions<Event, Id>
     | ReadStructuredIntegrationOptions<Event, Id>,

package/src/internal/abortable-source.js

@@ -0,0 +1,82 @@
+export function abortableSource(events, signal, onAbort) {
+  const reader = typeof events?.getReader === "function" ? events.getReader() : undefined;
+  const asyncFactory = reader === undefined ? events[Symbol.asyncIterator] : undefined;
+  const synchronous = reader === undefined && asyncFactory == null;
+  const iterator = reader === undefined
+    ? (asyncFactory ?? events[Symbol.iterator]).call(events)
+    : undefined;
+  let closed = false;
+  // Each read removes its listener; one shared pending promise would retain
+  // a Promise.race reaction for every event until the session ends.
+  const waitFor = (promise) => signal === undefined ? Promise.resolve(promise) : new Promise((resolve, reject) => {
+    let listening = true;
+    const detach = () => {
+      if (!listening) return;
+      listening = false;
+      signal.removeEventListener("abort", stop);
+    };
+    const stop = () => { detach(); reject(signal.reason); };
+    signal.addEventListener("abort", stop, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        detach();
+        if (signal.aborted) reject(signal.reason);
+        else resolve(value);
+      },
+      (error) => { detach(); reject(signal.aborted ? signal.reason : error); },
+    );
+    if (signal.aborted) stop();
+  });
+
+  const close = (reason) => {
+    if (closed) return Promise.resolve();
+    closed = true;
+    return Promise.resolve().then(async () => {
+      if (reader !== undefined) {
+        try { return reader.cancel(reason); }
+        finally { reader.releaseLock(); }
+      } else {
+        await iterator.return?.();
+      }
+    });
+  };
+  const abort = () => {
+    try { onAbort(); } catch { /* Cancellation preserves the signal's reason. */ }
+    close(signal.reason).catch(() => {});
+  };
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
+
+  return {
+    [Symbol.asyncIterator]() { return this; },
+    async next() {
+      signal?.throwIfAborted();
+      const result = await waitFor(
+        Promise.resolve().then(async () => {
+          signal?.throwIfAborted();
+          const next = reader !== undefined ? await reader.read() : await iterator.next();
+          if (next === null || typeof next !== "object") {
+            throw new TypeError("Iterator result must be an object");
+          }
+          return synchronous ? { done: next.done, value: await next.value } : next;
+        }),
+      );
+      signal?.throwIfAborted();
+      if (result.done) {
+        closed = true;
+        reader?.releaseLock();
+      }
+      return result;
+    },
+    async return() {
+      const cleanup = close();
+      cleanup.catch(() => {});
+      if (!signal?.aborted) await waitFor(cleanup);
+      return { done: true, value: undefined };
+    },
+    async dispose() {
+      try { await this.return(); }
+      finally { signal?.removeEventListener("abort", abort); }
+    },
+  };
+}

package/src/internal/wasm-runtime.js

@@ -196,6 +196,16 @@ export const createWasmParser = ({ maxBytes, maxDepth }) => {
 };
 
 const pushChunk = (parser, chunk) => {
+  // In Unicode mode this range matches lone surrogate code units, not valid
+  // pairs. TextEncoder would silently replace them with U+FFFD, while the
+  // pool's final JSON.parse would preserve them, producing different values.
+  // A trailing high surrogate is buffered by pushWasmParser before this check.
+  if (/[\uD800-\uDFFF]/u.test(chunk)) {
+    throw streamError(
+      new TypeError("Unpaired UTF-16 surrogate; use a JSON Unicode escape"),
+      "INVALID_CHUNK",
+    );
+  }
   const { wasm, handle } = parser;
   const capacity = chunk.length * 3;
   const pointer = wasm.streamfold_parser_input(handle, capacity);

package/src/read-structured.js

@@ -1,9 +1,10 @@
 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 },
+  { adapter, integration, limits, onDiagnostic, signal },
 ) {
   if (
     (adapter === undefined) === (integration === undefined) ||
@@ -17,7 +18,14 @@ export async function* readStructured(
   }
   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 });
@@ -26,23 +34,43 @@ export async function* readStructured(
         onDiagnostic === undefined ? limits : { ...limits, onDiagnostic },
       );
     }
-    for await (const event of events) {
-      for (const update of stream.pushAll(event)) yield update;
+    signal?.throwIfAborted();
+    // Own the source even without cancellation so a rejected next()
+    // still triggers upstream cleanup.
+    source = abortableSource(events, signal, dispose);
+    for await (const event of source) {
+      signal?.throwIfAborted();
+      for (const update of stream.pushAll(event)) {
+        signal?.throwIfAborted();
+        yield update;
+      }
     }
+    signal?.throwIfAborted();
     if (pool === undefined) {
-      for (const completed of stream.finish()) yield completed;
+      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 {
-    if (pool === undefined) stream?.dispose();
-    else for (const id of pool.activeIds) pool.abort(id);
+    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);
+      },
+    },
+  ];
+}