streamfold 0.1.2 → 0.1.5

package/src/index.d.ts

@@ -14,6 +14,8 @@ export interface StructuredStreamOptions {
   readonly maxBytes?: number;
   /** Maximum nested object/array depth. Defaults to 128. */
   readonly maxDepth?: number;
+  /** Live views by default; immutable snapshots are frozen with structural sharing. */
+  readonly snapshots?: "live" | "immutable";
 }
 
 export interface StructuredStreamPoolOptions extends StructuredStreamOptions {
@@ -44,7 +46,7 @@ export interface StreamState {
   readonly complete: boolean;
   readonly inString: boolean;
   readonly changes: readonly StructuredStreamPatch[];
-  /** A live view updated in place; use `changes` for reactive state updates. */
+  /** Live by default; a stable, deeply frozen value with `snapshots: "immutable"`. */
   readonly partialValue: JsonValue | undefined;
 }
 
@@ -68,12 +70,131 @@ export interface EventStructuredStream<Event, Id = string> {
   finish(): readonly CompletedStructuredStream<Id>[];
 }
 
+export type StructuredStreamLifecycleUpdate<Id = string> =
+  | (ActiveStructuredStream<Id> & { readonly type: "start" | "update" })
+  | (CompletedStructuredStream<Id> & { readonly type: "complete" });
+
+export interface BatchEventStructuredStream<Event, Id = string>
+  extends EventStructuredStream<Event, Id> {
+  /** Consume once and return every call update, in event order. */
+  pushAll(event: Event): readonly StructuredStreamLifecycleUpdate<Id>[];
+}
+
+export type StructuredStreamErrorCode =
+  | "UNEXPECTED_TOKEN"
+  | "MISMATCHED_CLOSING"
+  | "TRAILING_DATA"
+  | "EMPTY_INPUT"
+  | "INCOMPLETE_JSON"
+  | "INVALID_JSON"
+  | "PARSER_ERROR"
+  | "MAX_BYTES_EXCEEDED"
+  | "MAX_DEPTH_EXCEEDED"
+  | "MAX_ACTIVE_STREAMS_EXCEEDED"
+  | "DUPLICATE_STREAM"
+  | "UNKNOWN_STREAM"
+  | "STREAM_DISPOSED"
+  | "INVALID_CHUNK"
+  | "INVALID_OPTIONS"
+  | "INTEGRATION_ERROR";
+
+/** Metadata on the original SyntaxError, RangeError, TypeError, or Error. */
+export interface StructuredStreamError extends Error {
+  readonly streamfold: true;
+  readonly code: StructuredStreamErrorCode;
+  /** Zero-based UTF-8 byte offset, when supplied by the parser. */
+  readonly byteOffset?: number;
+  readonly id?: unknown;
+  readonly operation?: "start" | "push" | "finish" | "getFieldState";
+  readonly adapter?: string;
+  readonly eventType?: string;
+}
+
+export function isStructuredStreamError(
+  error: unknown,
+): error is StructuredStreamError;
+
+export interface StructuredStreamDiagnostic {
+  readonly code: "NO_TOOL_EVENTS" | "UNMATCHED_TOOL_EVENT" | "STREAM_ERROR";
+  readonly message: string;
+  readonly adapter: string;
+  readonly eventType?: string;
+  readonly id?: unknown;
+  readonly error?: Error;
+}
+
+export interface StructuredStreamIntegrationOptions {
+  /** Opt-in diagnostics. No logging by default. Callback exceptions are ignored. */
+  readonly onDiagnostic?: (diagnostic: StructuredStreamDiagnostic) => void;
+}
+
 export interface StructuredStreamIntegration<Event, Id = string> {
+  (pool?: StructuredStreamPool<Id>): EventStructuredStream<Event, Id>;
+}
+
+export interface BatchStructuredStreamIntegration<Event, Id = string> {
   (
     pool?: StructuredStreamPool<Id>,
-  ): EventStructuredStream<Event, Id>;
+    options?: StructuredStreamIntegrationOptions,
+  ): BatchEventStructuredStream<Event, Id>;
 }
 
