@pretable/stream-adapter 0.4.0 → 0.5.0

package/README.md

@@ -1,16 +1,16 @@
 # @pretable/stream-adapter
 
-RAF-batched streaming integration for [pretable](https://pretable.dev/). Bridges async streams (HTTP SSE, WebSocket, partial-JSON from LLMs) into the grid with predictable per-frame batching.
+RAF-batched streaming integration for [Pretable](https://pretable.dev/). It bridges async sources such as SSE, WebSockets, and partial JSON into an ID-generic row model with one atomic transaction per animation frame.
 
 ## When to reach for this
 
-Use `@pretable/stream-adapter` when you need to drive a grid from a live data stream and want one DOM mutation per animation frame regardless of incoming stream rate. The package ships:
+Use `@pretable/stream-adapter` when a live source emits faster than the browser should publish row-model revisions. The package ships:
 
-- A **batcher** ([`createBatcher`](#createbatcher)) that coalesces `add` / `update` / `remove` into one `applyTransaction` per RAF tick.
-- Two **connect** functions that wire an `AsyncIterable` source through the batcher into a grid.
-- Two **parse** functions that turn raw UTF-8 string streams (e.g., `fetch().body`) into typed row iterables.
+- A **batcher** that coalesces `add`, `{ id, changes }` updates, and ID removals into one transaction per RAF tick.
+- Two **connectors** that consume `AsyncIterable` sources and target a structural row model.
+- Two **parsers** that turn raw UTF-8 string streams into typed row iterables.
 
-If you only need one-shot row mounting, use `<Pretable>` from `@pretable/react` instead — this package is for live streams.
+If your data changes only through ordinary React props, pass `rows` to `@pretable/react` instead. This package is for explicit streaming ownership.
 
 ## Install
 
@@ -19,25 +19,27 @@ npm install @pretable/stream-adapter
 # or pnpm add @pretable/stream-adapter, yarn add @pretable/stream-adapter
 ```
 
-## Minimal example — element stream
+## Element streams
 
-```ts
-import { connectElementStream, parseElementStream } from "@pretable/stream-adapter";
-import { createGrid } from "@pretable/core";
+`connectElementStream` treats every complete element as a row to add. Pass a Pretable row model or any object satisfying `RowModelLike<TRow, TRowId>`.
 
-const grid = createGrid({ columns: [...], rows: [] });
+```ts
+import {
+  connectElementStream,
+  parseElementStream,
+} from "@pretable/stream-adapter";
 
 const response = await fetch("/api/rows");
 const stringStream = response.body!.pipeThrough(new TextDecoderStream());
-const rowStream = parseElementStream<MyRow>(stringStream);
+const rows = parseElementStream<MyRow>(stringStream);
 
-const connection = connectElementStream(grid, rowStream);
-await connection.done; // resolves when the server closes the response
+const connection = connectElementStream(rowModel, rows);
+await connection.done;
 ```
 
-## Minimal example — partial-update stream (e.g., LLM)
+## Partial streams
 
-When an LLM is streaming partial JSON, every chunk is an incomplete row. `connectPartialStream` upserts by row id so each chunk visibly fills out the corresponding row.
+`connectPartialStream` sends every partial to the fixed `options.rowId` as `{ id, changes }`. The target row must already exist unless `createRow(partial, id)` is provided. The connector never asserts that a partial is a complete row.
 
 ```ts
 import {
@@ -45,29 +47,45 @@ import {
   parsePartialStream,
 } from "@pretable/stream-adapter";
 
-const partialStream = parsePartialStream<MyRow>(stringStream);
-const connection = connectPartialStream(grid, partialStream, { rowId: "id" });
+const partials = parsePartialStream<ChatRow>(stringStream);
+const connection = connectPartialStream(rowModel, partials, {
+  rowId: "assistant-1",
+  onIssue(issue) {
+    console.warn(issue.code, issue.rowId);
+  },
+  createRow(partial, id) {
+    return { id, role: "assistant", content: partial.content ?? "" };
+  },
+});
 ```
 
-## API
+When the model returns an `unknown-update-id` issue, `onIssue` receives it. If `createRow` is present, its complete result is added in a separate atomic transaction; otherwise nothing is fabricated.
 
-See **[`stream-adapter.api.md`](./stream-adapter.api.md)** for the full generated public-API report.
+## Direct batching
 
-### `createBatcher`
+Use `createBatcher` when your source does not fit either connector:
 
-Returns a `TransactionBatcher` that buffers add / update / remove calls and applies them once per `requestAnimationFrame`. Use directly when you have a custom stream source that doesn't fit the `connect*Stream` shape.
-
-### `connectElementStream` / `parseElementStream`
+```ts
+const batcher = createBatcher(rowModel);
 
-`connectElementStream(grid, stream)` drives a grid from an `AsyncIterable<TRow>`. `parseElementStream(stream)` turns a string stream into an `AsyncIterable<TRow>` by parsing top-level array elements.
+batcher.update([{ id: 42, changes: { status: "ready" } }]);
+batcher.remove([7]);
+// The scheduled RAF flushes automatically; flush() is also available.
+```
 
-### `connectPartialStream` / `parsePartialStream`
+The batcher preserves string and number IDs. It detaches the transaction payload before publication, clears the published batch before calling the model, and remains usable if `applyTransaction` throws.
 
-Same shape, but for incremental field updates: `parsePartialStream` emits `Partial<TRow>` values as the streaming parser fills each element; `connectPartialStream` upserts by `options.rowId`.
+## API
 
-### Types
+See **[`stream-adapter.api.md`](./stream-adapter.api.md)** for the generated public-API report.
 
-`GridLike<TRow>` is the structural grid contract — any object with `applyTransaction({ add?, update?, remove? })` works, including a custom adapter. `TransactionBatcher<TRow>` and `StreamConnection` are the handle types returned by the constructors above. `PartialStreamOptions` is the options bag for `connectPartialStream`.
+- `createBatcher(rowModel)` returns a `TransactionBatcher<TRow, TRowId>`.
+- `connectElementStream(rowModel, stream)` adds complete streamed rows.
+- `connectPartialStream(rowModel, stream, options)` updates one fixed row ID.
+- `parseElementStream(stream)` parses complete top-level array elements.
+- `parsePartialStream(stream)` parses incremental partial objects.
+- `RowModelLike<TRow, TRowId>` is the dependency-free structural model contract.
+- `PartialStreamOptions<TRow, TRowId>`, `TransactionBatcher<TRow, TRowId>`, and `StreamConnection` describe the connector and lifecycle handles.
 
 ## License
 

package/dist/index.cjs

@@ -3,39 +3,93 @@
 var jsonStream = require('@cacheplane/json-stream');
 
 // src/create-batcher.ts
-function createBatcher(grid) {
+function createBatcher(rowModel) {
   let addBuffer = [];
   let updateBuffer = [];
   let removeBuffer = [];
   let rafId = null;
   let disposed = false;
+  let rejectError;
+  const errorListeners = /* @__PURE__ */ new Set();
+  let failed = false;
+  let failure;
+  const error = new Promise((_resolve, reject) => {
+    rejectError = reject;
+  });
+  error.catch(() => void 0);
+  function fail(error2) {
+    if (disposed) return;
+    disposed = true;
+    failed = true;
+    failure = error2;
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    addBuffer = [];
+    updateBuffer = [];
+    removeBuffer = [];
+    const listeners = [...errorListeners];
+    errorListeners.clear();
+    for (const listener of listeners) {
+      try {
+        listener(error2);
+      } catch {
+      }
+    }
+    rejectError(error2);
+  }
   function scheduleFlush() {
     if (rafId !== null || disposed) return;
     rafId = requestAnimationFrame(() => {
       rafId = null;
-      applyBuffered();
+      if (disposed) return;
+      try {
+        applyBuffered();
+      } catch (error2) {
+        fail(error2);
+      }
     });
   }
   function applyBuffered() {
     if (addBuffer.length === 0 && updateBuffer.length === 0 && removeBuffer.length === 0) {
       return;
     }
-    const tx = {};
-    if (addBuffer.length > 0) {
-      tx.add = addBuffer;
-      addBuffer = [];
+    const bufferedAdds = addBuffer;
+    const bufferedUpdates = updateBuffer;
+    const bufferedRemovals = removeBuffer;
+    addBuffer = [];
+    updateBuffer = [];
+    removeBuffer = [];
+    const transaction = {};
+    if (bufferedAdds.length > 0) {
+      transaction.add = bufferedAdds.map((row) => ({ ...row }));
     }
-    if (updateBuffer.length > 0) {
-      tx.update = updateBuffer;
-      updateBuffer = [];
+    if (bufferedUpdates.length > 0) {
+      transaction.update = bufferedUpdates.map(({ id, changes }) => ({
+        id,
+        changes: { ...changes }
+      }));
     }
-    if (removeBuffer.length > 0) {
-      tx.remove = removeBuffer;
-      removeBuffer = [];
+    if (bufferedRemovals.length > 0) {
+      transaction.remove = [...bufferedRemovals];
     }
-    grid.applyTransaction(tx);
+    rowModel.applyTransaction(transaction);
   }
   return {
+    error,
+    subscribeError(listener) {
+      if (failed) {
+        try {
+          listener(failure);
+        } catch {
+        }
+        return () => void 0;
+      }
+      if (disposed) return () => void 0;
+      errorListeners.add(listener);
+      return () => errorListeners.delete(listener);
+    },
     add(rows) {
       if (disposed) return;
       addBuffer.push(...rows);
@@ -69,14 +123,17 @@ function createBatcher(grid) {
       addBuffer = [];
       updateBuffer = [];
       removeBuffer = [];
+      errorListeners.clear();
     }
   };
 }
 
 // src/connect-element-stream.ts
-function connectElementStream(grid, stream) {
-  const batcher = createBatcher(grid);
+function connectElementStream(rowModel, stream) {
+  const iterator = stream[Symbol.asyncIterator]();
+  const batcher = createBatcher(rowModel);
   let disposed = false;
+  let sourceClosed = false;
   let resolveDone;
   let rejectDone;
   const done = new Promise((resolve, reject) => {
@@ -84,37 +141,102 @@ function connectElementStream(grid, stream) {
     rejectDone = reject;
   });
   done.catch(() => void 0);
-  (async () => {
+  const closeSource = () => {
+    if (sourceClosed) return;
+    sourceClosed = true;
     try {
-      for await (const element of stream) {
-        if (disposed) break;
-        batcher.add([element]);
+      const closing = iterator.return?.();
+      if (closing !== void 0)
+        void Promise.resolve(closing).catch(() => void 0);
+    } catch {
+    }
+  };
+  let settled = false;
+  const settle = (failure, flush = true, close = failure !== void 0) => {
+    if (settled) return;
+    settled = true;
+    disposed = true;
+    if (close) closeSource();
+    let finalFailure = failure;
+    if (flush) {
+      try {
+        batcher.flush();
+      } catch (error) {
+        finalFailure ??= { error };
+      }
+    }
+    batcher.dispose();
+    if (finalFailure === void 0) resolveDone();
+    else rejectDone(finalFailure.error);
+  };
+  batcher.subscribeError((error) => {
+    settle({ error }, false, true);
+  });
+  void (async () => {
+    try {
+      while (!disposed) {
+        const result = await iterator.next();
+        if (disposed) return;
+        if (result.done) {
+          settle();
+          return;
+        }
+        batcher.add([result.value]);
       }
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
     } catch (err) {
-      batcher.flush();
-      batcher.dispose();
-      rejectDone(err);
+      settle({ error: err }, true, true);
     }
-  })();
+  })().catch((error) => settle({ error }));
   return {
     done,
     dispose() {
       if (disposed) return;
-      disposed = true;
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
+      settle(void 0, true, true);
     }
   };
 }
 
 // src/connect-partial-stream.ts
-function connectPartialStream(grid, stream, options) {
-  const batcher = createBatcher(grid);
+function sameValueZero(left, right) {
+  return left === right || typeof left === "number" && typeof right === "number" && Number.isNaN(left) && Number.isNaN(right);
+}
+function connectPartialStream(rowModel, stream, options) {
+  const iterator = stream[Symbol.asyncIterator]();
+  const issueAwareRowModel = {
+    applyTransaction(transaction) {
+      const result = rowModel.applyTransaction(transaction);
+      if (result === void 0 || result.issues === void 0) return result;
+      let targetMissing = false;
+      for (const issue of result.issues) {
+        if (issue.code !== "unknown-update-id" || issue.rowId === void 0 || !sameValueZero(issue.rowId, options.rowId)) {
+          continue;
+        }
+        targetMissing = true;
+        options.onIssue?.({
+          code: "unknown-update-id",
+          rowId: options.rowId
+        });
+      }
+      if (targetMissing && options.createRow !== void 0) {
+        const updates = transaction.update ?? [];
+        const combinedChanges = {};
+        let hasTargetUpdate = false;
+        for (const update of updates) {
+          if (!sameValueZero(update.id, options.rowId)) continue;
+          Object.assign(combinedChanges, update.changes);
+          hasTargetUpdate = true;
+        }
+        if (hasTargetUpdate) {
+          const row = options.createRow(combinedChanges, options.rowId);
+          rowModel.applyTransaction({ add: [row] });
+        }
+      }
+      return result;
+    }
+  };
+  const batcher = createBatcher(issueAwareRowModel);
   let disposed = false;
+  let sourceClosed = false;
   let resolveDone;
   let rejectDone;
   const done = new Promise((resolve, reject) => {
@@ -122,29 +244,57 @@ function connectPartialStream(grid, stream, options) {
     rejectDone = reject;
   });
   done.catch(() => void 0);
-  (async () => {
+  const closeSource = () => {
+    if (sourceClosed) return;
+    sourceClosed = true;
+    try {
+      const closing = iterator.return?.();
+      if (closing !== void 0)
+        void Promise.resolve(closing).catch(() => void 0);
+    } catch {
+    }
+  };
+  let settled = false;
+  const settle = (failure, flush = true, close = failure !== void 0) => {
+    if (settled) return;
+    settled = true;
+    disposed = true;
+    if (close) closeSource();
+    let finalFailure = failure;
+    if (flush) {
+      try {
+        batcher.flush();
+      } catch (error) {
+        finalFailure ??= { error };
+      }
+    }
+    batcher.dispose();
+    if (finalFailure === void 0) resolveDone();
+    else rejectDone(finalFailure.error);
+  };
+  batcher.subscribeError((error) => {
+    settle({ error }, false, true);
+  });
+  void (async () => {
     try {
-      for await (const partial of stream) {
-        if (disposed) break;
-        batcher.update([{ ...partial, id: options.rowId }]);
+      while (!disposed) {
+        const result = await iterator.next();
+        if (disposed) return;
+        if (result.done) {
+          settle();
+          return;
+        }
+        batcher.update([{ id: options.rowId, changes: result.value }]);
       }
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
     } catch (err) {
-      batcher.flush();
-      batcher.dispose();
-      rejectDone(err);
+      settle({ error: err }, true, true);
     }
-  })();
+  })().catch((error) => settle({ error }));
   return {
     done,
     dispose() {
       if (disposed) return;
-      disposed = true;
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
+      settle(void 0, true, true);
     }
   };
 }

package/dist/index.d.cts

@@ -1,17 +1,24 @@
 /**
- * Structural type for any grid that supports `applyTransaction`. Avoids
- * hard coupling to `@pretable-internal/grid-core` so consumers can wire
- * up streaming against a custom grid implementation that conforms to the
- * same shape.
+ * Structural contract for a row model that accepts atomic row transactions.
+ * The adapter depends only on this ID-generic shape, so callers may pass a
+ * Pretable row model or a compatible custom implementation.
  *
  * @public
  */
-interface GridLike<TRow extends Record<string, unknown>> {
-    applyTransaction(transaction: {
+interface RowModelLike<TRow extends object, TRowId extends string | number> {
+    readonly applyTransaction: (transaction: {
         add?: TRow[];
-        update?: Partial<TRow>[];
-        remove?: string[];
-    }): void;
+        update?: {
+            id: TRowId;
+            changes: Partial<TRow>;
+        }[];
+        remove?: TRowId[];
+    }) => void | {
+        readonly issues?: readonly {
+            readonly code: string;
+            readonly rowId?: TRowId;
+        }[];
+    };
 }
 /**
  * RAF-batched mutator returned by {@link createBatcher}. Buffer
@@ -22,12 +29,19 @@ interface GridLike<TRow extends Record<string, unknown>> {
  *
  * @public
  */
-interface TransactionBatcher<TRow extends Record<string, unknown>> {
-    add(rows: TRow[]): void;
-    update(patches: Partial<TRow>[]): void;
-    remove(ids: string[]): void;
-    flush(): void;
-    dispose(): void;
+interface TransactionBatcher<TRow extends object, TRowId extends string | number> {
+    /** Rejects with the exact model error from a scheduled RAF transaction. */
+    readonly error: Promise<never>;
+    /** Observes a scheduled model failure synchronously before later races. */
+    readonly subscribeError: (listener: (error: unknown) => void) => () => void;
+    readonly add: (rows: readonly TRow[]) => void;
+    readonly update: (patches: readonly {
+        readonly id: TRowId;
+        readonly changes: Partial<TRow>;
+    }[]) => void;
+    readonly remove: (ids: readonly TRowId[]) => void;
+    readonly flush: () => void;
+    readonly dispose: () => void;
 }
 /**
  * Handle returned by the `connect*Stream` functions. `done` resolves
@@ -37,31 +51,30 @@ interface TransactionBatcher<TRow extends Record<string, unknown>> {
  * @public
  */
 interface StreamConnection {
-    done: Promise<void>;
-    dispose(): void;
+    readonly done: Promise<void>;
+    readonly dispose: () => void;
 }
 
 /**
  * Create a `requestAnimationFrame`-batched mutator that coalesces
  * `add` / `update` / `remove` calls into a single `applyTransaction` per
- * frame. Use this when driving a grid from a stream that emits faster
- * than the browser can render — batching keeps DOM mutations to one per
- * frame regardless of stream rate.
+ * frame. Use this when driving a row model from a stream that emits faster
+ * than the browser can render.
  *
  * @example
  * ```ts
- * const batcher = createBatcher(grid);
+ * const batcher = createBatcher(rowModel);
  * batcher.add([{ id: "1", name: "Ada" }]);
- * batcher.update([{ id: "1", age: 36 }]);
+ * batcher.update([{ id: "1", changes: { age: 36 } }]);
  * batcher.flush(); // optional — RAF will flush automatically
  * ```
  *
  * @public
  */
-declare function createBatcher<TRow extends Record<string, unknown>>(grid: GridLike<TRow>): TransactionBatcher<TRow>;
+declare function createBatcher<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>): TransactionBatcher<TRow, TRowId>;
 
 /**
- * Drive a grid from an `AsyncIterable<TRow>`. Each yielded row is added
+ * Drive a row model from an `AsyncIterable<TRow>`. Each yielded row is added
  * via a {@link createBatcher | RAF batcher}; the returned
  * {@link StreamConnection} resolves `done` when the stream ends and
  * supports `dispose()` for early cancellation.
@@ -71,34 +84,35 @@ declare function createBatcher<TRow extends Record<string, unknown>>(grid: GridL
  *
  * @public
  */
-declare function connectElementStream<TRow extends Record<string, unknown>>(grid: GridLike<TRow>, stream: AsyncIterable<TRow>): StreamConnection;
+declare function connectElementStream<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>, stream: AsyncIterable<TRow>): StreamConnection;
 
 /**
- * Options for {@link connectPartialStream}. `rowId` names the field on
- * each partial row used to identify it for upsert (the field must be
- * present in every emitted partial — partials missing the rowId are
- * ignored).
+ * Options for {@link connectPartialStream}. `rowId` is the fixed target for
+ * every partial update. Unknown targets are reported through `onIssue`; an
+ * optional `createRow` factory may turn the partial into a complete row to add.
  *
  * @public
  */
-interface PartialStreamOptions {
-    rowId: string;
+interface PartialStreamOptions<TRow extends object, TRowId extends string | number> {
+    readonly rowId: TRowId;
+    readonly onIssue?: (issue: {
+        readonly code: "unknown-update-id";
+        readonly rowId: TRowId;
+    }) => void;
+    readonly createRow?: (partial: Partial<TRow>, id: TRowId) => TRow;
 }
 /**
- * Drive a grid from an `AsyncIterable<Partial<TRow>>`. Each yielded
- * partial is upserted by `options.rowId` — new rowIds are added,
- * existing rowIds are merged via `applyTransaction.update`. Useful when
- * a stream emits incremental field updates (e.g., partial JSON parses)
- * rather than complete rows.
+ * Drive a row model from an `AsyncIterable<Partial<TRow>>`. Every yielded
+ * partial updates the fixed `options.rowId` via a RAF-batched
+ * `{ id, changes }` transaction. A missing target is reported instead of
+ * fabricating a row; provide `createRow` when the stream is allowed to add one.
  *
  * Pair with {@link parsePartialStream} for end-to-end partial-update
  * streaming over UTF-8 strings.
  *
  * @public
  */
-declare function connectPartialStream<TRow extends Record<string, unknown> & {
-    id: string;
-}>(grid: GridLike<TRow>, stream: AsyncIterable<Partial<TRow>>, options: PartialStreamOptions): StreamConnection;
+declare function connectPartialStream<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>, stream: AsyncIterable<Partial<TRow>>, options: PartialStreamOptions<TRow, TRowId>): StreamConnection;
 
 /**
  * Parse a UTF-8 string stream into an `AsyncIterable<TRow>`. Built on
@@ -126,4 +140,4 @@ declare function parseElementStream<TRow>(stream: AsyncIterable<string>): AsyncI
  */
 declare function parsePartialStream<TRow>(stream: AsyncIterable<string>): AsyncIterable<Partial<TRow>>;
 
-export { type GridLike, type PartialStreamOptions, type StreamConnection, type TransactionBatcher, connectElementStream, connectPartialStream, createBatcher, parseElementStream, parsePartialStream };
+export { type PartialStreamOptions, type RowModelLike, type StreamConnection, type TransactionBatcher, connectElementStream, connectPartialStream, createBatcher, parseElementStream, parsePartialStream };

package/dist/index.d.ts

@@ -1,17 +1,24 @@
 /**
- * Structural type for any grid that supports `applyTransaction`. Avoids
- * hard coupling to `@pretable-internal/grid-core` so consumers can wire
- * up streaming against a custom grid implementation that conforms to the
- * same shape.
+ * Structural contract for a row model that accepts atomic row transactions.
+ * The adapter depends only on this ID-generic shape, so callers may pass a
+ * Pretable row model or a compatible custom implementation.
  *
  * @public
  */
-interface GridLike<TRow extends Record<string, unknown>> {
-    applyTransaction(transaction: {
+interface RowModelLike<TRow extends object, TRowId extends string | number> {
+    readonly applyTransaction: (transaction: {
         add?: TRow[];
-        update?: Partial<TRow>[];
-        remove?: string[];
-    }): void;
+        update?: {
+            id: TRowId;
+            changes: Partial<TRow>;
+        }[];
+        remove?: TRowId[];
+    }) => void | {
+        readonly issues?: readonly {
+            readonly code: string;
+            readonly rowId?: TRowId;
+        }[];
+    };
 }
 /**
  * RAF-batched mutator returned by {@link createBatcher}. Buffer
@@ -22,12 +29,19 @@ interface GridLike<TRow extends Record<string, unknown>> {
  *
  * @public
  */
-interface TransactionBatcher<TRow extends Record<string, unknown>> {
-    add(rows: TRow[]): void;
-    update(patches: Partial<TRow>[]): void;
-    remove(ids: string[]): void;
-    flush(): void;
-    dispose(): void;
+interface TransactionBatcher<TRow extends object, TRowId extends string | number> {
+    /** Rejects with the exact model error from a scheduled RAF transaction. */
+    readonly error: Promise<never>;
+    /** Observes a scheduled model failure synchronously before later races. */
+    readonly subscribeError: (listener: (error: unknown) => void) => () => void;
+    readonly add: (rows: readonly TRow[]) => void;
+    readonly update: (patches: readonly {
+        readonly id: TRowId;
+        readonly changes: Partial<TRow>;
+    }[]) => void;
+    readonly remove: (ids: readonly TRowId[]) => void;
+    readonly flush: () => void;
+    readonly dispose: () => void;
 }
 /**
  * Handle returned by the `connect*Stream` functions. `done` resolves
@@ -37,31 +51,30 @@ interface TransactionBatcher<TRow extends Record<string, unknown>> {
  * @public
  */
 interface StreamConnection {
-    done: Promise<void>;
-    dispose(): void;
+    readonly done: Promise<void>;
+    readonly dispose: () => void;
 }
 
 /**
  * Create a `requestAnimationFrame`-batched mutator that coalesces
  * `add` / `update` / `remove` calls into a single `applyTransaction` per
- * frame. Use this when driving a grid from a stream that emits faster
- * than the browser can render — batching keeps DOM mutations to one per
- * frame regardless of stream rate.
+ * frame. Use this when driving a row model from a stream that emits faster
+ * than the browser can render.
  *
  * @example
  * ```ts
- * const batcher = createBatcher(grid);
+ * const batcher = createBatcher(rowModel);
  * batcher.add([{ id: "1", name: "Ada" }]);
- * batcher.update([{ id: "1", age: 36 }]);
+ * batcher.update([{ id: "1", changes: { age: 36 } }]);
  * batcher.flush(); // optional — RAF will flush automatically
  * ```
  *
  * @public
  */
-declare function createBatcher<TRow extends Record<string, unknown>>(grid: GridLike<TRow>): TransactionBatcher<TRow>;
+declare function createBatcher<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>): TransactionBatcher<TRow, TRowId>;
 
 /**
- * Drive a grid from an `AsyncIterable<TRow>`. Each yielded row is added
+ * Drive a row model from an `AsyncIterable<TRow>`. Each yielded row is added
  * via a {@link createBatcher | RAF batcher}; the returned
  * {@link StreamConnection} resolves `done` when the stream ends and
  * supports `dispose()` for early cancellation.
@@ -71,34 +84,35 @@ declare function createBatcher<TRow extends Record<string, unknown>>(grid: GridL
  *
  * @public
  */
-declare function connectElementStream<TRow extends Record<string, unknown>>(grid: GridLike<TRow>, stream: AsyncIterable<TRow>): StreamConnection;
+declare function connectElementStream<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>, stream: AsyncIterable<TRow>): StreamConnection;
 
 /**
- * Options for {@link connectPartialStream}. `rowId` names the field on
- * each partial row used to identify it for upsert (the field must be
- * present in every emitted partial — partials missing the rowId are
- * ignored).
+ * Options for {@link connectPartialStream}. `rowId` is the fixed target for
+ * every partial update. Unknown targets are reported through `onIssue`; an
+ * optional `createRow` factory may turn the partial into a complete row to add.
  *
  * @public
  */
-interface PartialStreamOptions {
-    rowId: string;
+interface PartialStreamOptions<TRow extends object, TRowId extends string | number> {
+    readonly rowId: TRowId;
+    readonly onIssue?: (issue: {
+        readonly code: "unknown-update-id";
+        readonly rowId: TRowId;
+    }) => void;
+    readonly createRow?: (partial: Partial<TRow>, id: TRowId) => TRow;
 }
 /**
- * Drive a grid from an `AsyncIterable<Partial<TRow>>`. Each yielded
- * partial is upserted by `options.rowId` — new rowIds are added,
- * existing rowIds are merged via `applyTransaction.update`. Useful when
- * a stream emits incremental field updates (e.g., partial JSON parses)
- * rather than complete rows.
+ * Drive a row model from an `AsyncIterable<Partial<TRow>>`. Every yielded
+ * partial updates the fixed `options.rowId` via a RAF-batched
+ * `{ id, changes }` transaction. A missing target is reported instead of
+ * fabricating a row; provide `createRow` when the stream is allowed to add one.
  *
  * Pair with {@link parsePartialStream} for end-to-end partial-update
  * streaming over UTF-8 strings.
  *
  * @public
  */
-declare function connectPartialStream<TRow extends Record<string, unknown> & {
-    id: string;
-}>(grid: GridLike<TRow>, stream: AsyncIterable<Partial<TRow>>, options: PartialStreamOptions): StreamConnection;
+declare function connectPartialStream<TRow extends object, TRowId extends string | number>(rowModel: RowModelLike<TRow, TRowId>, stream: AsyncIterable<Partial<TRow>>, options: PartialStreamOptions<TRow, TRowId>): StreamConnection;
 
 /**
  * Parse a UTF-8 string stream into an `AsyncIterable<TRow>`. Built on
@@ -126,4 +140,4 @@ declare function parseElementStream<TRow>(stream: AsyncIterable<string>): AsyncI
  */
 declare function parsePartialStream<TRow>(stream: AsyncIterable<string>): AsyncIterable<Partial<TRow>>;
 
-export { type GridLike, type PartialStreamOptions, type StreamConnection, type TransactionBatcher, connectElementStream, connectPartialStream, createBatcher, parseElementStream, parsePartialStream };
+export { type PartialStreamOptions, type RowModelLike, type StreamConnection, type TransactionBatcher, connectElementStream, connectPartialStream, createBatcher, parseElementStream, parsePartialStream };

package/dist/index.mjs

@@ -1,39 +1,93 @@
 import { create, push, isArrayNode, isComplete, finish, isObjectNode } from '@cacheplane/json-stream';
 
 // src/create-batcher.ts
-function createBatcher(grid) {
+function createBatcher(rowModel) {
   let addBuffer = [];
   let updateBuffer = [];
   let removeBuffer = [];
   let rafId = null;
   let disposed = false;
+  let rejectError;
+  const errorListeners = /* @__PURE__ */ new Set();
+  let failed = false;
+  let failure;
+  const error = new Promise((_resolve, reject) => {
+    rejectError = reject;
+  });
+  error.catch(() => void 0);
+  function fail(error2) {
+    if (disposed) return;
+    disposed = true;
+    failed = true;
+    failure = error2;
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    addBuffer = [];
+    updateBuffer = [];
+    removeBuffer = [];
+    const listeners = [...errorListeners];
+    errorListeners.clear();
+    for (const listener of listeners) {
+      try {
+        listener(error2);
+      } catch {
+      }
+    }
+    rejectError(error2);
+  }
   function scheduleFlush() {
     if (rafId !== null || disposed) return;
     rafId = requestAnimationFrame(() => {
       rafId = null;
-      applyBuffered();
+      if (disposed) return;
+      try {
+        applyBuffered();
+      } catch (error2) {
+        fail(error2);
+      }
     });
   }
   function applyBuffered() {
     if (addBuffer.length === 0 && updateBuffer.length === 0 && removeBuffer.length === 0) {
       return;
     }
-    const tx = {};
-    if (addBuffer.length > 0) {
-      tx.add = addBuffer;
-      addBuffer = [];
+    const bufferedAdds = addBuffer;
+    const bufferedUpdates = updateBuffer;
+    const bufferedRemovals = removeBuffer;
+    addBuffer = [];
+    updateBuffer = [];
+    removeBuffer = [];
+    const transaction = {};
+    if (bufferedAdds.length > 0) {
+      transaction.add = bufferedAdds.map((row) => ({ ...row }));
     }
-    if (updateBuffer.length > 0) {
-      tx.update = updateBuffer;
-      updateBuffer = [];
+    if (bufferedUpdates.length > 0) {
+      transaction.update = bufferedUpdates.map(({ id, changes }) => ({
+        id,
+        changes: { ...changes }
+      }));
     }
-    if (removeBuffer.length > 0) {
-      tx.remove = removeBuffer;
-      removeBuffer = [];
+    if (bufferedRemovals.length > 0) {
+      transaction.remove = [...bufferedRemovals];
     }
-    grid.applyTransaction(tx);
+    rowModel.applyTransaction(transaction);
   }
   return {
+    error,
+    subscribeError(listener) {
+      if (failed) {
+        try {
+          listener(failure);
+        } catch {
+        }
+        return () => void 0;
+      }
+      if (disposed) return () => void 0;
+      errorListeners.add(listener);
+      return () => errorListeners.delete(listener);
+    },
     add(rows) {
       if (disposed) return;
       addBuffer.push(...rows);
@@ -67,14 +121,17 @@ function createBatcher(grid) {
       addBuffer = [];
       updateBuffer = [];
       removeBuffer = [];
+      errorListeners.clear();
     }
   };
 }
 
 // src/connect-element-stream.ts
-function connectElementStream(grid, stream) {
-  const batcher = createBatcher(grid);
+function connectElementStream(rowModel, stream) {
+  const iterator = stream[Symbol.asyncIterator]();
+  const batcher = createBatcher(rowModel);
   let disposed = false;
+  let sourceClosed = false;
   let resolveDone;
   let rejectDone;
   const done = new Promise((resolve, reject) => {
@@ -82,37 +139,102 @@ function connectElementStream(grid, stream) {
     rejectDone = reject;
   });
   done.catch(() => void 0);
-  (async () => {
+  const closeSource = () => {
+    if (sourceClosed) return;
+    sourceClosed = true;
     try {
-      for await (const element of stream) {
-        if (disposed) break;
-        batcher.add([element]);
+      const closing = iterator.return?.();
+      if (closing !== void 0)
+        void Promise.resolve(closing).catch(() => void 0);
+    } catch {
+    }
+  };
+  let settled = false;
+  const settle = (failure, flush = true, close = failure !== void 0) => {
+    if (settled) return;
+    settled = true;
+    disposed = true;
+    if (close) closeSource();
+    let finalFailure = failure;
+    if (flush) {
+      try {
+        batcher.flush();
+      } catch (error) {
+        finalFailure ??= { error };
+      }
+    }
+    batcher.dispose();
+    if (finalFailure === void 0) resolveDone();
+    else rejectDone(finalFailure.error);
+  };
+  batcher.subscribeError((error) => {
+    settle({ error }, false, true);
+  });
+  void (async () => {
+    try {
+      while (!disposed) {
+        const result = await iterator.next();
+        if (disposed) return;
+        if (result.done) {
+          settle();
+          return;
+        }
+        batcher.add([result.value]);
       }
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
     } catch (err) {
-      batcher.flush();
-      batcher.dispose();
-      rejectDone(err);
+      settle({ error: err }, true, true);
     }
-  })();
+  })().catch((error) => settle({ error }));
   return {
     done,
     dispose() {
       if (disposed) return;
-      disposed = true;
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
+      settle(void 0, true, true);
     }
   };
 }
 
 // src/connect-partial-stream.ts
-function connectPartialStream(grid, stream, options) {
-  const batcher = createBatcher(grid);
+function sameValueZero(left, right) {
+  return left === right || typeof left === "number" && typeof right === "number" && Number.isNaN(left) && Number.isNaN(right);
+}
+function connectPartialStream(rowModel, stream, options) {
+  const iterator = stream[Symbol.asyncIterator]();
+  const issueAwareRowModel = {
+    applyTransaction(transaction) {
+      const result = rowModel.applyTransaction(transaction);
+      if (result === void 0 || result.issues === void 0) return result;
+      let targetMissing = false;
+      for (const issue of result.issues) {
+        if (issue.code !== "unknown-update-id" || issue.rowId === void 0 || !sameValueZero(issue.rowId, options.rowId)) {
+          continue;
+        }
+        targetMissing = true;
+        options.onIssue?.({
+          code: "unknown-update-id",
+          rowId: options.rowId
+        });
+      }
+      if (targetMissing && options.createRow !== void 0) {
+        const updates = transaction.update ?? [];
+        const combinedChanges = {};
+        let hasTargetUpdate = false;
+        for (const update of updates) {
+          if (!sameValueZero(update.id, options.rowId)) continue;
+          Object.assign(combinedChanges, update.changes);
+          hasTargetUpdate = true;
+        }
+        if (hasTargetUpdate) {
+          const row = options.createRow(combinedChanges, options.rowId);
+          rowModel.applyTransaction({ add: [row] });
+        }
+      }
+      return result;
+    }
+  };
+  const batcher = createBatcher(issueAwareRowModel);
   let disposed = false;
+  let sourceClosed = false;
   let resolveDone;
   let rejectDone;
   const done = new Promise((resolve, reject) => {
@@ -120,29 +242,57 @@ function connectPartialStream(grid, stream, options) {
     rejectDone = reject;
   });
   done.catch(() => void 0);
-  (async () => {
+  const closeSource = () => {
+    if (sourceClosed) return;
+    sourceClosed = true;
+    try {
+      const closing = iterator.return?.();
+      if (closing !== void 0)
+        void Promise.resolve(closing).catch(() => void 0);
+    } catch {
+    }
+  };
+  let settled = false;
+  const settle = (failure, flush = true, close = failure !== void 0) => {
+    if (settled) return;
+    settled = true;
+    disposed = true;
+    if (close) closeSource();
+    let finalFailure = failure;
+    if (flush) {
+      try {
+        batcher.flush();
+      } catch (error) {
+        finalFailure ??= { error };
+      }
+    }
+    batcher.dispose();
+    if (finalFailure === void 0) resolveDone();
+    else rejectDone(finalFailure.error);
+  };
+  batcher.subscribeError((error) => {
+    settle({ error }, false, true);
+  });
+  void (async () => {
     try {
-      for await (const partial of stream) {
-        if (disposed) break;
-        batcher.update([{ ...partial, id: options.rowId }]);
+      while (!disposed) {
+        const result = await iterator.next();
+        if (disposed) return;
+        if (result.done) {
+          settle();
+          return;
+        }
+        batcher.update([{ id: options.rowId, changes: result.value }]);
       }
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
     } catch (err) {
-      batcher.flush();
-      batcher.dispose();
-      rejectDone(err);
+      settle({ error: err }, true, true);
     }
-  })();
+  })().catch((error) => settle({ error }));
   return {
     done,
     dispose() {
       if (disposed) return;
-      disposed = true;
-      batcher.flush();
-      batcher.dispose();
-      resolveDone();
+      settle(void 0, true, true);
     }
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pretable/stream-adapter",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Streaming row adapters for Pretable.",
   "license": "MIT",
   "repository": {