streamfold 0.1.6 → 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.6",
+  "version": "0.1.7",
   "description": "Protocol-neutral incremental state for structured AI streams",
   "type": "module",
   "license": "MIT",

package/src/index.d.ts

@@ -193,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

@@ -8,7 +8,7 @@ export function abortableSource(events, signal, onAbort) {
   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) => new Promise((resolve, reject) => {
+  const waitFor = (promise) => signal === undefined ? Promise.resolve(promise) : new Promise((resolve, reject) => {
     let listening = true;
     const detach = () => {
       if (!listening) return;
@@ -44,16 +44,16 @@ export function abortableSource(events, signal, onAbort) {
     try { onAbort(); } catch { /* Cancellation preserves the signal's reason. */ }
     close(signal.reason).catch(() => {});
   };
-  signal.addEventListener("abort", abort, { once: true });
-  if (signal.aborted) abort();
+  signal?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted) abort();
 
   return {
     [Symbol.asyncIterator]() { return this; },
     async next() {
-      signal.throwIfAborted();
+      signal?.throwIfAborted();
       const result = await waitFor(
         Promise.resolve().then(async () => {
-          signal.throwIfAborted();
+          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");
@@ -61,7 +61,7 @@ export function abortableSource(events, signal, onAbort) {
           return synchronous ? { done: next.done, value: await next.value } : next;
         }),
       );
-      signal.throwIfAborted();
+      signal?.throwIfAborted();
       if (result.done) {
         closed = true;
         reader?.releaseLock();
@@ -71,12 +71,12 @@ export function abortableSource(events, signal, onAbort) {
     async return() {
       const cleanup = close();
       cleanup.catch(() => {});
-      if (!signal.aborted) await waitFor(cleanup);
+      if (!signal?.aborted) await waitFor(cleanup);
       return { done: true, value: undefined };
     },
     async dispose() {
       try { await this.return(); }
-      finally { signal.removeEventListener("abort", abort); }
+      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

@@ -35,8 +35,10 @@ export async function* readStructured(
       );
     }
     signal?.throwIfAborted();
-    source = signal === undefined ? undefined : abortableSource(events, signal, dispose);
-    for await (const event of source ?? events) {
+    // 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();