streamfold 0.1.4 → 0.1.6

package/README.md

@@ -29,11 +29,36 @@ stream.finish();
 stream.dispose();
 ```
 
+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`.
+
 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.
 
+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.
+
+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.
+
+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.
+
+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.
+
 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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "streamfold",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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/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,
   );
 };