vastgrid 0.1.0 → 0.2.0

package/dist/core/store.js

@@ -0,0 +1,1162 @@
+import { applyCommand, CommandError, canonicalJson, checkPlan, decodeBlock, displayedColumns, emptyDocument, emptySession, keyText, normalizePlan, PlanError, planOptions, repairDocument } from "vastgrid-spec";
+import { ViewCache } from "./cache.js";
+import { GridClient } from "./client.js";
+import { valuesPlan } from "./filters.js";
+import { measuresPlan } from "./measures.js";
+import { RowReader, sameColumns } from "./rows.js";
+import { TotalsReader } from "./totals.js";
+import { now, track } from "./trace.js";
+import { GridError } from "./types.js";
+
+/** Bytes of rows that a store keeps for the view on screen, by default. */
+export const CACHE_BYTES = 64 * 1024 * 1024;
+
+/** Failures of a write that the same write may not meet when it is sent again. */
+const RETRIED = new Set(["internal", "cancelled", "not_ready", "table_not_found"]);
+
+/** A command applied, or why it was not. */
+
+function isCancelled(error) {
+  return error instanceof GridError && error.code === "cancelled";
+}
+function asGridError(error) {
+  if (error instanceof GridError) return error;
+  if (error instanceof PlanError) {
+    return new GridError("invalid_plan", error.message, {
+      reason: error.reason,
+      path: error.path
+    });
+  }
+  return new GridError("internal", error instanceof Error ? error.message : String(error));
+}
+function planKey(plan) {
+  return canonicalJson(normalizePlan(plan));
+}
+
+/**
+ * The grid without a screen (§4 of react.md): the state of the specification as immutable snapshots, the
+ * commands that change it, and the rows of the view on screen, read through a transport. Making a store has
+ * no side effects; `connect` opens the table and starts reading.
+ */
+export class GridStore {
+  listeners = new Set();
+  rowListeners = new Set();
+  events = {
+    document: new Set(),
+    session: new Set(),
+    error: new Set()
+  };
+  controlled = {
+    document: false,
+    session: false
+  };
+  /** What a command made of a controlled part, until the host passes it back (§5.2 of react.md). */
+  proposed = {};
+  client = null;
+  /** Counts connections, so that answers to an earlier one are dropped. */
+  connection = 0;
+  /** Whether the table is open for the current connection. */
+  opened = false;
+  current = null;
+  next = null;
+  /**
+   * Values of writes (§7.2) that the rows read do not hold yet, by the key text of their row and by column, with
+   * the write that gave them: the grid shows them at once, and drops them when the write fails or once the view
+   * of its edits version is on screen.
+   */
+  written = new Map();
+  writes = 0;
+  /** The edits version that each write that succeeded made. */
+  writeVersions = new Map();
+  /** Settles once the writes sent so far are answered and their steps are in the history. */
+  writing = Promise.resolve();
+  totals = new TotalsReader((plan, revision, signal) => this.measure(plan, revision, signal), totals => this.publish({
+    totals
+  }), error => this.readFailed(error));
+  rowsVersion = 0;
+  constructor(options) {
+    this.options = options;
+    this.reader = new RowReader({
+      current: () => this.current,
+      next: () => this.next,
+      client: () => this.client,
+      table: () => this.snapshot.table,
+      opened: () => this.opened,
+      rowKey: () => this.base("document").rowKey,
+      keyed: () => Boolean(this.base("session").active?.key),
+      showView: info => this.publish({
+        view: info
+      }),
+      showRows: () => this.emitRows(),
+      fail: error => this.readFailed(error)
+    }, options.cacheBytes ?? CACHE_BYTES);
+    this.snapshot = {
+      document: options.document ?? emptyDocument(),
+      session: options.session ?? emptySession(),
+      table: null,
+      view: null,
+      displayed: [],
+      pending: null,
+      status: "idle",
+      error: null,
+      failedWrite: null,
+      totals: null
+    };
+    if (options.initial) this.seed(options.initial);
+  }
+
+  // ----- reading the state -----
+
+  getSnapshot = () => this.snapshot;
+  subscribe = listener => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** Follows changes of the document or the session (reported also when they are controlled), and errors. */
+  on(event, listener) {
+    const set = this.events[event];
+    set.add(listener);
+    return () => {
+      set.delete(listener);
+    };
+  }
+  emit(event, value) {
+    for (const listener of this.events[event]) listener(value);
+  }
+  publish(changes) {
+    const previous = this.snapshot;
+    const next = {
+      ...previous,
+      ...changes
+    };
+    if (next.view && previous.view && sameColumns(next.view.columns, previous.view.columns)) {
+      // Views read again keep their columns' identity, which displayed columns and commands key on.
+      if (next.view.columns !== previous.view.columns) next.view = {
+        ...next.view,
+        columns: previous.view.columns
+      };
+    }
+    const keep = next.document.columns === previous.document.columns && next.view?.columns === previous.view?.columns;
+    next.displayed = keep ? previous.displayed : this.displayedOf(next);
+    this.snapshot = next;
+    for (const listener of this.listeners) listener();
+    // The totals are read once the table is open, which rows read on a server come before.
+    if (this.opened) this.totals.follow(this.current, this.snapshot);
+  }
+
+  /** Reads the one row of a plan that aggregates without keys: its values and their types, by column name. */
+  async measure(plan, revision, signal) {
+    const table = this.snapshot.table;
+    const client = this.client;
+    if (!table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    const names = plan.aggregate?.measures.map(measure => measure.name) ?? [];
+    const result = await client.request("rows", {
+      table: table.table,
+      revision,
+      plan,
+      start: 0,
+      end: 1,
+      columns: names
+    }, signal);
+    const block = decodeBlock(result.block.bytes);
+    const values = {};
+    const columns = {};
+    block.columns.forEach((column, index) => {
+      values[column.name] = block.rows[0]?.[index] ?? null;
+      columns[column.name] = column;
+    });
+    return {
+      values,
+      columns
+    };
+  }
+
+  /**
+   * Measures (§4.5) over the rows of the document's plan, for the column statistics: an `aggregate` without keys
+   * (`measuresPlan`). Fails for a plan that groups rows.
+   */
+  async aggregate(measures, signal) {
+    const plan = measuresPlan(this.base("document").plan ?? {}, measures);
+    if (!plan) throw new GridError("invalid_plan", "The measures of a grouped view are not read.");
+    return this.measure(plan, this.current?.revision ?? this.snapshot.table?.revision ?? null, signal);
+  }
+  displayedOf(snapshot) {
+    return snapshot.view ? displayedColumns(snapshot.document, snapshot.view.columns) : [];
+  }
+
+  /** The state that commands apply to: what was proposed for controlled parts, or what is shown. */
+  base(part) {
+    return this.proposed[part] ?? this.snapshot[part];
+  }
+
+  // ----- rows -----
+
+  /** The value of a cell of the view on screen; undefined while it is not read. */
+  cell(row, column) {
+    const view = this.current;
+    const value = view?.cache.value(row, column);
+    if (!view || this.written.size === 0) return value;
+    const key = view.cache.loaded(row, this.base("document").rowKey)?.key;
+    const entry = key === undefined ? undefined : this.written.get(keyText(key))?.get(column);
+    return entry === undefined ? value : entry.value;
+  }
+
+  /** Whether the engine cut a cell's value to the text limit (§8.4). */
+  isCut(row, column) {
+    return this.current?.cache.isCut(row, column) ?? false;
+  }
+
+  /** The key of a row of the view on screen (§5.3); undefined while it is not read. */
+  rowKey(row) {
+    return this.current?.cache.loaded(row, this.base("document").rowKey)?.key;
+  }
+
+  /** The row ID of a row of the view on screen. */
+  rowId(row) {
+    return this.current?.cache.rowId(row);
+  }
+
+  /** Changes whenever rows of the view on screen arrive or leave. */
+  getRowsVersion = () => this.rowsVersion;
+
+  /** Follows the arrival of rows (the snapshot does not change when rows arrive). */
+  subscribeRows = listener => {
+    this.rowListeners.add(listener);
+    return () => {
+      this.rowListeners.delete(listener);
+    };
+  };
+  emitRows() {
+    this.rowsVersion++;
+    for (const listener of this.rowListeners) listener();
+  }
+
+  /** Tells the store what the canvas shows, so that it reads those rows and a page around them. */
+  setViewport(viewport) {
+    this.reader.setViewport(viewport);
+  }
+
+  /** Reads rows `[start, end)` of `columns` of the view on screen if they are not read, for cells React renders. */
+  ensure(start, end, columns) {
+    this.reader.ensure(start, end, columns);
+  }
+
+  // ----- connecting -----
+
+  /**
+   * Opens the table, follows its events and reads the view of the document's plan. Gives the function that
+   * undoes all of it; connecting again afterwards works (Strict Mode does it, §4.3 of react.md).
+   */
+  connect() {
+    const connection = ++this.connection;
+    const client = new GridClient(this.options.transport);
+    this.client = client;
+    this.opened = false;
+    let connected = true;
+    // Events can arrive before the open response names the table (HTTP's streams are independent). Replay
+    // them against that response, so an early ready event cannot leave plans waiting for loading forever.
+    let openingEvents = [];
+    const stopEvents = client.subscribe(event => {
+      if (!connected || connection !== this.connection) return;
+      if (openingEvents) openingEvents.push(event);else this.onEvent(event, connection);
+    });
+    if (this.snapshot.status === "idle" || this.snapshot.status === "error") this.publish({
+      status: "opening"
+    });
+    let tableId = null;
+    const close = id => void client.request("close", {
+      table: id
+    }).catch(() => {});
+    void (async () => {
+      try {
+        // Not cancelled: an engine may open the table all the same, which is then closed.
+        const info = await client.request("open", {
+          ref: this.options.table,
+          ...(this.options.open ? {
+            read: this.options.open
+          } : {})
+        });
+        if (!connected) {
+          close(info.table);
+          return;
+        }
+        tableId = info.table;
+        this.opened = true;
+        this.opening(info);
+        const events = openingEvents;
+        openingEvents = null;
+        for (const event of events ?? []) this.onEvent(event, connection);
+      } catch (error) {
+        openingEvents = null;
+        if (connected && !isCancelled(error)) {
+          this.publish({
+            status: "error"
+          });
+          this.fail(asGridError(error));
+        }
+      }
+    })();
+    return () => {
+      if (!connected) return;
+      connected = false;
+      openingEvents = null;
+      stopEvents();
+      if (tableId !== null) close(tableId);
+      if (connection !== this.connection) return;
+      this.connection++;
+      this.opened = false;
+      this.current?.abort.abort();
+      this.next?.abort.abort();
+      this.next = null;
+      this.totals.reset();
+      if (this.current) this.current = {
+        ...this.current,
+        abort: new AbortController()
+      };
+      this.client = null;
+    };
+  }
+
+  /** The table is open: repairs the document for it and reads the view (§5.5). */
+  opening(info) {
+    const document = this.base("document");
+    const repaired = repairDocument(document, info.columns, planOptions(info.capabilities));
+    const seeded = this.current;
+    // Rows read on a server stay when they belong to the same revision and plan.
+    if (seeded && (seeded.revision !== info.revision || seeded.edits !== info.edits.version)) this.current = null;else if (seeded) this.current = {
+      ...seeded,
+      abort: new AbortController()
+    };
+    this.publish({
+      table: info,
+      status: info.status === "error" ? "error" : "ready"
+    });
+    if (repaired.removed.length > 0) this.change(repaired.document, this.base("session"));
+    this.showPlan(this.base("document").plan ?? {});
+    this.reader.schedule();
+  }
+  onEvent(event, connection) {
+    if (connection !== this.connection) return;
+    const table = this.snapshot.table;
+    if (!table || event.table !== table.table) return;
+    if (event.event === "changed") {
+      const revision = event.revision;
+      const edits = event.edits;
+      const fileChanged = event.fileChanged === true;
+      if (revision === table.revision) {
+        if (edits.version === table.edits.version && fileChanged === (table.fileChanged === true)) return;
+        const {
+          fileChanged: _,
+          ...rest
+        } = table;
+        this.publish({
+          table: fileChanged ? {
+            ...rest,
+            edits,
+            fileChanged
+          } : {
+            ...rest,
+            edits
+          }
+        });
+        this.showPlan(this.base("document").plan ?? {});
+        return;
+      }
+      // Another revision may have other columns: the table is read again, then the view (§5.4).
+      const client = this.client;
+      void client?.request("info", {
+        table: table.table
+      }).then(info => {
+        if (connection === this.connection) this.adopt(info);
+      }).catch(error => {
+        if (connection === this.connection && !isCancelled(error)) this.fail(asGridError(error));
+      });
+    } else if (event.event === "progress") {
+      this.publish({
+        table: {
+          ...table,
+          status: event.status,
+          progress: event.progress,
+          readableRows: event.readableRows,
+          rowCount: event.rowCount
+        }
+      });
+      if (event.status === "ready") this.showPlan(this.base("document").plan ?? {});
+      // A view still being made reads its rows again once the table is read, also without `view` events (§9).
+      const view = this.current;
+      if (event.status === "ready" && view?.info && view.info.status !== "ready") {
+        const columns = this.reader.withKeyFor(view, this.reader.viewport.columns);
+        void this.reader.read(view, this.reader.around(this.reader.viewport.top, null, columns)).then(() => this.reader.schedule(), () => {});
+      }
+    } else if (event.event === "view") {
+      const view = [this.next, this.current].find(item => item?.info?.hash === event.hash && item?.revision === table.revision);
+      if (view?.info) {
+        view.info = {
+          ...view.info,
+          status: event.status,
+          readableRows: event.readableRows,
+          rowCount: event.rowCount,
+          rowCountExact: event.rowCountExact
+        };
+        if (view === this.current) this.publish({
+          view: view.info
+        });
+        this.reader.schedule();
+      }
+    }
+  }
+  fail(error) {
+    this.publish({
+      error
+    });
+    this.emit("error", error);
+  }
+
+  /** A read failed: unless it was cancelled, the failure belongs to no command (§4.2 of react.md). */
+  readFailed(error) {
+    if (!isCancelled(error)) this.fail(asGridError(error));
+  }
+
+  /** Shows rows read on a server before the table is open. */
+  seed(initial) {
+    const {
+      table,
+      plan,
+      rows
+    } = initial;
+    if (planKey(plan) !== planKey(this.snapshot.document.plan ?? {})) return;
+    try {
+      const view = {
+        key: planKey(plan),
+        plan,
+        checked: checkPlan(plan, table.columns, planOptions(table.capabilities)),
+        revision: table.revision,
+        edits: rows.view.edits.version,
+        info: rows.view,
+        cache: new ViewCache(),
+        abort: new AbortController()
+      };
+      const block = decodeBlock(rows.block.bytes);
+      view.cache.receive(rows.start, rows.rowIds, block.columns.map(column => column.name), block.rows, rows.truncated);
+      this.current = view;
+      this.snapshot = {
+        ...this.snapshot,
+        table,
+        view: rows.view
+      };
+      this.snapshot = {
+        ...this.snapshot,
+        displayed: this.displayedOf(this.snapshot)
+      };
+    } catch (error) {
+      if (!(error instanceof PlanError)) throw error;
+    }
+  }
+
+  // ----- views -----
+
+  /**
+   * Reads the view of a plan while the view on screen stays, and shows it when its first rows arrive, with the
+   * session moved by `view.update` (§5.4; §4.2 of react.md).
+   */
+  showPlan(plan) {
+    const table = this.snapshot.table;
+    if (!table || !this.client || !this.opened) return;
+    const key = planKey(plan);
+    if (table.status === "loading" && !table.capabilities.partialViews && key !== planKey({})) {
+      this.next?.abort.abort();
+      this.next = null;
+      this.publish({
+        pending: {
+          plan
+        }
+      });
+      return;
+    }
+    const fresh = view => view !== null && !view.abort.signal.aborted && view.key === key && view.revision === table.revision && view.edits === table.edits.version;
+    if (this.next && !fresh(this.next)) {
+      this.next.abort.abort();
+      this.next = null;
+    }
+    if (fresh(this.current)) {
+      if (this.snapshot.pending) this.publish({
+        pending: null
+      });
+      return;
+    }
+    if (this.next) return;
+    if (this.current?.info?.status === "building") this.current.abort.abort();
+    let checked;
+    try {
+      checked = checkPlan(plan, table.columns, planOptions(table.capabilities));
+    } catch (error) {
+      if (!(error instanceof PlanError)) throw error;
+      if (this.snapshot.pending) this.publish({
+        pending: null
+      });
+      this.fail(asGridError(error));
+      return;
+    }
+    const view = {
+      key,
+      plan,
+      checked,
+      revision: table.revision,
+      edits: table.edits.version,
+      info: null,
+      cache: new ViewCache(),
+      abort: new AbortController()
+    };
+    this.next = view;
+    if (this.current) this.publish({
+      pending: {
+        plan
+      }
+    });
+    void this.prepare(view, this.connection);
+  }
+  live(view, connection) {
+    return connection === this.connection && view === this.next;
+  }
+  async prepare(view, connection) {
+    const table = this.snapshot.table;
+    const client = this.client;
+    const columns = this.reader.withKeyFor(view, this.reader.viewport.columns);
+    try {
+      const top = this.current ? this.reader.viewport.top : this.base("session").scroll?.row ?? 0;
+      await this.reader.read(view, this.reader.around(top, null, columns));
+      if (!this.live(view, connection) || !view.info) return;
+      let info = view.info;
+      if (top >= info.rowCount && info.rowCount > 0) {
+        await this.reader.read(view, this.reader.around(info.rowCount - 1, info.rowCount, columns));
+        if (!this.live(view, connection) || !view.info) return;
+        info = view.info;
+      }
+      // The session as it is now: the person may have moved while the rows were read.
+      const session = this.base("session");
+      const document = this.base("document");
+      const key = session.active?.key;
+      const located = [];
+      if (key && session.view !== info.hash && table.capabilities.locate) {
+        const result = await client.request("locate", {
+          table: table.table,
+          revision: view.revision,
+          plan: view.plan,
+          keys: [key],
+          ...(document.rowKey === undefined ? {} : {
+            rowKey: document.rowKey
+          })
+        }, view.abort.signal);
+        if (!this.live(view, connection)) return;
+        located.push({
+          key,
+          row: result.rows[0] ?? null
+        });
+      }
+      const state = {
+        document: this.base("document"),
+        session: this.base("session")
+      };
+      const updated = applyCommand(state, {
+        command: "view.update",
+        hash: info.hash,
+        located
+      }, this.contextFor(view, table, info));
+      const scroll = updated.session.scroll;
+      const target = scroll && scroll !== state.session.scroll ? scroll.row : Math.min(top, info.rowCount - 1);
+      if (info.status === "ready" && target >= 0 && view.cache.value(target, columns[0] ?? "") === undefined && columns.length > 0) {
+        await this.reader.read(view, this.reader.around(target, info.rowCount, columns));
+        if (!this.live(view, connection)) return;
+      }
+      const previous = this.current;
+      previous?.abort.abort();
+      this.current = view;
+      this.next = null;
+      // The rows, the view and the session's new positions are shown in one step.
+      // A view that comes on screen ends the failure of the one before (a pivot with too many columns).
+      this.change(updated.document, updated.session, {
+        view: view.info ?? info,
+        pending: null,
+        error: null
+      });
+      // The snapshot keeps the columns of the view before when they are the same, for commands to key on.
+      view.info = this.snapshot.view;
+      // Values of writes that the new rows hold are no longer needed.
+      this.dropWritten(write => (this.writeVersions.get(write) ?? Number.POSITIVE_INFINITY) <= view.edits);
+      this.emitRows();
+      this.reader.schedule();
+      // A normal read waits for completion, also when there is no event channel or the ready event raced
+      // the preview. It reports a failed build and is cancelled when the plan or connection changes.
+      if (view.info?.status === "building" && table.status === "ready") {
+        void this.reader.read(view, this.reader.around(Math.max(0, target), null, columns)).then(() => this.reader.schedule(), () => {});
+      }
+    } catch (error) {
+      if (view === this.next) {
+        this.next = null;
+        if (this.snapshot.pending) this.publish({
+          pending: null
+        });
+      }
+      if (connection === this.connection && !isCancelled(error)) this.fail(asGridError(error));
+    }
+  }
+  contextFor(view, table, info = view.info) {
+    const rowKey = this.base("document").rowKey;
+    return {
+      table: table.columns,
+      revision: view.revision,
+      view: {
+        columns: info?.columns ?? view.checked.columns,
+        rowCount: info?.rowCount ?? 0,
+        rowIds: view.checked.rowIds
+      },
+      lookup: row => this.withWritten(view.cache.loaded(row, rowKey)),
+      page: Math.max(1, this.reader.viewport.rows - 1),
+      capabilities: table.capabilities
+    };
+  }
+
+  // ----- changing the state -----
+
+  /** A row as commands read it, with the values of writes that its rows do not hold yet. */
+  withWritten(row) {
+    if (!row?.key || this.written.size === 0) return row;
+    const values = this.written.get(keyText(row.key));
+    if (!values) return row;
+    return {
+      key: row.key,
+      has: column => values.has(column) || row.has(column),
+      get: column => {
+        const entry = values.get(column);
+        return entry === undefined ? row.get(column) : entry.value;
+      }
+    };
+  }
+
+  /** Shows the values of a write until it is answered (§7.2). */
+  markWritten(write, updates) {
+    for (const update of updates) {
+      const text = keyText(update.key);
+      let values = this.written.get(text);
+      if (!values) {
+        values = new Map();
+        this.written.set(text, values);
+      }
+      values.set(update.column, {
+        value: update.value,
+        write
+      });
+    }
+    this.emitRows();
+  }
+
+  /** Forgets the values of writes: one that failed, or those that the rows on screen now hold. */
+  dropWritten(done) {
+    let dropped = false;
+    for (const [text, values] of this.written) {
+      for (const [column, entry] of values) {
+        if (!done(entry.write)) continue;
+        values.delete(column);
+        dropped = true;
+      }
+      if (values.size === 0) this.written.delete(text);
+    }
+    if (dropped) this.emitRows();
+  }
+
+  /** Makes a part controlled: commands report what they make of it, and only `setDocument`/`setSession` show it. */
+  control(part, controlled) {
+    this.controlled[part] = controlled;
+    if (!controlled) delete this.proposed[part];
+  }
+
+  /** Shows a document given by the host (a controlled prop, a saved view, an agent). */
+  setDocument(document) {
+    delete this.proposed.document;
+    const previous = this.snapshot.document;
+    if (document === previous) return;
+    this.publish({
+      document
+    });
+    if (document.plan !== previous.plan) this.showPlan(document.plan ?? {});
+    this.reader.schedule();
+  }
+
+  /** Shows a session given by the host. */
+  setSession(session) {
+    delete this.proposed.session;
+    if (session === this.snapshot.session) return;
+    this.publish({
+      session
+    });
+  }
+
+  /**
+   * Applies a new state from a command: shows what is not controlled, with `extra` members of the snapshot in the
+   * same step, and reports both parts that changed.
+   */
+  change(document, session, extra = {}) {
+    const shown = {
+      ...extra
+    };
+    const previous = this.snapshot.document;
+    const reports = [];
+    if (document !== this.base("document")) {
+      if (this.controlled.document) this.proposed.document = document;else shown.document = document;
+      reports.push(["document", document]);
+    }
+    if (session !== this.base("session")) {
+      if (this.controlled.session) this.proposed.session = session;else shown.session = session;
+      reports.push(["session", session]);
+    }
+    if (Object.keys(shown).length > 0) this.publish(shown);
+    for (const [part, value] of reports) {
+      if (part === "document") this.emit("document", value);else this.emit("session", value);
+    }
+    if (shown.document && shown.document.plan !== previous.plan) this.showPlan(shown.document.plan ?? {});
+  }
+
+  /** Applies a command now, or tells why it cannot be applied (rows to read first included). */
+  applyNow(command, options) {
+    const view = this.current;
+    const table = this.snapshot.table;
+    if (!view?.info || !table) {
+      return {
+        kind: "failed",
+        error: new GridError("not_ready", "The table is not open yet."),
+        view: null
+      };
+    }
+    const context = this.contextFor(view, table);
+    if (options.clipboard) context.clipboard = options.clipboard;
+    const started = now();
+    try {
+      const result = applyCommand({
+        document: this.base("document"),
+        session: this.base("session")
+      }, command, context);
+      track(command.command, started, "commands");
+      this.change(result.document, result.session);
+      return {
+        kind: "applied",
+        result,
+        table
+      };
+    } catch (error) {
+      if (!(error instanceof CommandError)) throw error;
+      track(command.command, started, "commands", "error");
+      return {
+        kind: "failed",
+        error,
+        view
+      };
+    }
+  }
+
+  /**
+   * Applies a command (§4.2 of react.md). The state changes at once when the command has what it needs;
+   * a command that needs rows that are not read reads them first. Resolves once the command's requests are
+   * answered, and never rejects. The same function for the life of the store.
+   */
+  dispatch = async (command, options = {}) => {
+    // The state never shares objects with a command that its caller may change later.
+    const given = structuredClone(command);
+    // An undo or a redo takes the last step once the writes sent before it are in the history.
+    if (given.command === "history.undo" || given.command === "history.redo") await this.writing;
+    let applied = this.applyNow(given, options);
+    for (let tries = 0; tries < 3 && applied.kind === "failed" && applied.view && applied.error instanceof CommandError && applied.error.reason === "not_loaded" && applied.error.details; tries++) {
+      const view = applied.view;
+      try {
+        await this.reader.load(view, applied.error.details);
+      } catch (failure) {
+        // A view that another replaced while its rows were read (a write, or the file read again) is cancelled:
+        // the command applies to the new one.
+        if (!isCancelled(failure) || view === this.current) return {
+          ok: false,
+          error: asGridError(failure)
+        };
+      }
+      applied = this.applyNow(given, options);
+    }
+    if (applied.kind === "failed") return {
+      ok: false,
+      error: applied.error
+    };
+    try {
+      const output = await this.send(given.command, applied.result.requests, applied.table);
+      const value = output ?? applied.result.output;
+      return value === undefined ? {
+        ok: true
+      } : {
+        ok: true,
+        output: value
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: asGridError(error)
+      };
+    }
+  };
+
+  /**
+   * Applies a command synchronously, as a `copy` event needs (its clipboard is written before the handler
+   * returns). A command that needs rows that are not read fails with `not_loaded`; its requests are sent.
+   */
+  dispatchSync(command, options = {}) {
+    const given = structuredClone(command);
+    const applied = this.applyNow(given, options);
+    if (applied.kind === "failed") return {
+      ok: false,
+      error: applied.error
+    };
+    if (applied.result.requests.length > 0) {
+      void this.send(given.command, applied.result.requests, applied.table).catch(error => {
+        this.fail(asGridError(error));
+      });
+    }
+    return applied.result.output === undefined ? {
+      ok: true
+    } : {
+      ok: true,
+      output: applied.result.output
+    };
+  }
+
+  /**
+   * Sends the failed write again (§6.6 of react.md): the same updates, or after an `edit_conflict` without their
+   * `previous`, so that they write over what the cells hold now. It succeeds as its command would have: the history
+   * gets its step, or an undo or a redo whose step is still the last moves it. Resolves as `dispatch` does.
+   */
+  retryWrite = async () => {
+    const failed = this.snapshot.failedWrite;
+    const table = this.snapshot.table;
+    if (!failed) return {
+      ok: false,
+      error: new GridError("invalid_request", "No write failed.")
+    };
+    if (failed.retry === null || !table || table.revision !== failed.revision) {
+      return {
+        ok: false,
+        error: new GridError("revision_changed", "The write cannot be sent again.")
+      };
+    }
+    this.publish({
+      failedWrite: null
+    });
+    const request = {
+      op: "write",
+      revision: failed.revision,
+      updates: failed.updates
+    };
+    if (failed.rowKey !== undefined) request.rowKey = failed.rowKey;
+    const command = this.stillLast(failed) ? failed.command : "write";
+    try {
+      await this.send(command, [request], table, failed.retry === "overwrite");
+      return {
+        ok: true
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        error: asGridError(error)
+      };
+    }
+  };
+
+  /** Forgets the failed write: its cells show what the engine holds. */
+  discardWrite() {
+    if (this.snapshot.failedWrite) this.publish({
+      failedWrite: null
+    });
+  }
+
+  /** Keeps a write that failed, for `retryWrite` and `discardWrite`. */
+  failWrite(command, request, error) {
+    const failed = {
+      command,
+      updates: request.updates,
+      revision: request.revision ?? null,
+      ...(request.rowKey === undefined ? {} : {
+        rowKey: request.rowKey
+      }),
+      error,
+      retry: error.code === "edit_conflict" ? "overwrite" : RETRIED.has(error.code) ? "retry" : null
+    };
+    this.publish({
+      failedWrite: failed
+    });
+  }
+
+  /** Whether a failed undo or redo has its step still last in its list, where its write then moves it from. */
+  stillLast(failed) {
+    const list = failed.command === "history.undo" ? "undo" : failed.command === "history.redo" ? "redo" : null;
+    if (!list) return true;
+    const step = this.base("session").history?.[list].at(-1);
+    if (!step) return false;
+    const written = step.updates.map(update => ({
+      key: update.key,
+      column: update.column,
+      value: list === "undo" ? update.before : update.after,
+      previous: list === "undo" ? update.after : update.before
+    }));
+    const sent = failed.updates.map(({
+      key,
+      column,
+      value,
+      previous
+    }) => ({
+      key,
+      column,
+      value,
+      previous
+    }));
+    return canonicalJson(written) === canonicalJson(sent);
+  }
+
+  /** Where the file of an `export` without a target can be downloaded (`Transport.exportUrl`), or null. */
+  exportUrl(target) {
+    return this.options.transport.exportUrl?.(target) ?? null;
+  }
+
+  /** A name for the file of an export that an engine answers as data: the table's name with the format's extension. */
+  exportName(format) {
+    const name = this.options.table.split(/[\\/]/).pop() ?? "";
+    const base = name.replace(/(\.(gz|zst))?$/i, "").replace(/\.[^.]*$/, "") || "export";
+    return `${base}.${format}`;
+  }
+
+  /**
+   * Reads the table's file as it is now (`reload`, §7.6), without the cells written into the table as it was read:
+   * for a file that changed on disk while the table had written cells (`fileChanged` of the table).
+   */
+  async reload() {
+    const table = this.snapshot.table;
+    const client = this.client;
+    const connection = this.connection;
+    if (!table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    const info = await client.request("reload", {
+      table: table.table
+    });
+    if (connection === this.connection) this.adopt(info);
+  }
+
+  /** Another revision of the table (§5.4): the document is repaired for its columns (§5.5), and the view read. */
+  adopt(info) {
+    const current = this.snapshot.table;
+    if (current && current.revision === info.revision && current.edits.version === info.edits.version && current.fileChanged === info.fileChanged && current.status === info.status) {
+      return;
+    }
+    const repaired = repairDocument(this.base("document"), info.columns, planOptions(info.capabilities));
+    this.publish({
+      table: info,
+      status: info.status === "error" ? "error" : "ready"
+    });
+    if (repaired.removed.length > 0) this.change(repaired.document, this.base("session"));
+    this.showPlan(this.base("document").plan ?? {});
+    this.reader.schedule();
+  }
+
+  /** Counts and sums the cells of ranges of the view on screen (`summarize`, §8.2). */
+  async summarize(ranges, columns, signal) {
+    const view = this.current;
+    const table = this.snapshot.table;
+    const client = this.client;
+    if (!view || !table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    return client.request("summarize", {
+      table: table.table,
+      revision: view.revision,
+      plan: view.plan,
+      ranges,
+      columns
+    }, signal);
+  }
+
+  /**
+   * The values of a column with how many rows have each, the most common first, for the column menu's list: the
+   * rows of the document's plan without the column's own conditions, and those whose text contains `search`
+   * (`valuesPlan`). At most `limit` of them; `truncated` when there are more.
+   */
+  async values(column, {
+    search = "",
+    limit = 1_000
+  } = {}, signal) {
+    const table = this.snapshot.table;
+    const client = this.client;
+    if (!table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    const made = valuesPlan(this.base("document").plan ?? {}, column, search);
+    if (!made) throw new GridError("invalid_plan", "The values of a grouped view are not listed.");
+    const result = await client.request("rows", {
+      table: table.table,
+      revision: this.current?.revision ?? table.revision,
+      plan: made.plan,
+      start: 0,
+      end: limit + 1,
+      columns: [column, made.count]
+    }, signal);
+    const rows = decodeBlock(result.block.bytes).rows;
+    return {
+      values: rows.slice(0, limit).map(([value, count]) => ({
+        value,
+        count: Number(count)
+      })),
+      truncated: rows.length > limit
+    };
+  }
+
+  /**
+   * Finds the next cell of the view on screen after `from` (before it with `direction` −1) whose text contains
+   * `text` (`find`, §8.2), among the displayed columns in display order, wrapping around; null when none does.
+   */
+  async find(text, {
+    from,
+    direction = 1,
+    caseSensitive = false
+  }, signal) {
+    const view = this.current;
+    const table = this.snapshot.table;
+    const client = this.client;
+    if (!view || !table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    const columns = this.snapshot.displayed.map(item => item.column.name);
+    const column = Math.max(0, columns.indexOf(from.column));
+    const found = await client.request("find", {
+      table: table.table,
+      revision: view.revision,
+      plan: view.plan,
+      text,
+      columns,
+      from: {
+        row: from.row,
+        column
+      },
+      direction,
+      ...(caseSensitive ? {
+        caseSensitive: true
+      } : {})
+    }, signal);
+    return found ? {
+      row: found.row,
+      column: columns[found.column]
+    } : null;
+  }
+
+  /** The whole value of a cell of the view on screen, also when the engine cut its text (§8.4), and its type. */
+  async fullValue(row, column, signal) {
+    const view = this.current;
+    const table = this.snapshot.table;
+    const client = this.client;
+    if (!view || !table || !client || !this.opened) throw new GridError("not_ready", "The table is not open yet.");
+    const result = await client.request("rows", {
+      table: table.table,
+      revision: view.revision,
+      plan: view.plan,
+      start: row,
+      end: row + 1,
+      columns: [column],
+      textLimit: 1_000_000
+    }, signal);
+    const block = decodeBlock(result.block.bytes);
+    return {
+      value: block.rows[0]?.[0] ?? null,
+      column: block.columns[0]
+    };
+  }
+
+  /** Sends the requests of a command and applies the commands of §6.7 that their answers call for. */
+  async send(name, requests, table, overwrite = false) {
+    if (!requests.some(request => request.op === "write")) return this.sendNow(name, requests, table, overwrite);
+    let done = () => {};
+    const finished = new Promise(resolve => {
+      done = resolve;
+    });
+    this.writing = this.writing.then(() => finished);
+    try {
+      return await this.sendNow(name, requests, table, overwrite);
+    } finally {
+      done();
+    }
+  }
+  async sendNow(name, requests, table, overwrite) {
+    const client = this.client;
+    let output;
+    for (const request of requests) {
+      if (!client) throw new GridError("not_ready", "The grid is not connected.");
+      const {
+        op,
+        ...members
+      } = request;
+      const updates = op === "write" ? members.updates : [];
+      const write = op === "write" ? ++this.writes : 0;
+      if (write) this.markWritten(write, updates);
+      // An overwrite checks no `previous`; the history keeps them all the same, as the values the person wrote over.
+      const sent = overwrite ? {
+        ...members,
+        updates: updates.map(({
+          previous: _,
+          ...update
+        }) => update)
+      } : members;
+      let result;
+      try {
+        result = await client.request(op, {
+          table: table.table,
+          ...sent
+        });
+      } catch (error) {
+        if (write) {
+          this.dropWritten(other => other === write);
+          if (client === this.client) this.failWrite(name, request, asGridError(error));
+        }
+        throw error;
+      }
+      if (op === "write") {
+        const core = name === "history.undo" ? {
+          command: "history.undone"
+        } : name === "history.redo" ? {
+          command: "history.redone"
+        } : {
+          command: "history.push",
+          updates: updates.map(update => ({
+            key: update.key,
+            column: update.column,
+            before: update.previous ?? null,
+            after: update.value
+          }))
+        };
+        const state = {
+          document: this.base("document"),
+          session: this.base("session")
+        };
+        const view = this.current;
+        if (view) {
+          const applied = applyCommand(state, core, this.contextFor(view, table));
+          this.change(applied.document, applied.session);
+        }
+        const edits = result.edits;
+        this.writeVersions.set(write, edits.version);
+        // The engine's event may have brought the view of this version on screen before the answer came.
+        if (this.current && this.current.edits >= edits.version) this.dropWritten(other => other === write);
+        const current = this.snapshot.table;
+        if (current) this.publish({
+          table: {
+            ...current,
+            edits
+          }
+        });
+        this.showPlan(this.base("document").plan ?? {});
+      } else {
+        output = result;
+      }
+    }
+    return output;
+  }
+}
+
+/** Makes a store (§4 of react.md). */
+export function createGridStore(options) {
+  return new GridStore(options);
+}
+//# sourceMappingURL=store.js.map