+export type StructuredStreamOperation<Id = string> =
+  | { readonly type: "start"; readonly id: Id }
+  | { readonly type: "delta"; readonly id: Id; readonly text: string }
+  | { readonly type: "end"; readonly id: Id }
+  | { readonly type: "abort"; readonly id: Id };
+
+/** Translate one decoded event into zero or more ordered operations. */
+export type StructuredStreamMapper<Event, Id = string> = (
+  event: Event,
+) => readonly StructuredStreamOperation<Id>[];
+
+export interface BatchStructuredStream<Event, Id = string> {
+  pushAll(event: Event): readonly StructuredStreamLifecycleUpdate<Id>[];
+  /** Finalize remaining calls only. Repeated successful calls return []. */
+  finish(): readonly (CompletedStructuredStream<Id> & {
+    readonly type: "complete";
+  })[];
+  /** Release active parsers without finalizing their JSON. Idempotent. */
+  dispose(): void;
+}
+
+export interface StructuredStreamAdapterOptions
+  extends StructuredStreamPoolOptions,
+    StructuredStreamIntegrationOptions {}
+
+/** Calling the adapter creates an independent parser pool. */
+export interface StructuredStreamAdapter<Event, Id = string> {
+  (options?: StructuredStreamAdapterOptions): BatchStructuredStream<Event, Id>;
+}
+
+export function defineAdapter<Event, Id = string>(
+  mapEvent: StructuredStreamMapper<Event, Id>,
+): StructuredStreamAdapter<Event, Id>;
+
+export interface ReadStructuredOptions<Event, Id = string>
+  extends StructuredStreamIntegrationOptions {
+  readonly adapter: StructuredStreamAdapter<Event, Id>;
+  readonly integration?: never;
+  readonly limits?: StructuredStreamPoolOptions;
+}
+
+export interface ReadStructuredIntegrationOptions<Event, Id = string>
+  extends StructuredStreamIntegrationOptions {
+  readonly integration: BatchStructuredStreamIntegration<Event, Id>;
+  readonly adapter?: never;
+  readonly limits?: StructuredStreamPoolOptions;
+}
+
+/** Consume decoded events, finalizing at EOF and disposing on every exit. */
+export function readStructured<Event, Id = string>(
+  events: AsyncIterable<Event> | Iterable<Event>,
+  options:
+    | ReadStructuredOptions<Event, Id>
+    | ReadStructuredIntegrationOptions<Event, Id>,
+): AsyncGenerator<StructuredStreamLifecycleUpdate<Id>, void, unknown>;
+
 export class IncrementalJsonScanner {
   constructor(options?: StructuredStreamOptions);
   push(chunk: string): StreamState;
@@ -82,7 +203,7 @@ export class IncrementalJsonScanner {
   dispose(): void;
   readonly backend: "rust-wasm";
   readonly state: StreamState;
-  /** A live view updated in place; use `StreamState.changes` for reactive updates. */
+  /** Live by default; a stable, deeply frozen value with `snapshots: "immutable"`. */
   readonly value: JsonValue | undefined;
 }
 
@@ -91,10 +212,7 @@ export class StructuredStreamPool<Id = string> {
   start(id: Id, initialChunk?: string): ActiveStructuredStream<Id>;
   push(id: Id, delta: string): ActiveStructuredStream<Id>;
   finish(id: Id): CompletedStructuredStream<Id>;
-  getFieldState(
-    id: Id,
-    path: StructuredStreamPath,
-  ): StructuredStreamFieldState;
+  getFieldState(id: Id, path: StructuredStreamPath): StructuredStreamFieldState;
   abort(id: Id): boolean;
   has(id: Id): boolean;
   readonly activeIds: readonly Id[];
@@ -105,6 +223,12 @@ export function createStructuredStream(): IncrementalJsonScanner;
 export function createStructuredStream(
   options: StructuredStreamOptions,
 ): IncrementalJsonScanner;
+export function createStructuredStream<Event, Id = string>(
+  adapter: StructuredStreamAdapter<Event, Id>,
+): BatchStructuredStream<Event, Id>;
+export function createStructuredStream<Event, Id = string>(
+  integration: BatchStructuredStreamIntegration<Event, Id>,
+): BatchEventStructuredStream<Event, Id>;
 export function createStructuredStream<Event, Id = string>(
   integration: StructuredStreamIntegration<Event, Id>,
 ): EventStructuredStream<Event, Id>;
@@ -114,5 +238,10 @@ export function createStructuredStreamPool<Id = string>(
 
 export const STREAMFOLD_ENGINE: "rust-wasm";
 export const DEFAULT_STREAM_LIMITS: Readonly<
-  Required<StructuredStreamPoolOptions>
+  Required<
+    Pick<
+      StructuredStreamPoolOptions,
+      "maxBytes" | "maxDepth" | "maxActiveStreams"
+    >
+  >
 >;

package/src/index.js

@@ -5,6 +5,12 @@ import {
   pushWasmParser,
   readWasmParser,
 } from "./internal/wasm-runtime.js";
+import { applyImmutableChanges, freezeJson } from "./internal/snapshots.js";
+import { annotateError, streamError } from "./internal/errors.js";
+
+export { isStructuredStreamError } from "./internal/errors.js";
+export { defineAdapter } from "./adapter.js";
+export { readStructured } from "./read-structured.js";
 
 export const STREAMFOLD_ENGINE = "rust-wasm";
 export const DEFAULT_STREAM_LIMITS = Object.freeze({
@@ -23,9 +29,11 @@ export class IncrementalJsonScanner {
   #value;
   #completion = createCompletionNode();
   #error;
+  #immutable;
 
   constructor(options = {}) {
     const limits = normalizeStreamLimits(options);
+    this.#immutable = limits.snapshots === "immutable";
     this.#parser = createWasmParser(limits);
     parserFinalizer?.register(this, this.#parser, this);
   }
@@ -40,7 +48,7 @@ export class IncrementalJsonScanner {
         partialValue: this.#value,
       };
     } catch (error) {
-      throw this.#fail(error);
+      throw this.#fail(error, "push");
     }
   }
 
@@ -54,7 +62,7 @@ export class IncrementalJsonScanner {
         partialValue: this.#value,
       };
     } catch (error) {
-      throw this.#fail(error);
+      throw this.#fail(error, "finish");
     }
   }
 
@@ -71,9 +79,7 @@ export class IncrementalJsonScanner {
   }
 
   getFieldState(path) {
-    return isFieldComplete(this.#completion, path)
-      ? "complete"
-      : "partial";
+    return isFieldComplete(this.#completion, path) ? "complete" : "partial";
   }
 
   get backend() {
@@ -92,12 +98,15 @@ export class IncrementalJsonScanner {
   #getParser() {
     if (this.#error !== undefined) throw this.#error;
     if (this.#parser === undefined) {
-      throw new Error("Structured stream has been disposed");
+      throw streamError(
+        new Error("Structured stream has been disposed"),
+        "STREAM_DISPOSED",
+      );
     }
     return this.#parser;
   }
 
-  #fail(error) {
+  #fail(error, operation) {
     const failure =
       error instanceof Error ? error : new Error("Structured stream failed");
     if (this.#parser !== undefined) {
@@ -106,22 +115,26 @@ export class IncrementalJsonScanner {
       this.#parser = undefined;
     }
     this.#error = failure;
+    if (failure.operation === undefined) annotateError(failure, { operation });
     return failure;
   }
 
   #apply(changes) {
+    if (this.#immutable)
+      this.#value = applyImmutableChanges(this.#value, changes);
     for (const change of changes) {
       if (change.op === "complete") {
         markFieldComplete(this.#completion, change.path);
       } else if (change.op === "set") {
         invalidateField(this.#completion, change.path);
+        if (this.#immutable) continue;
         const value = Array.isArray(change.value)
           ? []
           : change.value !== null && typeof change.value === "object"
             ? {}
             : change.value;
         this.#value = setAtPath(this.#value, change.path, value);
-      } else {
+      } else if (!this.#immutable) {
         const current = getAtPath(this.#value, change.path);
         this.#value = setAtPath(
           this.#value,
@@ -143,8 +156,11 @@ export const createStructuredStream = (integrationOrOptions) => {
     return new IncrementalJsonScanner(integrationOrOptions);
   }
   if (typeof integrationOrOptions !== "function") {
-    throw new TypeError(
-      "A Streamfold argument must be an integration or options object",
+    throw streamError(
+      new TypeError(
+        "A Streamfold argument must be an integration or options object",
+      ),
+      "INVALID_OPTIONS",
     );
   }
   return integrationOrOptions();
@@ -161,16 +177,32 @@ export class StructuredStreamPool {
     this.#streamOptions = {
       maxBytes: limits.maxBytes,
       maxDepth: limits.maxDepth,
+      snapshots: limits.snapshots,
     };
   }
 
   start(id, initialChunk = "") {
+    if (typeof initialChunk !== "string") {
+      throw streamError(
+        new TypeError("A structured stream chunk must be a string"),
+        "INVALID_CHUNK",
+        { id, operation: "start" },
+      );
+    }
     if (this.#streams.has(id)) {
-      throw new Error(`Structured stream already exists: ${String(id)}`);
+      throw streamError(
+        new Error(`Structured stream already exists: ${String(id)}`),
+        "DUPLICATE_STREAM",
+        { id, operation: "start" },
+      );
     }
     if (this.#streams.size >= this.#maxActiveStreams) {
-      throw new RangeError(
-        `Structured stream pool exceeds maxActiveStreams (${this.#maxActiveStreams})`,
+      throw streamError(
+        new RangeError(
+          `Structured stream pool exceeds maxActiveStreams (${this.#maxActiveStreams})`,
+        ),
+        "MAX_ACTIVE_STREAMS_EXCEEDED",
+        { id, operation: "start" },
       );
     }
 
@@ -179,35 +211,54 @@ export class StructuredStreamPool {
       chunks: [],
     };
     this.#streams.set(id, entry);
-    if (initialChunk.length > 0) return this.push(id, initialChunk);
+    if (initialChunk.length > 0) {
+      try {
+        return this.push(id, initialChunk);
+      } catch (error) {
+        throw annotateError(error, { operation: "start" });
+      }
+    }
     return { id, ...entry.scanner.state };
   }
 
   push(id, delta) {
     const entry = this.#streams.get(id);
     if (entry === undefined) {
-      throw new Error(`Unknown structured stream: ${String(id)}`);
+      throw streamError(
+        new Error(
+          `Unknown structured stream: ${String(id)} (push requires an active call)`,
+        ),
+        "UNKNOWN_STREAM",
+        { id, operation: "push" },
+      );
     }
     entry.chunks.push(delta);
     try {
       return { id, ...entry.scanner.push(delta) };
     } catch (error) {
       this.abort(id);
-      throw error;
+      throw annotateError(error, { id, operation: "push" });
     }
   }
 
   finish(id) {
     const entry = this.#streams.get(id);
     if (entry === undefined) {
-      throw new Error(`Unknown structured stream: ${String(id)}`);
+      throw streamError(
+        new Error(`Unknown structured stream: ${String(id)}`),
+        "UNKNOWN_STREAM",
+        { id, operation: "finish" },
+      );
     }
 
     try {
       const state = entry.scanner.finish();
       const text = entry.chunks.join("");
       const value = JSON.parse(text);
+      if (this.#streamOptions.snapshots === "immutable") freezeJson(value);
       return { id, text, value, ...state };
+    } catch (error) {
+      throw annotateError(error, { id, operation: "finish" });
     } finally {
       this.#streams.delete(id);
       entry.scanner.dispose();
@@ -217,7 +268,11 @@ export class StructuredStreamPool {
   getFieldState(id, path) {
     const entry = this.#streams.get(id);
     if (entry === undefined) {
-      throw new Error(`Unknown structured stream: ${String(id)}`);
+      throw streamError(
+        new Error(`Unknown structured stream: ${String(id)}`),
+        "UNKNOWN_STREAM",
+        { id, operation: "getFieldState" },
+      );
     }
     return entry.scanner.getFieldState(path);
   }
@@ -312,17 +367,17 @@ const isFieldComplete = (root, path) => {
 
 const normalizeLimit = (value, fallback, name) => {
   const limit = value ?? fallback;
-  if (
-    !Number.isSafeInteger(limit) ||
-    limit <= 0 ||
-    limit > 0xffff_ffff
-  ) {
-    throw new RangeError(`${name} must be an integer between 1 and 4294967295`);
+  if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 0xffff_ffff) {
+    throw streamError(
+      new RangeError(`${name} must be an integer between 1 and 4294967295`),
+      "INVALID_OPTIONS",
+    );
   }
   return limit;
 };
 
 const normalizeStreamLimits = (options) => ({
+  snapshots: normalizeSnapshots(options.snapshots),
   maxBytes: normalizeLimit(
     options.maxBytes,
     DEFAULT_STREAM_LIMITS.maxBytes,
@@ -335,6 +390,16 @@ const normalizeStreamLimits = (options) => ({
   ),
 });
 
+const normalizeSnapshots = (snapshots = "live") => {
+  if (snapshots !== "live" && snapshots !== "immutable") {
+    throw streamError(
+      new TypeError('snapshots must be "live" or "immutable"'),
+      "INVALID_OPTIONS",
+    );
+  }
+  return snapshots;
+};
+
 const normalizePoolLimits = (options) => ({
   ...normalizeStreamLimits(options),
   maxActiveStreams: normalizeLimit(

package/src/internal/diagnostics.js

@@ -0,0 +1,9 @@
+export const emitDiagnostic = (options, diagnostic) => {
+  try {
+    if (typeof options?.onDiagnostic === "function") {
+      options.onDiagnostic(diagnostic);
+    }
+  } catch {
+    // Observability must not interrupt parsing or resource cleanup.
+  }
+};

package/src/internal/errors.js

@@ -0,0 +1,14 @@
+export const annotateError = (error, details) => {
+  try {
+    Object.assign(error, details);
+  } catch {
+    // Preserve an upstream error even when it cannot accept metadata.
+  }
+  return error;
+};
+
+export const isStructuredStreamError = (error) =>
+  error instanceof Error && error.streamfold === true;
+
+export const streamError = (error, code, details = {}) =>
+  annotateError(error, { streamfold: true, code, ...details });

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;
+};