streamfold 0.1.6 → 0.1.8

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.8",
   "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>,
@@ -240,6 +240,9 @@ export function createStructuredStreamPool<Id = string>(
   options?: StructuredStreamPoolOptions,
 ): StructuredStreamPool<Id>;
 
+/** Compile and cache the embedded WebAssembly module before creating scanners. */
+export function prepareStreamfold(): Promise<void>;
+
 export const STREAMFOLD_ENGINE: "rust-wasm";
 export const DEFAULT_STREAM_LIMITS: Readonly<
   Required<

package/src/index.js

@@ -9,6 +9,7 @@ import { applyImmutableChanges, freezeJson } from "./internal/snapshots.js";
 import { annotateError, streamError } from "./internal/errors.js";
 
 export { isStructuredStreamError } from "./internal/errors.js";
+export { prepareWasm as prepareStreamfold } from "./internal/wasm-runtime.js";
 export { defineAdapter } from "./adapter.js";
 export { readStructured } from "./read-structured.js";
 

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

@@ -17,6 +17,8 @@ const PATCH_COMPLETE = 8;
 
 const encoder = new TextEncoder();
 let exports;
+let compiledModule;
+let compiling;
 
 const decodeBase64 = (base64) => {
   const binary = globalThis.atob(base64);
@@ -32,11 +34,39 @@ const getExports = () => {
   if (typeof WebAssembly !== "object") {
     throw new Error("Streamfold requires WebAssembly support");
   }
-  const module = new WebAssembly.Module(decodeBase64(wasmBinaryBase64));
+  const module =
+    compiledModule ?? new WebAssembly.Module(decodeBase64(wasmBinaryBase64));
   exports = new WebAssembly.Instance(module, {}).exports;
   return exports;
 };
 
+export const prepareWasm = () => {
+  if (exports !== undefined || compiledModule !== undefined)
+    return Promise.resolve();
+  if (compiling !== undefined) return compiling;
+  if (
+    typeof WebAssembly !== "object" ||
+    typeof WebAssembly.compile !== "function"
+  ) {
+    return Promise.reject(new Error("Streamfold requires WebAssembly support"));
+  }
+  try {
+    compiling = WebAssembly.compile(decodeBase64(wasmBinaryBase64)).then(
+      (module) => {
+        compiledModule = module;
+        compiling = undefined;
+      },
+      (error) => {
+        compiling = undefined;
+        throw error;
+      },
+    );
+  } catch (error) {
+    return Promise.reject(error);
+  }
+  return compiling;
+};
+
 const describeParserError = ({ wasm, handle, maxBytes, maxDepth }, code) => {
   const offset = wasm.streamfold_parser_error_offset(handle) >>> 0;
   const byte = wasm.streamfold_parser_error_byte(handle);
@@ -196,15 +226,27 @@ 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 remaining = parser.maxBytes - (wasm.streamfold_parser_bytes_seen(handle) >>> 0);
+  if (chunk.length > remaining) throw parserError(parser, 7);
+  const capacity = Math.min(chunk.length * 3, remaining);
   const pointer = wasm.streamfold_parser_input(handle, capacity);
   let length = 0;
   if (capacity > 0) {
     const input = new Uint8Array(wasm.memory.buffer, pointer, capacity);
     const result = encoder.encodeInto(chunk, input);
     if (result.read !== chunk.length) {
-      throw new Error("Unable to encode the complete stream fragment");
+      throw parserError(parser, 7);
     }
     length = result.written;
   }

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();