vastgrid 0.1.1 → 0.2.0

package/src/core/totals.ts

@@ -0,0 +1,59 @@
+import { canonicalJson, type Plan } from "vastgrid-spec";
+import { measuresPlan, totalMeasures } from "./measures.js";
+import type { View } from "./rows.js";
+import type { GridSnapshot } from "./types.js";
+
+type Totals = NonNullable<GridSnapshot["totals"]>;
+
+/**
+ * The totals row of the view on screen (§5.1): read again when the view, its edits or the totals change, with
+ * `measure`, and shown with `show`; a read that fails goes to `fail`. The totals on screen stay until the new ones
+ * come.
+ */
+export class TotalsReader {
+  /** The revision, edits and plan of the totals read last; empty without them, null to read them again. */
+  private key: string | null = "";
+  private abort: AbortController | null = null;
+
+  constructor(
+    private readonly measure: (plan: Plan, revision: string | null, signal: AbortSignal) => Promise<Totals>,
+    private readonly show: (totals: Totals | null) => void,
+    private readonly fail: (error: unknown) => void,
+  ) {}
+
+  /** Stops the read in flight, and reads the totals row again at the next `follow`, as for a new connection. */
+  reset() {
+    this.key = null;
+    this.abort?.abort();
+    this.abort = null;
+  }
+
+  /** Reads the totals row again if the view on screen, its edits or the totals changed. */
+  follow(view: View | null, snapshot: GridSnapshot) {
+    const measures = totalMeasures(snapshot.displayed);
+    // A view that is being made is totalled once it is ready.
+    if (view && measures.length > 0 && snapshot.view?.status !== "ready") return;
+    const plan = view && measures.length > 0 ? measuresPlan(view.plan, measures) : null;
+    const key = view && plan ? `${view.revision}\u0000${view.edits}\u0000${canonicalJson(plan)}` : "";
+    if (key === this.key) return;
+    this.key = key;
+    this.abort?.abort();
+    this.abort = null;
+    if (!view || !plan) {
+      if (snapshot.totals) this.show(null);
+      return;
+    }
+    const abort = new AbortController();
+    this.abort = abort;
+    this.measure(plan, view.revision, abort.signal)
+      .then(
+        (totals) => {
+          if (!abort.signal.aborted) this.show(totals);
+        },
+        (error) => {
+          if (!abort.signal.aborted) this.fail(error);
+        },
+      )
+      .catch(() => {});
+  }
+}

package/src/core/trace.ts

@@ -0,0 +1,44 @@
+/**
+ * The grid's tracks in the Performance panel of Chrome's DevTools, next to React's (§9 of react.md):
+ * requests, commands and canvas frames, in development builds only. `console.timeStamp` costs little when
+ * nothing records.
+ */
+declare const process: { env: { NODE_ENV?: string } };
+
+/** Whether this is a development build: bundlers replace `process.env.NODE_ENV`, as they do for React. */
+function development(): boolean {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+}
+
+type Color = "primary" | "secondary" | "tertiary" | "error";
+
+const stamp =
+  typeof console !== "undefined" && typeof console.timeStamp === "function" && development()
+    ? (console.timeStamp as unknown as (
+        label: string,
+        start: number,
+        end: number,
+        track: string,
+        group: string,
+        color: Color,
+      ) => void)
+    : null;
+
+/** The time to give `track` as the start of an entry. */
+export function now(): number {
+  return typeof performance === "undefined" ? 0 : performance.now();
+}
+
+/** Adds an entry from `start` to now to one of the grid's tracks. */
+export function track(
+  label: string,
+  start: number,
+  lane: "requests" | "commands" | "canvas",
+  color: Color = "primary",
+) {
+  stamp?.(label, start, now(), lane, "vastgrid", color);
+}

package/src/core/transports.ts

