Streaming

RAF-batch async sources into an explicit Pretable row model.

@pretable/stream-adapter connects an async source to an explicit row model. It coalesces producer events into at most one atomic row-model transaction per animation frame, no matter how fast the source emits.

There are two source shapes, and they behave nothing alike. An element stream appends a whole new row per event; a partial stream patches one fixed row ID over and over. A partial stream adds a row only if you hand it a createRow factory, and never more than the one row it targets. Watch both:

New rows arrive

Each yielded value is a complete row. connectElementStream appends one as it arrives — this grid starts empty and fills in:

Streaming chat grid

Turn a streaming LLM response into rows with connectElementStream and append them to the grid as they arrive.

.md

"use client";

import { connectElementStream } from "@pretable/stream-adapter";
import { PretableSurface, useDisposeOnUnmount } from "@pretable/react";
import { createLocalRowModel } from "@pretable/core";
import { useEffect, useMemo } from "react";

import { columns, type ChatRow } from "./columns";
import {
  responseEventsToChatRows,
  type ChatResponseEvent,
} from "./response-events-to-chat-rows";

export type OpenChatResponseEvents = (input: {
  readonly model: string;
  readonly prompt: string;
}) =>
  AsyncIterable<ChatResponseEvent> | Promise<AsyncIterable<ChatResponseEvent>>;

export function ChatGrid({
  prompt,
  openResponseEvents,
}: {
  prompt: string;
  openResponseEvents: OpenChatResponseEvents;
}) {
  const rowModel = useMemo(
    () => createLocalRowModel({ rows: [], columns, getRowId: (row) => row.id }),
    [],
  );

  useEffect(() => {
    let disposed = false;
    let connection: ReturnType<typeof connectElementStream> | undefined;
    void (async () => {
      const stream = await openResponseEvents({
        model: "gpt-5",
        prompt,
      });
      const rows: AsyncIterable<ChatRow> = responseEventsToChatRows(stream);
      connection = connectElementStream(rowModel, rows);
      if (disposed) connection.dispose();
    })();
    return () => {
      disposed = true;
      connection?.dispose();
    };
  }, [openResponseEvents, prompt, rowModel]);

  // NOT `useEffect(() => () => rowModel.dispose())`: StrictMode rehearses an
  // unmount in dev, `useMemo` hands the same model back to the remount, and the
  // grid then renders nothing at all. `useDisposeOnUnmount` defers the disposal
  // by a microtask so a remount can cancel it.
  useDisposeOnUnmount(rowModel);

  return (
    <PretableSurface
      ariaLabel="Streaming chat"
      model={rowModel}
      viewportHeight={320}
    />
  );
}

One row grows

Each yielded value is a Partial<TRow> patch to a single, fixed row ID. Row msg-1 below is seeded before its stream connects; msg-2 isn't seeded, so its first partial is reported through onIssue and createRow builds the row from it:

Partial row stream

Grow one row's content cell in place with connectPartialStream, covering both the seeded-row and createRow/onIssue patterns.

.md

"use client";

import { connectPartialStream } from "@pretable/stream-adapter";
import { PretableSurface, useDisposeOnUnmount } from "@pretable/react";
import { createLocalRowModel } from "@pretable/core";
import { useEffect, useMemo } from "react";

import { columns, type MessageRow } from "./columns";
import { scriptedFirstReply, scriptedSecondReply } from "./scripted-partials";

export function PartialRowGrid() {
  const rowModel = useMemo(
    () =>
      createLocalRowModel({
        // "msg-1" is seeded here, before any stream connects — the "seed
        // the row first" pattern. connectPartialStream never creates a
        // row on its own; without a row to find, every partial for an
        // unseeded id is reported through onIssue instead of applied.
        rows: [{ id: "msg-1", role: "assistant", content: "", tokens: 0 }],
        columns,
        getRowId: (row) => row.id,
      }),
    [],
  );

  useEffect(() => {
    // "msg-1" already exists, so this connection only ever patches it.
    const seeded = connectPartialStream(rowModel, scriptedFirstReply(), {
      rowId: "msg-1",
    });

    // "msg-2" does not exist yet. The first partial for it is reported
    // through onIssue as an "unknown-update-id" issue; createRow then
    // turns that partial's accumulated changes into the new row. Every
    // later partial for "msg-2" is a normal update from there on.
    const created = connectPartialStream(rowModel, scriptedSecondReply(), {
      rowId: "msg-2",
      onIssue: (issue) => {
        console.warn(`[partial-row-stream] ${issue.code}: ${issue.rowId}`);
      },
      createRow: (partial, id): MessageRow => ({
        id,
        role: "assistant",
        content: partial.content ?? "",
        tokens: partial.tokens ?? 0,
      }),
    });

    return () => {
      seeded.dispose();
      created.dispose();
    };
  }, [rowModel]);

  // NOT `useEffect(() => () => rowModel.dispose())`: StrictMode rehearses an
  // unmount in dev, `useMemo` hands the same model back to the remount, and the
  // grid then renders nothing at all. `useDisposeOnUnmount` defers the disposal
  // by a microtask so a remount can cancel it.
  useDisposeOnUnmount(rowModel);

  return (
    <PretableSurface
      ariaLabel="Partial row stream"
      model={rowModel}
      viewportHeight={220}
    />
  );
}

Own the row model explicitly

Both grids above create their own rowModel and pass it to PretableSurface via model, not rows:

import { createLocalRowModel } from "@pretable/core";
 
const rowModel = createLocalRowModel({ rows: [], columns });

For ordinary React data, the declarative rows prop is enough — the surface owns diffing for you. Reach for explicit row-model ownership, as both grids above do, when a high-frequency producer needs to publish transactions directly.

Pick the connector

Each element is a complete new row — the shape behind the grid above.

import { connectElementStream } from "@pretable/stream-adapter";
 
const connection = connectElementStream(rowModel, rows);
await connection.done;

dispose() stops consumption; done resolves on completion/disposal and rejects with source or model failures.

Streaming

New rows arrive

One row grows

Own the row model explicitly

Pick the connector

Next

Element streams

Partial streams

Parsers