vastgrid 0.1.1 → 0.2.1

package/src/core/format.ts

@@ -0,0 +1,309 @@
+/**
+ * How cells show their values with the `number` and `date` of a column's format (§5.1 of the specification): 0.1's
+ * `NumberFormat` and `DateFormat`, ported from `vastgrid-core` (Intl formats, with the exact digits of decimals,
+ * and date patterns such as `yyyy/MM/dd`).
+ */
+import type { Column, ColumnFormat, DateFormat, JsonValue, NumberFormat } from "vastgrid-spec";
+
+const decimalLiteral = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
+
+/**
+ * A value as input for `Intl.NumberFormat`, or null when it is not a finite number. Numeric strings
+ * stay strings, which `Intl.NumberFormat` formats from their exact digits.
+ */
+function numberInput(value: JsonValue): number | string | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string") return null;
+  const text = value.trim();
+  return decimalLiteral.test(text) ? text : null;
+}
+
+function numberFormatter(locale: string | undefined, format: NumberFormat, grouping: boolean) {
+  const style = format.style ?? "decimal";
+  if (style === "currency" && !format.currency) throw new RangeError("A currency format needs `currency`.");
+  const options: Intl.NumberFormatOptions = {
+    style,
+    useGrouping: format.grouping ?? grouping,
+    minimumFractionDigits: format.fractionDigits ?? format.minimumFractionDigits,
+    maximumFractionDigits: format.fractionDigits ?? format.maximumFractionDigits,
+  };
+  if (style === "currency") {
+    options.currency = format.currency;
+    if (format.currencyDisplay) options.currencyDisplay = format.currencyDisplay;
+  }
+  if (format.notation) options.notation = format.notation;
+  if (format.signDisplay) options.signDisplay = format.signDisplay;
+  // A maximum below the style's default minimum (2 for USD, 0 for percent) lowers the minimum too.
+  if (options.maximumFractionDigits !== undefined && options.minimumFractionDigits === undefined) {
+    options.minimumFractionDigits = Math.min(
+      options.maximumFractionDigits,
+      new Intl.NumberFormat(locale, { ...options, maximumFractionDigits: undefined }).resolvedOptions()
+        .minimumFractionDigits ?? 0,
+    );
+  }
+  const intl = new Intl.NumberFormat(locale, options);
+  const prefix = format.prefix ?? "";
+  const suffix = format.suffix ?? "";
+  // `format` takes exact decimal strings (Intl.NumberFormat v3); the types only list numbers.
+  return (value: number | string) => `${prefix}${intl.format(value as number)}${suffix}`;
+}
+
+/** The parts of an ISO-like date, time or timestamp. */
+interface DateParts {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  /** Fraction digits of the second, as written. */
+  fraction: string;
+  hasDate: boolean;
+  hasTime: boolean;
+  /** Offset from UTC in minutes, for values with one. */
+  offset: number | null;
+}
+
+const isoDateTime =
+  /^([+-]?\d{4,})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?)?\s*(Z|[+-]\d{2}(?::?\d{2})?)?$/i;
+const isoTime = /^(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d+))?)?$/;
+
+function parseOffset(text: string | undefined) {
+  if (!text) return null;
+  if (text.toUpperCase() === "Z") return 0;
+  const sign = text.startsWith("-") ? -1 : 1;
+  const digits = text.slice(1).replace(":", "");
+  return sign * (Number(digits.slice(0, 2)) * 60 + Number(digits.slice(2) || 0));
+}
+
+function parseDate(text: string): DateParts | null {
+  const date = isoDateTime.exec(text.trim());
+  if (date) {
+    const [, year, month, day, hour, minute, second, fraction, offset] = date;
+    return {
+      year: Number(year),
+      month: Number(month),
+      day: Number(day),
+      hour: Number(hour ?? 0),
+      minute: Number(minute ?? 0),
+      second: Number(second ?? 0),
+      fraction: fraction ?? "",
+      hasDate: true,
+      hasTime: hour !== undefined,
+      offset: parseOffset(offset),
+    };
+  }
+  const time = isoTime.exec(text.trim());
+  if (!time) return null;
+  const [, hour, minute, second, fraction] = time;
+  return {
+    year: 1970,
+    month: 1,
+    day: 1,
+    hour: Number(hour),
+    minute: Number(minute),
+    second: Number(second ?? 0),
+    fraction: fraction ?? "",
+    hasDate: false,
+    hasTime: true,
+    offset: null,
+  };
+}
+
+/** The UTC time of the parts' wall clock (ignoring their offset). Years below 100 are kept. */
+function wallClock(parts: DateParts) {
+  const date = new Date(0);
+  date.setUTCFullYear(parts.year, parts.month - 1, parts.day);
+  date.setUTCHours(parts.hour, parts.minute, parts.second, Number(parts.fraction.slice(0, 3).padEnd(3, "0")));
+  return date;
+}
+
+const patternToken = /'(?:[^']|'')*'|yyyy|yy|MMMM|MMM|MM|M|dd|d|EEEE|EEE|HH|H|hh|h|mm|m|ss|s|S+|a/g;
+
+function dateFormatter(locale: string | undefined, format: DateFormat) {
+  const { pattern, timeZone, ...options } = format;
+  // Checks the time zone and the options now, not on the first value.
+  new Intl.DateTimeFormat(locale, { ...options, timeZone });
+  const custom = Object.keys(options).length > 0;
+  const formats = new Map<string, Intl.DateTimeFormat>();
+  const intl = (key: string, make: () => Intl.DateTimeFormat) => {
+    let item = formats.get(key);
+    if (!item) {
+      item = make();
+      formats.set(key, item);
+    }
+    return item;
+  };
+  /** The parts in the shown time zone: values with an offset move to `timeZone`. */
+  const local = (parts: DateParts): DateParts => {
+    if (parts.offset === null) return parts;
+    const instant = new Date(wallClock(parts).getTime() - parts.offset * 60_000);
+    const fields = intl(
+      "parts",
+      () =>
+        new Intl.DateTimeFormat("en-US-u-nu-latn", {
+          timeZone,
+          year: "numeric",
+          month: "numeric",
+          day: "numeric",
+          hour: "numeric",
+          minute: "numeric",
+          second: "numeric",
+          hourCycle: "h23",
+          era: "short",
+        }),
+    ).formatToParts(instant);
+    const field = (type: string) => Number(fields.find((part) => part.type === type)?.value ?? 0);
+    const bc = fields.find((part) => part.type === "era")?.value.startsWith("B");
+    return {
+      ...parts,
+      year: bc ? 1 - field("year") : field("year"),
+      month: field("month"),
+      day: field("day"),
+      hour: field("hour"),
+      minute: field("minute"),
+      second: field("second"),
+      offset: null,
+    };
+  };
+
+  if (pattern !== undefined) {
+    const tokens = pattern.match(patternToken) ?? [];
+    const texts = pattern.split(patternToken);
+    const name = (key: string, options: Intl.DateTimeFormatOptions, date: Date) =>
+      intl(key, () => new Intl.DateTimeFormat(locale, { ...options, timeZone: "UTC" })).format(date);
+    const pad = (value: number, length: number) =>
+      value < 0 ? `-${String(-value).padStart(length, "0")}` : String(value).padStart(length, "0");
+    return (parts: DateParts) => {
+      const shown = local(parts);
+      const date = wallClock(shown);
+      let text = texts[0];
+      tokens.forEach((token, index) => {
+        let part: string;
+        switch (token) {
+          case "yyyy":
+            part = pad(shown.year, 4);
+            break;
+          case "yy":
+            part = pad(Math.abs(shown.year) % 100, 2);
+            break;
+          case "MMMM":
+            part = name("MMMM", { month: "long" }, date);
+            break;
+          case "MMM":
+            part = name("MMM", { month: "short" }, date);
+            break;
+          case "MM":
+            part = pad(shown.month, 2);
+            break;
+          case "M":
+            part = String(shown.month);
+            break;
+          case "dd":
+            part = pad(shown.day, 2);
+            break;
+          case "d":
+            part = String(shown.day);
+            break;
+          case "EEEE":
+            part = name("EEEE", { weekday: "long" }, date);
+            break;
+          case "EEE":
+            part = name("EEE", { weekday: "short" }, date);
+            break;
+          case "HH":
+            part = pad(shown.hour, 2);
+            break;
+          case "H":
+            part = String(shown.hour);
+            break;
+          case "hh":
+            part = pad(shown.hour % 12 || 12, 2);
+            break;
+          case "h":
+            part = String(shown.hour % 12 || 12);
+            break;
+          case "a":
+            part =
+              intl("a", () => new Intl.DateTimeFormat(locale, { hour: "numeric", hour12: true, timeZone: "UTC" }))
+                .formatToParts(date)
+                .find((item) => item.type === "dayPeriod")?.value ?? (shown.hour < 12 ? "AM" : "PM");
+            break;
+          case "mm":
+            part = pad(shown.minute, 2);
+            break;
+          case "m":
+            part = String(shown.minute);
+            break;
+          case "ss":
+            part = pad(shown.second, 2);
+            break;
+          case "s":
+            part = String(shown.second);
+            break;
+          default:
+            part = token.startsWith("S")
+              ? shown.fraction.slice(0, token.length).padEnd(token.length, "0")
+              : token.slice(1, -1).replaceAll("''", "'");
+        }
+        text += part + texts[index + 1];
+      });
+      return text;
+    };
+  }
+
+  return (parts: DateParts) => {
+    const zone = parts.offset !== null ? "z" : "";
+    const shape = custom ? `custom${zone}` : `${parts.hasDate ? "d" : ""}${parts.hasTime ? "t" : ""}${zone}`;
+    const item = intl(shape, () => {
+      const defaults: Intl.DateTimeFormatOptions = custom ? options : {};
+      if (!custom && parts.hasDate) Object.assign(defaults, { year: "numeric", month: "2-digit", day: "2-digit" });
+      if (!custom && parts.hasTime) Object.assign(defaults, { hour: "2-digit", minute: "2-digit", second: "2-digit" });
+      // Values without an offset are wall-clock times: show them as they are.
+      return new Intl.DateTimeFormat(locale, { ...defaults, timeZone: parts.offset !== null ? timeZone : "UTC" });
+    });
+    const time = wallClock(parts).getTime() - (parts.offset ?? 0) * 60_000;
+    return item.format(time);
+  };
+}
+
+/** Whether a column holds numbers. */
+export function isNumeric(column: Column) {
+  return column.type === "integer" || column.type === "bigint" || column.type === "decimal" || column.type === "float";
+}
+
+const TEMPORAL = new Set(["date", "time", "timestamp", "timestamptz"]);
+
+/**
+ * The text of values of a column by its format, or null where the format says nothing about a value (the grid then
+ * shows its text form, §2.4). Formats that Intl refuses (an unknown currency or time zone) give null for every value.
+ */
+export function formatterFor(
+  column: Column,
+  format: ColumnFormat | undefined,
+  locale: string | undefined,
+): ((value: JsonValue) => string | null) | null {
+  if (!format?.number && !format?.date) return null;
+  let number: ((value: number | string) => string) | null = null;
+  let date: ((parts: DateParts) => string) | null = null;
+  try {
+    if (format.number && isNumeric(column)) number = numberFormatter(locale, format.number, true);
+    if (format.date && TEMPORAL.has(column.type)) date = dateFormatter(locale, format.date);
+  } catch (error) {
+    if (error instanceof RangeError) return null;
+    throw error;
+  }
+  if (!number && !date) return null;
+  return (value) => {
+    if (value === null) return null;
+    if (number) {
+      const input = numberInput(value);
+      return input === null ? null : number(input);
+    }
+    if (date && typeof value === "string") {
+      const parts = parseDate(value.replace(/\+00$/, "Z"));
+      return parts ? date(parts) : null;
+    }
+    return null;
+  };
+}