@@ -0,0 +1,177 @@
+import { ARROW_MEDIA_TYPE, readAttached, toStructuredEncoding } from "vastgrid-spec";
+import type { Transport } from "./client.js";
+import type { RequestMessage } from "./types.js";
+
+/** An engine in the same thread: it answers request messages, and may send events (§8.5). */
+export interface Engine {
+  handle(message: unknown): Promise<unknown>;
+  subscribe?(listener: (event: unknown) => void): () => void;
+}
+
+/** Carries messages to an engine in the same thread, as function calls with blocks as bytes (§8.8). */
+export function localTransport(engine: Engine): Transport {
+  const transport: Transport = { send: (request) => engine.handle(request) };
+  if (engine.subscribe) {
+    const subscribe = engine.subscribe.bind(engine);
+    transport.subscribe = (listener) => subscribe(listener);
+  }
+  return transport;
+}
+
+/**
+ * The side of a worker that `workerTransport` talks to: `self` in a worker, a `MessagePort`, or anything that carries
+ * messages as they do (VS Code's webview, a notebook widget's messages).
+ */
+export interface WorkerLike {
+  postMessage(message: unknown, transfer?: Transferable[]): void;
+  addEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  removeEventListener(type: "message", listener: (event: MessageEvent) => void): void;
+  start?(): void;
+}
+
+/**
+ * Carries messages to an engine in a Web Worker (or behind a `MessagePort`), which answers with
+ * `serveEngine`. Blocks travel as bytes and their buffers are transferred (§8.8).
+ */
+export function workerTransport(worker: WorkerLike): Transport & { close(): void } {
+  const waiting = new Map<number, (response: unknown) => void>();
+  const listeners = new Set<(event: unknown) => void>();
+  const receive = (event: MessageEvent) => {
+    const data = event.data as { id?: unknown; event?: unknown } | null;
+    if (data === null || typeof data !== "object") return;
+    if (typeof data.event === "string") {
+      for (const listener of listeners) listener(data);
+      return;
+    }
+    if (typeof data.id !== "number") return;
+    const resolve = waiting.get(data.id);
+    waiting.delete(data.id);
+    resolve?.(data);
+  };
+  worker.addEventListener("message", receive);
+  worker.start?.();
+  return {
+    send(request: RequestMessage) {
+      if (request.op === "cancel") {
+        worker.postMessage(request);
+        return Promise.resolve(undefined);
+      }
+      return new Promise((resolve) => {
+        waiting.set(request.id, resolve);
+        worker.postMessage(request);
+      });
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    close() {
+      worker.removeEventListener("message", receive);
+      waiting.clear();
+      listeners.clear();
+    },
+  };
+}
+
+/** Answers the requests that `workerTransport` sends, in a worker (`serveEngine(engine, self)`). */
+export function serveEngine(engine: Engine, scope: WorkerLike): () => void {
+  const receive = (event: MessageEvent) => {
+    void engine.handle(event.data).then((response) => {
+      if (response === undefined) return;
+      const block = (response as { result?: { block?: { bytes?: unknown }; data?: { bytes?: unknown } } }).result;
+      const bytes = block?.block?.bytes ?? block?.data?.bytes;
+      scope.postMessage(response, bytes instanceof Uint8Array ? [bytes.buffer as ArrayBuffer] : []);
+    });
+  };
+  scope.addEventListener("message", receive);
+  scope.start?.();
+  const stop = engine.subscribe?.((event) => scope.postMessage(event));
+  return () => {
+    scope.removeEventListener("message", receive);
+    stop?.();
+  };
+}
+
+export interface HttpTransportOptions {
+  /** `fetch`, by default the global one. */
+  fetch?: typeof fetch;
+  /** Headers sent with every request, such as an authorization. */
+  headers?: Record<string, string>;
+  /** A URL of Server-Sent Events that carries the engine's events (§8.8). */
+  events?: string;
+  /** The URL under which exports without a target are downloaded; `<url>/exports/` by default. */
+  exports?: string;
+}
+
+/**
+ * Carries messages over HTTP (§8.8): each request is a `POST` of its JSON, and the answers of `rows` and `export`
+ * come with their blocks attached. Aborting a request aborts its HTTP request.
+ */
+export function httpTransport(url: string, options: HttpTransportOptions = {}): Transport {
+  const request = options.fetch ?? ((...args: Parameters<typeof fetch>) => fetch(...args));
+  const exports = options.exports ?? `${url.replace(/\/+$/, "")}/exports/`;
+  // While the event stream connects, requests wait: an engine sends each event to the streams open at the time, so
+  // a table opened before would finish loading without the client hearing it.
+  let connecting: Promise<void> | null = null;
+  const transport: Transport = {
+    cancels: "signal",
+    exportUrl: (target) => `${exports}${encodeURIComponent(target)}`,
+    async send(message, { signal }) {
+      if (connecting) await connecting;
+      const response = await request(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: `${ARROW_MEDIA_TYPE}, application/json`,
+          ...options.headers,
+        },
+        body: JSON.stringify(message),
+        signal,
+      });
+      const type = response.headers.get("content-type") ?? "";
+      if (type.startsWith(ARROW_MEDIA_TYPE)) return readAttached(new Uint8Array(await response.arrayBuffer()));
+      return toStructuredEncoding((await response.json()) as Record<string, unknown>);
+    },
+  };
+  const events = options.events;
+  if (events !== undefined) {
+    transport.subscribe = (listener) => {
+      const source = new EventSource(events);
+      let open = () => {};
+      const opening = new Promise<void>((resolve) => {
+        open = resolve;
+      });
+      connecting = opening;
+      // Open, or failed: a stream that cannot connect does not hold the requests back.
+      const settle = () => {
+        open();
+        if (connecting === opening) connecting = null;
+      };
+      source.onopen = settle;
+      source.onerror = settle;
+      source.onmessage = (event) => {
+        try {
+          listener(JSON.parse(event.data as string));
+        } catch {
+          // An event that is not JSON is not an event of §8.5.
+        }
+      };
+      return () => {
+        settle();
+        source.close();
+      };
+    };
+  }
+  return transport;
+}
+
+/**
+ * Carries messages through a Server Function (`"use server"`), which passes each to an engine on the server and
+ * returns its answer (§7 of react.md). The function receives what any client may send: it checks every
+ * request with `checkRequest`, as engines do.
+ */
+export function serverFunctionTransport(action: (request: RequestMessage) => Promise<unknown>): Transport {
+  return { send: (request) => action(request) };
+}

