streamfold 0.1.2 → 0.1.5

package/README.md

@@ -2,14 +2,18 @@
 
 Incremental structured state for streamed AI tool calls.
 
-Streamfold retains JSON parser and value state across deltas. Its Rust/WebAssembly
-engine emits compact patches that update a live partial JavaScript value without
-reparsing the complete accumulated input.
+Streamfold retains JSON parser and value state across deltas. Its embedded
+Rust/WebAssembly engine emits compact patches and works in Node.js 20+ and
+modern browsers without native build tools or provider SDK dependencies.
+
+## Install
 
 ```bash
-pnpm add streamfold
+npm install streamfold
 ```
 
+## Quick start
+
 ```ts
 import { createStructuredStream } from "streamfold";
 
@@ -17,39 +21,46 @@ const stream = createStructuredStream();
 const update = stream.push('{"city":"San');
 
 console.log(update.partialValue); // { city: "San" }
-console.log(update.changes); // compact set/append/complete patches
 
 stream.push(' Francisco"}');
 console.log(stream.getFieldState(["city"])); // "complete"
+
+stream.finish();
+stream.dispose();
 ```
 
-Resource limits are configurable and enabled by default:
+Values are live by default. Use `createStructuredStream({ snapshots: "immutable" })`
+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`.
 
-```ts
-const stream = createStructuredStream({
-  maxBytes: 2 * 1024 * 1024,
-  maxDepth: 64,
-});
-```
+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
+types and do not load provider SDKs.
 
-Use an isolated event integration when consuming an SDK stream:
+For custom protocols, import `defineAdapter` from `streamfold`. Translate each
+event into an array of `start`, `delta`, `end`, or `abort` operations. The returned
+factory creates an independent session with `pushAll(event)`, `finish()`, and
+`dispose()`. See the API reference for a complete switch-based example.
 
-```ts
-import { createStructuredStream } from "streamfold/assistant-ui";
+For automatic lifecycle management, use
+`readStructured(events, { adapter, limits })` in a `for await` loop. It wraps the
+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.
 
-const toolCalls = createStructuredStream();
+Every built-in adapter supports `pushAll(event)`, returning all ordered
+`start`, `update`, and `complete` updates, including multiple calls in one event.
+Existing `push(event)` remains available. Call `finish()` at the stream boundary.
 