package/src/core/measures.ts

@@ -0,0 +1,99 @@
+/**
+ * Measures over the rows of a view (§4.5 of the specification), for the column statistics and the totals row: both
+ * are an `aggregate` without keys over the plan's rows (Appendix A), read with `rows` like any view.
+ */
+import {
+  type Capabilities,
+  type Column,
+  checkPlan,
+  type DisplayedColumn,
+  type Measure,
+  type MeasureName,
+  measureTakes,
+  type Plan,
+  planOptions,
+} from "vastgrid-spec";
+import type { TableInfo } from "./types.js";
+
+/** The rows of a plan before grouping: its derived columns and `where`. Null when the plan groups rows. */
+function rowsPlan(plan: Plan): Plan | null {
+  if (plan.aggregate) return null;
+  return { ...(plan.derive ? { derive: plan.derive } : {}), ...(plan.where ? { where: plan.where } : {}) };
+}
+
+/** Whether the engine evaluates a measure (§4.10: absent `measures` are all of them). */
+export function offers(capabilities: Capabilities | undefined, fn: MeasureName): boolean {
+  if (capabilities?.plan?.aggregate === false) return false;
+  return capabilities?.measures?.includes(fn) ?? true;
+}
+
+/** A statistic of a column: what it is, and the measure that gives it. */
+export interface Statistic {
+  kind: "rows" | "values" | "distinct" | "min" | "max" | "sum" | "average" | "median" | "stddev";
+  measure: Measure;
+}
+
+const STATISTICS: [Statistic["kind"], MeasureName, number?][] = [
+  ["values", "count"],
+  ["distinct", "count_distinct"],
+  ["min", "min"],
+  ["max", "max"],
+  ["sum", "sum"],
+  ["average", "avg"],
+  ["median", "quantile", 0.5],
+  ["stddev", "stddev"],
+];
+
+/** The statistics of a column that the engine evaluates and that take its type, with the number of rows first. */
+export function statisticsOf(column: Column, capabilities: Capabilities | undefined): Statistic[] {
+  if (!offers(capabilities, "count")) return [];
+  const list: Statistic[] = [{ kind: "rows", measure: { name: "rows", fn: "count" } }];
+  for (const [kind, fn, p] of STATISTICS) {
+    if (!offers(capabilities, fn) || !measureTakes(fn, column)) continue;
+    list.push({ kind, measure: { name: kind, fn, column: column.name, ...(p === undefined ? {} : { p }) } });
+  }
+  return list;
+}
+
+/** The measures of the totals row (§5.1): one per displayed column with a total, named after the column. */
+export function totalMeasures(displayed: readonly DisplayedColumn[]): Measure[] {
+  return displayed.flatMap(({ column, setting }) =>
+    setting.total
+      ? [
+          {
+            name: column.name,
+            fn: setting.total.fn,
+            column: column.name,
+            ...(setting.total.p === undefined ? {} : { p: setting.total.p }),
+          },
+        ]
+      : [],
+  );
+}
+
+/** The plan of measures over the rows of a plan, or null when it groups rows. */
+export function measuresPlan(plan: Plan, measures: Measure[]): Plan | null {
+  const rows = rowsPlan(plan);
+  return rows && { ...rows, aggregate: { keys: [], measures } };
+}
+
+/** The measures that a total can be, for a column's type, in the order the menu offers them. */
+export const TOTALS: MeasureName[] = ["sum", "avg", "count", "count_distinct", "min", "max"];
+
+/** A measure's name as 0.1 wrote it, `sum(amount)` or `count(*)`, with ` (2)`, ` (3)`, … when it is taken. */
+export function measureName(fn: MeasureName, column: string | undefined, taken: ReadonlySet<string>): string {
+  const base = `${fn}(${column ?? "*"})`;
+  let name = base;
+  for (let n = 2; taken.has(name); n++) name = `${base} (${n})`;
+  return name;
+}
+
+/** The columns of the rows before grouping: the table's and the derived ones, or the table's when the plan fails. */
+export function rowColumns(plan: Plan | undefined, table: TableInfo): readonly Column[] {
+  try {
+    return checkPlan(rowsPlan({ ...plan, aggregate: undefined }) ?? {}, table.columns, planOptions(table.capabilities))
+      .rows;
+  } catch {
+    return table.columns;
+  }
+}