package/src/core/types.ts

@@ -0,0 +1,168 @@
+import type {
+  Capabilities,
+  Column,
+  CommandError,
+  DisplayedColumn,
+  ErrorCode,
+  GridDocument,
+  GridSession,
+  JsonValue,
+  Operation,
+  Plan,
+  RowKey,
+} from "vastgrid-spec";
+
+/** The table's edits version and the number of cells written so far (§8.2 of the specification). */
+export interface Edits {
+  version: number;
+  cells: number;
+}
+
+/** What `open` and `info` give (§8.2). */
+export interface TableInfo {
+  /** The engine's id of the open table, for later requests. */
+  table: string;
+  revision: string | null;
+  edits: Edits;
+  status: "loading" | "ready" | "error";
+  progress: number | null;
+  /** Null while the table loads. */
+  rowCount: number | null;
+  readableRows: number;
+  columns: Column[];
+  capabilities: Capabilities;
+  format?: string;
+  byteSize?: number;
+  notes?: string[];
+  sheets?: { name: string; hidden?: boolean }[];
+  sheet?: string;
+  error?: string;
+  /** The file changed on disk since the table, which has written cells, was read (§7.6); `reload` reads it again. */
+  fileChanged?: boolean;
+}
+
+/** A view as `rows` reports it (§8.2, §9). */
+export interface ViewInfo {
+  hash: string;
+  status: "building" | "ready";
+  rowCount: number;
+  rowCountExact: boolean;
+  readableRows: number;
+  columns: Column[];
+  edits: Edits;
+  partial?: boolean;
+}
+
+/** The result of `rows` (§8.2), with its block in the structured encoding. */
+export interface RowsResult {
+  view: ViewInfo;
+  start: number;
+  end: number;
+  rowIds: number[] | null;
+  block: { bytes: Uint8Array };
+  truncated?: Record<string, number[]>;
+}
+
+/** The `read` options of `open` (§8.2). */
+export interface OpenOptions {
+  sheet?: string;
+  headerRow?: number;
+  keepEmptyRows?: boolean;
+  keepEmptyColumns?: boolean;
+}
+
+/** A request (§8.1). */
+export interface RequestMessage {
+  v: 2;
+  id: number;
+  op: Operation;
+  [member: string]: unknown;
+}
+
+/**
+ * Rows read on a server for the first render (§7 of react.md): the table, the plan they were read for, and
+ * the answer of `rows`. A store given them shows these rows before it reads any.
+ */
+export interface InitialView {
+  table: TableInfo;
+  plan: Plan;
+  rows: RowsResult;
+}
+
+/** A failed request (§8.7), or a response that does not follow §8 (`internal`). */
+export class GridError extends Error {
+  readonly code: ErrorCode;
+  readonly reason?: string;
+  readonly path?: string;
+  readonly details?: Record<string, unknown>;
+  /** The operation of the request that failed. */
+  readonly op?: Operation;
+
+  constructor(
+    code: ErrorCode,
+    message: string,
+    extra: { reason?: string; path?: string; details?: Record<string, unknown>; op?: Operation } = {},
+  ) {
+    super(message);
+    this.name = "GridError";
+    this.code = code;
+    if (extra.reason !== undefined) this.reason = extra.reason;
+    if (extra.path !== undefined) this.path = extra.path;
+    if (extra.details !== undefined) this.details = extra.details;
+    if (extra.op !== undefined) this.op = extra.op;
+  }
+}
+
+/** What a dispatched command came to: its output, or why it failed (§4.2 of react.md). */
+export type CommandOutcome = { ok: true; output?: unknown } | { ok: false; error: CommandError | GridError };
+
+/** One update of a `write` request (§7.2 of the specification). */
+export interface WriteUpdate {
+  readonly key: RowKey;
+  readonly column: string;
+  readonly value: JsonValue;
+  readonly previous?: JsonValue;
+}
+
+/**
+ * The last write that failed (§6.6 of react.md), which `retryWrite` sends again and `discardWrite` forgets.
+ * `retry` tells how it can be sent again: the same write (`"retry"`), after an `edit_conflict` without the
+ * `previous` values (`"overwrite"`), or not at all (null): the table has another revision now, or the engine
+ * refused the values or the cells.
+ */
+export interface FailedWrite {
+  /** The command whose write it was. */
+  readonly command: string;
+  readonly updates: readonly WriteUpdate[];
+  readonly revision: string | null;
+  readonly rowKey?: string | readonly string[];
+  readonly error: GridError;
+  readonly retry: "retry" | "overwrite" | null;
+}
+
+/** What the grid shows. A snapshot is never changed: the store makes a new one for every change. */
+export interface GridSnapshot {
+  readonly document: GridDocument;
+  readonly session: GridSession;
+  /** Null until the table is open. */
+  readonly table: TableInfo | null;
+  /** The view on screen; null until its first rows are read. */
+  readonly view: ViewInfo | null;
+  /** The displayed columns of the view on screen (§5.1.1), in display order. */
+  readonly displayed: readonly DisplayedColumn[];
+  /** A plan whose view is being read to replace the one on screen. */
+  readonly pending: { readonly plan: Plan } | null;
+  readonly status: "idle" | "opening" | "ready" | "error";
+  /** The last failure that belongs to no command. */
+  readonly error: GridError | null;
+  /** The last write that failed, until it is sent again or discarded. */
+  readonly failedWrite: FailedWrite | null;
+  /**
+   * The totals row (§5.1): the total of each displayed column that has one, over the whole view on screen, with
+   * the types of the values; null without totals, or for a view that groups rows.
+   */
+  readonly totals: {
+    readonly values: Readonly<Record<string, JsonValue>>;
+    readonly columns: Readonly<Record<string, Column>>;
+  } | null;
+}