-for await (const event of assistantStream) {
-  const update = toolCalls.push(event);
-  if (update) renderToolInput(update.id, update.partialValue);
-}
-```
+Pass `onDiagnostic` in a custom factory's options, as an SDK factory's second
+argument, or beside the factory in `readStructured`. Errors preserve their
+native categories and include structured codes and call context where known.
 
-Available subpaths are `assistant-ui`, `vercel-ai`, `openai`, `anthropic`,
-`gemini`, `langchain`, and `ag-ui`. They consume structural event shapes and do
-not install or load provider SDKs.
+See the repository for the [API reference](https://github.com/assistant-ui/streamfold/blob/main/API.md),
+[integration guide](https://github.com/assistant-ui/streamfold/blob/main/MIGRATION.md),
+and [benchmarks](https://github.com/assistant-ui/streamfold#performance).
 
-See the [repository README](https://github.com/assistant-ui/streamfold#readme)
-for benchmarks, methodology, and development instructions. The
-[migration guide](https://github.com/assistant-ui/streamfold/blob/main/MIGRATION.md)
-covers direct streams and every bundled integration.
+MIT © Streamfold contributors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamfold",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Protocol-neutral incremental state for structured AI streams",
   "type": "module",
   "license": "MIT",
@@ -67,9 +67,11 @@
     "tool-calling",
     "webassembly"
   ],
+  "scripts": {
+    "prepack": "node ../../scripts/build-wasm.mjs"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true
-  },
-  "scripts": {}
-}
+  }
+}

package/src/adapter.js

@@ -0,0 +1,161 @@
+import { createStructuredStreamPool } from "./index.js";
+import {
+  annotateError,
+  isStructuredStreamError,
+  streamError,
+} from "./internal/errors.js";
+import { emitDiagnostic } from "./internal/diagnostics.js";
+
+export function defineAdapter(mapEvent) {
+  if (typeof mapEvent !== "function") {
+    throw streamError(
+      new TypeError("An adapter mapper must be a function"),
+      "INVALID_OPTIONS",
+    );
+  }
+
+  return (options) => {
+    const pool = createStructuredStreamPool(options);
+    let status = "active";
+    let failure;
+    let eventType;
+    let operationContext;
+    let receivedEvents = false;
+    let matched = false;
+
+    const diagnose = (diagnostic) =>
+      emitDiagnostic(options, { adapter: "custom", eventType, ...diagnostic });
+    const disposeActive = () => {
+      for (const id of pool.activeIds) pool.abort(id);
+    };
+
+    const fail = (error) => {
+      const original =
+        error instanceof Error
+          ? error
+          : new Error("Adapter stream failed", { cause: error });
+      const context = { adapter: "custom", eventType };
+      failure = isStructuredStreamError(original)
+        ? annotateError(original, context)
+        : streamError(original, "INTEGRATION_ERROR", {
+            ...context,
+            ...operationContext,
+          });
+      disposeActive();
+      diagnose({
+        code: "STREAM_ERROR",
+        message: failure.message,
+        error: failure,
+        id: failure.id,
+      });
+      return failure;
+    };
+
+    const assertActive = () => {
+      if (failure !== undefined) throw failure;
+      if (status !== "active") {
+        throw streamError(
+          new Error(`Adapter stream has been ${status}`),
+          status === "disposed" ? "STREAM_DISPOSED" : "INTEGRATION_ERROR",
+          { adapter: "custom" },
+        );
+      }
+    };
+
+    return {
+      pushAll(event) {
+        assertActive();
+        receivedEvents = true;
+        try {
+          const type = event?.type ?? event?.event_type ?? event?.kind;
+          eventType =
+            typeof type === "string"
+              ? type
+              : Array.isArray(event)
+                ? "operations"
+                : undefined;
+          const operations = mapEvent(event);
+          if (!Array.isArray(operations)) {
+            throw new TypeError("An adapter mapper must return an array");
+          }
+
+          const updates = [];
+          for (const operation of operations) {
+            operationContext = undefined;
+            if (
+              operation === null ||
+              typeof operation !== "object" ||
+              !("id" in operation)
+            ) {
+              throw new TypeError("An adapter operation must include an id");
+            }
+            operationContext = { id: operation.id };
+            switch (operation.type) {
+              case "start":
+                operationContext.operation = "start";
+                updates.push({ type: "start", ...pool.start(operation.id) });
+                break;
+              case "delta":
+                operationContext.operation = "push";
+                if (typeof operation.text !== "string") {
+                  throw new TypeError("An adapter delta must include text");
+                }
+                updates.push({
+                  type: "update",
+                  ...pool.push(operation.id, operation.text),
+                });
+                break;
+              case "end":
+                operationContext.operation = "finish";
+                updates.push({
+                  type: "complete",
+                  ...pool.finish(operation.id),
+                });
+                break;
+              case "abort":
+                pool.abort(operation.id);
+                break;
+              default:
+                throw new TypeError("Unknown adapter operation type");
+            }
+            matched = true;
+          }
+          return updates;
+        } catch (error) {
+          throw fail(error);
+        } finally {
+          eventType = undefined;
+          operationContext = undefined;
+        }
+      },
+
+      finish() {
+        if (failure !== undefined) throw failure;
+        if (status === "finished") return [];
+        assertActive();
+        try {
+          const completed = pool.activeIds.map((id) => ({
+            type: "complete",
+            ...pool.finish(id),
+          }));
+          status = "finished";
+          if (receivedEvents && !matched) {
+            diagnose({
+              code: "NO_TOOL_EVENTS",
+              message:
+                "No tool operations were mapped; text-only streams are valid, otherwise check the event mapper",
+            });
+          }
+          return completed;
+        } catch (error) {
+          throw fail(error);
+        }
+      },
+
+      dispose() {
+        disposeActive();
+        if (status === "active") status = "disposed";
+      },
+    };
+  };
+}

package/src/ag-ui.d.ts

@@ -1,6 +1,7 @@
 import type {
-  EventStructuredStream,
-  StructuredStreamIntegration,
+  BatchEventStructuredStream,
+  BatchStructuredStreamIntegration,
+  StructuredStreamIntegrationOptions,
   StructuredStreamPool,
 } from "./index.js";
 
@@ -24,8 +25,9 @@ export type AgUiToolCallEvent =
       readonly [key: string]: unknown;
     };
 
-export const agUI: StructuredStreamIntegration<AgUiToolCallEvent, string>;
+export const agUI: BatchStructuredStreamIntegration<AgUiToolCallEvent, string>;
 
 export function createStructuredStream(
   pool?: StructuredStreamPool<string>,
-): EventStructuredStream<AgUiToolCallEvent, string>;
+  options?: StructuredStreamIntegrationOptions,
+): BatchEventStructuredStream<AgUiToolCallEvent, string>;

package/src/ag-ui.js

@@ -1,14 +1,22 @@
 import { createStructuredStreamPool } from "./index.js";
 import { createIntegration } from "./internal/integration.js";
 
-export const agUI = (pool = createStructuredStreamPool()) =>
-  createIntegration(pool, (event, complete) => {
-    if (event.type === "TOOL_CALL_START") return pool.start(event.toolCallId);
-    if (event.type === "TOOL_CALL_ARGS") {
-      return pool.push(event.toolCallId, event.delta);
-    }
-    if (event.type === "TOOL_CALL_END") return complete(event.toolCallId);
-    return undefined;
-  });
+export const agUI = (pool = createStructuredStreamPool(), options) =>
+  createIntegration(
+    pool,
+    (event, calls) => {
+      if (event.type === "TOOL_CALL_START")
+        return calls.start(event.toolCallId);
+      if (event.type === "TOOL_CALL_ARGS") {
+        return calls.push(event.toolCallId, event.delta);
+      }
+      if (event.type === "TOOL_CALL_END")
+        return calls.complete(event.toolCallId);
+      return undefined;
+    },
+    undefined,
+    "ag-ui",
+    options,
+  );
 
 export { agUI as createStructuredStream };

package/src/anthropic.d.ts

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

package/src/anthropic.js

@@ -1,34 +1,48 @@
 import { createStructuredStreamPool } from "./index.js";
 import { createIntegration } from "./internal/integration.js";
 
-export const anthropic = (pool = createStructuredStreamPool()) => {
+export const anthropic = (pool = createStructuredStreamPool(), options) => {
   const idsByIndex = new Map();
 
-  return createIntegration(pool, (event, complete) => {
-    if (
-      event.type === "content_block_start" &&
-      (event.content_block.type === "tool_use" ||
-        event.content_block.type === "server_tool_use")
-    ) {
-      idsByIndex.set(event.index, event.content_block.id);
-      return pool.start(event.content_block.id);
-    }
+  return createIntegration(
+    pool,
+    (event, calls) => {
+      if (
+        event.type === "content_block_start" &&
+        (event.content_block.type === "tool_use" ||
+          event.content_block.type === "server_tool_use")
+      ) {
+        idsByIndex.set(event.index, event.content_block.id);
+        return calls.start(event.content_block.id);
+      }
 
-    const id = idsByIndex.get(event.index);
-    if (id === undefined) return undefined;
+      const id = idsByIndex.get(event.index);
+      if (id === undefined) {
+        if (
+          event.type === "content_block_delta" &&
+          event.delta.type === "input_json_delta"
+        ) {
+          calls.unmatched("Arguments delta has no matching tool block index");
+        }
+        return undefined;
+      }
 
-    if (
-      event.type === "content_block_delta" &&
-      event.delta.type === "input_json_delta"
-    ) {
-      return pool.push(id, event.delta.partial_json);
-    }
-    if (event.type === "content_block_stop") {
-      idsByIndex.delete(event.index);
-      return complete(id);
-    }
-    return undefined;
-  });
+      if (
+        event.type === "content_block_delta" &&
+        event.delta.type === "input_json_delta"
+      ) {
+        return calls.push(id, event.delta.partial_json);
+      }
+      if (event.type === "content_block_stop") {
+        idsByIndex.delete(event.index);
+        return calls.complete(id);
+      }
+      return undefined;
+    },
+    undefined,
+    "anthropic",
+    options,
+  );
 };
 
 export { anthropic as createStructuredStream };

package/src/assistant-ui.d.ts

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

package/src/assistant-ui.js

@@ -3,29 +3,40 @@ import { createIntegration } from "./internal/integration.js";
 
 const pathKey = (path) => path.join("/");
 
-export const assistantUI = (pool = createStructuredStreamPool()) => {
+export const assistantUI = (pool = createStructuredStreamPool(), options) => {
   const idsByPath = new Map();
 
-  return createIntegration(pool, (event, complete) => {
-    const key = pathKey(event.path);
+  return createIntegration(
+    pool,
+    (event, calls) => {
+      const key = pathKey(event.path);
 
-    if (event.type === "part-start" && event.part.type === "tool-call") {
-      idsByPath.set(key, event.part.toolCallId);
-      return pool.start(event.part.toolCallId);
-    }
+      if (event.type === "part-start" && event.part.type === "tool-call") {
+        idsByPath.set(key, event.part.toolCallId);
+        return calls.start(event.part.toolCallId);
+      }
 
-    const id = idsByPath.get(key);
-    if (id === undefined) return undefined;
+      const id = idsByPath.get(key);
+      if (id === undefined) {
+        if (event.type === "tool-call-args-text-finish") {
+          calls.unmatched("Tool completion has no matching part path");
+        }
+        return undefined;
+      }
 
-    if (event.type === "text-delta") {
-      return pool.push(id, event.textDelta);
-    }
-    if (event.type === "tool-call-args-text-finish") {
-      idsByPath.delete(key);
-      return complete(id);
-    }
-    return undefined;
-  });
+      if (event.type === "text-delta") {
+        return calls.push(id, event.textDelta);
+      }
+      if (event.type === "tool-call-args-text-finish") {
+        idsByPath.delete(key);
+        return calls.complete(id);
+      }
+      return undefined;
+    },
+    undefined,
+    "assistant-ui",
+    options,
+  );
 };
 
 export { assistantUI as createStructuredStream };

package/src/gemini.d.ts

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

package/src/gemini.js

@@ -1,12 +1,12 @@
 import { createStructuredStreamPool } from "./index.js";
 import { createIntegration } from "./internal/integration.js";
 
-export const gemini = (pool = createStructuredStreamPool()) => {
+export const gemini = (pool = createStructuredStreamPool(), options) => {
   const idsByIndex = new Map();
 
   return createIntegration(
     pool,
-    (event, complete) => {
+    (event, calls) => {
       if (
         event.event_type === "step.start" &&
         event.step.type === "function_call"
@@ -18,7 +18,7 @@ export const gemini = (pool = createStructuredStreamPool()) => {
             : event.step.arguments
               ? JSON.stringify(event.step.arguments)
               : "";
-        return pool.start(event.step.id, initial);
+        return calls.start(event.step.id, initial);
       }
 
       if (
@@ -27,15 +27,16 @@ export const gemini = (pool = createStructuredStreamPool()) => {
       ) {
         const id = idsByIndex.get(event.index);
         if (id !== undefined) {
-          return pool.push(id, event.delta.partial_arguments);
+          return calls.push(id, event.delta.partial_arguments);
         }
+        calls.unmatched("Arguments delta has no matching function call index");
       }
 
       if (
         event.event_type === "interaction.completed" ||
         event.event_type === "interaction.complete"
       ) {
-        for (const id of idsByIndex.values()) complete(id);
+        for (const id of idsByIndex.values()) calls.complete(id);
         idsByIndex.clear();
       }
       return undefined;
@@ -44,6 +45,8 @@ export const gemini = (pool = createStructuredStreamPool()) => {
       for (const id of idsByIndex.values()) complete(id);
       idsByIndex.clear();
     },
+    "gemini",
+    options,
   );
 };