package/src/core/request-ids.ts

@@ -0,0 +1,54 @@
+/**
+ * Ids of requests (§8.1 of the specification) for several clients of one engine, such as the Apps and the grids of
+ * an MCP server or the webviews of an editor. Each client chooses ids of its own, which the engine would mix up (a `cancel` of one
+ * client's request would stop another's): the requests of each client get ids that are unique in the engine, and
+ * the answers get the client's ids back.
+ */
+
+type Json = Record<string, unknown>;
+
+/** What the clients share: the engine's `handle`, as `DuckDBEngine` has it. */
+export interface Handler {
+  handle(message: unknown, options?: { signal?: AbortSignal }): Promise<unknown>;
+}
+
+function isObject(value: unknown): value is Json {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isId(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+export class RequestIds {
+  private next = 1;
+
+  constructor(private readonly engine: Handler) {}
+
+  /** A client of the engine whose requests keep their ids apart from those of the others. */
+  client(): Handler {
+    // The engine's ids of this client's requests in flight, by the client's ids.
+    const running = new Map<number, number>();
+    return {
+      handle: async (message, options) => {
+        // A message without a valid id is the engine's to refuse, as it is (§8.1).
+        if (!isObject(message) || !isId(message.id)) return this.engine.handle(message, options);
+        const own = message.id;
+        const id = this.next++;
+        const sent: Json = { ...message, id };
+        if (message.op === "cancel" && isId(message.request)) {
+          // A request that is not running any more is cancelled under an id that no request has.
+          sent.request = running.get(message.request) ?? this.next++;
+        } else {
+          running.set(own, id);
+        }
+        try {
+          const answer = await this.engine.handle(sent, options);
+          return isObject(answer) && answer.id === id ? { ...answer, id: own } : answer;
+        } finally {
+          if (running.get(own) === id) running.delete(own);
+        }
+      },
+    };
+  }
+}

package/src/core/rows.ts

@@ -0,0 +1,213 @@
+import { type CheckedPlan, type Column, canonicalJson, decodeBlock, type Plan } from "vastgrid-spec";
+import { BLOCK_ROWS, type Read, type ViewCache } from "./cache.js";
+import type { GridClient } from "./client.js";
+import type { RowsResult, TableInfo, ViewInfo } from "./types.js";
+
+/** Where the canvas is: its first row, how many rows it shows and the columns it draws. */
+export interface Viewport {
+  top: number;
+  rows: number;
+  columns: readonly string[];
+}
+
+/** A view of the document's plan, being read or on screen. */
+export interface View {
+  readonly key: string;
+  readonly plan: Plan;
+  readonly checked: CheckedPlan;
+  /** The table's revision and edits version that the view's rows belong to. */
+  readonly revision: string | null;
+  readonly edits: number;
+  info: ViewInfo | null;
+  readonly cache: ViewCache;
+  readonly abort: AbortController;
+}
+
+/** Whether two lists of columns have the same names and types. */
+export function sameColumns(a: readonly Column[], b: readonly Column[]) {
+  return a.length === b.length && a.every((column, index) => canonicalJson(column) === canonicalJson(b[index]));
+}
+
+/** What a `RowReader` reads with: the views, the connection and the state of its store, and where rows go. */
+export interface ReadHost {
+  /** The view on screen. */
+  current(): View | null;
+  /** The view being made, which comes on screen once its first rows are read (§4.2 of react.md). */
+  next(): View | null;
+  client(): GridClient | null;
+  table(): TableInfo | null;
+  /** Whether the table is open for the current connection. */
+  opened(): boolean;
+  /** The document's row key column (§5.3). */
+  rowKey(): string | undefined;
+  /** Whether the session's active cell has the key of its row (§5.2). */
+  keyed(): boolean;
+  /** A read changed the info of the view on screen. */
+  showView(info: ViewInfo): void;
+  /** Rows of the view on screen arrived. */
+  showRows(): void;
+  /** A read of the view on screen or of the one being made failed. */
+  fail(error: unknown): void;
+}
+
+/**
+ * Reads the rows of a store's views into their caches (§4.1 of react.md): those on screen and a page around
+ * them, within a budget of bytes, and those that the store asks for. Rows that come for a view that is no longer
+ * on screen or being made are dropped.
+ */
+export class RowReader {
+  /** What the canvas shows, as `setViewport` was told last. */
+  viewport: Viewport = { top: 0, rows: 0, columns: [] };
+  private scheduled = false;
+
+  constructor(
+    private readonly host: ReadHost,
+    private readonly budget: number,
+  ) {}
+
+  /** Follows what the canvas shows, and reads those rows and a page around them. */
+  setViewport(viewport: Viewport) {
+    const before = this.viewport;
+    if (
+      before.top === viewport.top &&
+      before.rows === viewport.rows &&
+      before.columns.length === viewport.columns.length &&
+      before.columns.every((column, index) => column === viewport.columns[index])
+    ) {
+      return;
+    }
+    this.viewport = viewport;
+    this.schedule();
+  }
+
+  /** Reads rows `[start, end)` of `columns` of the view on screen if they are not read, for cells React renders. */
+  ensure(start: number, end: number, columns: readonly string[]) {
+    const view = this.host.current();
+    if (!view?.info || !this.host.opened() || this.host.next() || view.abort.signal.aborted) return;
+    for (const read of view.cache.reads(start, end, this.withKey(columns), view.info.rowCount)) {
+      void this.read(view, read).catch(() => {});
+    }
+  }
+
+  /** Reads the rows on screen once the current task is done, once for all the changes it makes. */
+  schedule() {
+    if (this.scheduled) return;
+    this.scheduled = true;
+    queueMicrotask(() => {
+      this.scheduled = false;
+      this.readVisible();
+    });
+  }
+
+  /** The rows from `row` for a viewport, in whole blocks. */
+  around(row: number, rowCount: number | null, columns: readonly string[]): Read {
+    const start = Math.floor(row / BLOCK_ROWS) * BLOCK_ROWS;
+    const rows = Math.max(this.viewport.rows, 1);
+    let end = Math.ceil((row + rows) / BLOCK_ROWS) * BLOCK_ROWS;
+    if (rowCount !== null) end = Math.min(end, Math.max(rowCount, start + 1));
+    return { start, end: Math.max(end, start + 1), columns: [...columns] };
+  }
+
+  /** The columns of a view to read: those asked for that it has and its row key column, at least one. */
+  withKeyFor(view: View, columns: readonly string[]): string[] {
+    const names = new Set(view.checked.columns.map((column) => column.name));
+    const wanted = columns.filter((column) => names.has(column));
+    const key = this.host.rowKey();
+    if (key !== undefined && names.has(key) && !wanted.includes(key)) wanted.push(key);
+    if (wanted.length === 0 && view.checked.columns.length > 0) wanted.push(view.checked.columns[0].name);
+    return wanted;
+  }
+
+  /** Reads the rows that a command needs (`not_loaded`, §6.1), in whole blocks. */
+  async load(view: View, details: { rows: [number, number][]; columns: string[] }) {
+    const rowCount = view.info?.rowCount ?? 0;
+    const columns = this.withKeyFor(view, details.columns);
+    const reads: Promise<void>[] = [];
+    for (const [start, end] of details.rows) {
+      const first = Math.floor(start / BLOCK_ROWS) * BLOCK_ROWS;
+      const last = Math.min(rowCount, Math.ceil(end / BLOCK_ROWS) * BLOCK_ROWS);
+      for (let at = first; at < last; at += BLOCK_ROWS * 16) {
+        reads.push(this.read(view, { start: at, end: Math.min(last, at + BLOCK_ROWS * 16), columns }));
+      }
+    }
+    await Promise.all(reads);
+  }
+
+  /** Reads rows of a view into its cache. */
+  async read(view: View, read: Read): Promise<void> {
+    const client = this.host.client();
+    const table = this.host.table();
+    if (!client || !table) return;
+    view.cache.reading(read, true);
+    try {
+      const result = await client.request<RowsResult>(
+        "rows",
+        {
+          table: table.table,
+          revision: view.revision,
+          plan: view.plan,
+          start: read.start,
+          end: read.end,
+          columns: read.columns,
+          // A keyed selection needs locate on the complete view before its position can change.
+          ...(!view.info && table.capabilities.preview && !this.host.keyed() ? { preview: true } : {}),
+        },
+        view.abort.signal,
+      );
+      if (view !== this.host.current() && view !== this.host.next()) return;
+      const block = decodeBlock(result.block.bytes);
+      view.cache.receive(
+        result.start,
+        result.rowIds,
+        block.columns.map((column) => column.name),
+        block.rows,
+        result.truncated,
+      );
+      const info = result.view;
+      view.cache.reading(read, false);
+      // A ready event can arrive before the response containing the preview.
+      if (
+        !(view.info?.status === "ready" && info.status === "building") &&
+        (!view.info ||
+          view.info.rowCount !== info.rowCount ||
+          view.info.status !== info.status ||
+          view.info.readableRows !== info.readableRows)
+      ) {
+        view.info =
+          view.info && sameColumns(view.info.columns, info.columns) ? { ...info, columns: view.info.columns } : info;
+        if (view === this.host.current()) this.host.showView(view.info);
+      }
+      if (view === this.host.current()) this.host.showRows();
+    } catch (error) {
+      view.cache.reading(read, false);
+      if (view === this.host.current() || view === this.host.next()) this.host.fail(error);
+      throw error;
+    }
+  }
+
+  /** The columns to read: those asked for, and the row key column (§5.3), which commands need. */
+  private withKey(columns: readonly string[]): string[] {
+    const key = this.host.rowKey();
+    const view = this.host.current()?.info?.columns ?? [];
+    if (key === undefined || columns.includes(key) || !view.some((column) => column.name === key)) {
+      return [...columns];
+    }
+    return [...columns, key];
+  }
+
+  private readVisible() {
+    const view = this.host.current();
+    if (!view?.info || !this.host.opened() || this.host.next() || view.abort.signal.aborted) return;
+    const { top, rows, columns } = this.viewport;
+    if (columns.length === 0) return;
+    const margin = Math.max(rows, 32);
+    const start = Math.max(0, top - margin);
+    const readable = view.info.status === "building" ? view.info.readableRows : view.info.rowCount;
+    const end = Math.min(readable, top + rows + margin);
+    view.cache.touch(top, top + rows);
+    for (const read of view.cache.reads(start, end, this.withKey(columns), readable)) {
+      void this.read(view, read).catch(() => {});
+    }
+    view.cache.evict(this.budget, start, end);
+  }
+}