package/src/core.ts

@@ -0,0 +1,39 @@
+/**
+ * The grid without React (§4 of react.md): the store, the client of the messages and the transports. Runs in
+ * browsers, workers and servers.
+ */
+export { BLOCK_ROWS } from "./core/cache.js";
+export { GridClient, type Transport } from "./core/client.js";
+export { type Handler, RequestIds } from "./core/request-ids.js";
+export type { Viewport } from "./core/rows.js";
+export {
+  CACHE_BYTES,
+  createGridStore,
+  type DispatchOptions,
+  GridStore,
+  type GridStoreOptions,
+} from "./core/store.js";
+export {
+  type Engine,
+  type HttpTransportOptions,
+  httpTransport,
+  localTransport,
+  serveEngine,
+  serverFunctionTransport,
+  type WorkerLike,
+  workerTransport,
+} from "./core/transports.js";
+export {
+  type CommandOutcome,
+  type Edits,
+  type FailedWrite,
+  GridError,
+  type GridSnapshot,
+  type InitialView,
+  type OpenOptions,
+  type RequestMessage,
+  type RowsResult,
+  type TableInfo,
+  type ViewInfo,
+  type WriteUpdate,
+} from "./core/types.js";

package/src/index.ts

@@ -1,13 +1,25 @@
-export * from "vastgrid-core";
+"use client";
+
+export type { CommandName, CommandOutputs, GridCommand, GridDocument, GridSession } from "vastgrid-spec";
+export type { Geometry, Hit } from "./canvas/geometry.js";
+export { GridCanvas, type Settled } from "./canvas/grid-canvas.js";
+export type { CellAction, CellHooks, CellStyle, ColumnGroup, DrawCellArgs, GridCell } from "./canvas/hooks.js";
+export { isApple, type KeyInput, keyCommand } from "./canvas/keys.js";
+/**
+ * vastgrid 0.2 for React (react.md): `DataGrid`, the hooks that read and change its store, and what the store
+ * and the transports give (also in `vastgrid/core`, without React).
+ */
+export * from "./core.js";
+export { DataGrid, type DataGridHandle, type DataGridProps, GridProvider } from "./react/data-grid.js";
+export type { DetailPanelProps } from "./react/detail-panel.js";
+export type { CellActionEvent } from "./react/grid-body.js";
 export {
-  type ColumnState,
-  CopyTooLargeError,
-  GridController,
-  type GridOptions,
-  type Hit,
-  type HitZone,
-} from "./controller.js";
-export { DataGrid, type DataGridHandle, type DataGridProps } from "./data-grid.js";
-export { en, ja, type Messages, messagesFor } from "./messages.js";
-export { CanvasRenderer } from "./renderer.js";
-export { type GridTheme, resolveTheme } from "./theme.js";
+  readRows,
+  shallowEqual,
+  useCreateGridStore,
+  useGridDispatch,
+  useGridRows,
+  useGridSelector,
+  useGridStore,
+} from "./react/hooks.js";
+export { type GridMessages, messagesFor } from "./react/messages.js";