@synnaxlabs/client 0.56.2 → 0.57.0

package/src/table/actions.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { NO_OP_RESULT as NO_OP, snapshotDraft as snapshot } from "@/actions/actions";
+import { actions } from "@/actions";
 import {
   type Action,
   addCol,
@@ -23,16 +23,14 @@ import {
 } from "@/table/actions.gen";
 import { type Cell } from "@/table/types.gen";
 
-// MIN_CELL_DIM is the floor enforced on row and column sizes.
 const MIN_CELL_DIM = 32;
 // BASE_ROW_DIM and BASE_COL_DIM are the defaults used when an action
 // bootstraps the opposing axis on an empty table.
 const BASE_ROW_DIM = 36;
 const BASE_COL_DIM = 72;
 
-// deriveCellKey returns the key for the index-th replica of template. Both
-// reducers run the same scheme so optimistic client state agrees with the
-// server.
+// deriveCellKey returns the key for the index-th replica of template. Both reducers run
+// the same scheme so optimistic client state agrees with the server.
 const deriveCellKey = (templateKey: string, index: number): string => {
   const suffix = index.toString(16).padStart(4, "0");
   if (templateKey.length < 36) return `${templateKey}-${suffix}`;
@@ -49,6 +47,11 @@ const expandTemplate = (template: Cell, count: number): Cell[] =>
   }));
 
 const handlers: Handlers = {
+  create: (state, payload) => {
+    Object.assign(state, payload.table);
+    return { inverse: [], targets: [payload.table.key] };
+  },
+
   rename: (state, payload) => {
     const oldName = state.name;
     state.name = payload.name;
@@ -83,12 +86,12 @@ const handlers: Handlers = {
   },
 
   removeRow: (state, payload) => {
-    if (payload.index >= state.rows.length) return NO_OP;
-    const removed = snapshot(state.rows[payload.index]);
+    if (payload.index >= state.rows.length) return actions.NO_OP_RESULT;
+    const removed = actions.snapshotDraft(state.rows[payload.index]);
     const cells: Cell[] = [];
     for (const k of removed.cells) {
       const c = state.cells[k];
-      if (c != null) cells.push(snapshot(c));
+      if (c != null) cells.push(actions.snapshotDraft(c));
     }
     state.rows.splice(payload.index, 1);
     for (const k of removed.cells) delete state.cells[k];
@@ -123,7 +126,7 @@ const handlers: Handlers = {
   },
 
   removeCol: (state, payload) => {
-    if (payload.index >= state.columns.length) return NO_OP;
+    if (payload.index >= state.columns.length) return actions.NO_OP_RESULT;
     const oldSize = state.columns[payload.index].size;
     const removedCells: Cell[] = [];
     state.columns.splice(payload.index, 1);
@@ -134,7 +137,7 @@ const handlers: Handlers = {
       if (payload.index >= state.rows[i].cells.length) continue;
       const k = state.rows[i].cells[payload.index];
       const c = state.cells[k];
-      if (c != null) removedCells.push(snapshot(c));
+      if (c != null) removedCells.push(actions.snapshotDraft(c));
       delete state.cells[k];
       state.rows[i].cells.splice(payload.index, 1);
     }
@@ -145,7 +148,7 @@ const handlers: Handlers = {
   },
 
   resizeRow: (state, payload) => {
-    if (payload.index >= state.rows.length) return NO_OP;
+    if (payload.index >= state.rows.length) return actions.NO_OP_RESULT;
     const oldSize = state.rows[payload.index].size;
     state.rows[payload.index].size = Math.max(payload.size, MIN_CELL_DIM);
     return {
@@ -155,7 +158,7 @@ const handlers: Handlers = {
   },
 
   resizeCol: (state, payload) => {
-    if (payload.index >= state.columns.length) return NO_OP;
+    if (payload.index >= state.columns.length) return actions.NO_OP_RESULT;
     const oldSize = state.columns[payload.index].size;
     state.columns[payload.index].size = Math.max(payload.size, MIN_CELL_DIM);
     const targets = state.rows
@@ -169,8 +172,8 @@ const handlers: Handlers = {
 
   setCell: (state, payload) => {
     const existing = state.cells[payload.cell.key];
-    if (existing == null) return NO_OP;
-    const oldCell = snapshot(existing);
+    if (existing == null) return actions.NO_OP_RESULT;
+    const oldCell = actions.snapshotDraft(existing);
     state.cells[payload.cell.key] = payload.cell;
     return {
       inverse: [setCell({ cell: oldCell })],
@@ -179,7 +182,7 @@ const handlers: Handlers = {
   },
 
   eraseCells: (state, payload) => {
-    if (payload.cells.length === 0) return NO_OP;
+    if (payload.cells.length === 0) return actions.NO_OP_RESULT;
     const selected = new Set(payload.cells);
     const rowPosOf = new Map<string, { row: number; col: number }>();
     for (let r = 0; r < state.rows.length; r++) {
@@ -209,11 +212,11 @@ const handlers: Handlers = {
     // unshift the inverse so undo replays it in ascending order.
     for (let i = fullRowIdx.length - 1; i >= 0; i--) {
       const idx = fullRowIdx[i];
-      const removed = snapshot(state.rows[idx]);
+      const removed = actions.snapshotDraft(state.rows[idx]);
       const cells: Cell[] = [];
       for (const k of removed.cells) {
         const c = state.cells[k];
-        if (c != null) cells.push(snapshot(c));
+        if (c != null) cells.push(actions.snapshotDraft(c));
       }
       state.rows.splice(idx, 1);
       for (const k of removed.cells) delete state.cells[k];
@@ -229,7 +232,7 @@ const handlers: Handlers = {
         if (idx >= state.rows[r].cells.length) continue;
         const k = state.rows[r].cells[idx];
         const c = state.cells[k];
-        if (c != null) removedCells.push(snapshot(c));
+        if (c != null) removedCells.push(actions.snapshotDraft(c));
         delete state.cells[k];
         state.rows[r].cells.splice(idx, 1);
       }
@@ -239,7 +242,7 @@ const handlers: Handlers = {
     for (const k of selected) {
       const existing = state.cells[k];
       if (existing == null) continue;
-      const oldCell = snapshot(existing);
+      const oldCell = actions.snapshotDraft(existing);
       state.cells[k] = {
         key: k,
         variant: payload.template.variant,
@@ -253,3 +256,25 @@ const handlers: Handlers = {
 };
 
 export const reduceAll = createReduceAll(handlers);
+
+// createOf hands the dispatch controller the document carried by a create
+// action so frames for never-cached documents ingest instead of drop.
+export const createOf = (action: Action) =>
+  action.type === "create" ? action.create.table : undefined;
+
+// kindOf classifies an action batch for the undoable store's per-kind coalesce window.
+// Continuous resize gestures (a stream of resize_row or resize_col actions) collapse
+// into a single undo step; successive set_cell actions on the same cell coalesce
+// per-cell so typing inside one cell collapses to one undo step but switching cells
+// starts a fresh entry; everything else is treated as a discrete user action.
+export const kindOf = (actions: Action[]): string => {
+  if (actions.length === 0) return "default";
+  if (actions.every((a) => a.type === "resize_row" || a.type === "resize_col"))
+    return "resize";
+  if (actions.length === 1) {
+    const a = actions[0];
+    if (a.type === "set_cell") return `set_cell:${a.setCell.cell.key}`;
+    return a.type;
+  }
+  return "transaction";
+};

package/src/table/client.ts

@@ -8,73 +8,225 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import { array, type destructor, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { type Action, dispatchReqZ } from "@/table/actions.gen";
-import { type Key, keyZ, type New, newZ, type Table, tableZ } from "@/table/types.gen";
-import { checkForMultipleOrNoResults } from "@/util/retrieve";
-import { workspace } from "@/workspace";
+import { actions } from "@/actions";
+import { type ontology } from "@/ontology";
+import { project } from "@/project";
+import { query } from "@/query";
+import { createOf, kindOf, reduceAll } from "@/table/actions";
+import {
+  type Action,
+  dispatchReqZ,
+  rename as renameAction,
+  scopedActionZ,
+} from "@/table/actions.gen";
+import {
+  type Key,
+  keyZ,
+  type New,
+  ontologyID,
+  type Table,
+  tableZ,
+} from "@/table/types.gen";
 
 export const SET_CHANNEL_NAME = "sy_table_set";
+export const DELETE_CHANNEL_NAME = "sy_table_delete";
 
-const renameReqZ = z.object({ key: keyZ, name: z.string() });
-
-const setDataBodyZ = tableZ.omit({ key: true, name: true });
-export type SetDataBody = z.input<typeof setDataBodyZ>;
-const setDataReqZ = z.object({ key: keyZ, data: setDataBodyZ });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 
-const retrieveReqZ = z.object({ keys: keyZ.array() });
-const singleRetrieveArgsZ = z
+const retrieveReqZ = z.object({
+  keys: keyZ.array(),
+  ignoreNotFoundError: z.boolean().optional(),
+});
+const retrieveMultiParamsZ = retrieveReqZ.or(query.keyListZ(keyZ));
+const singleRetrieveParamsZ = z
   .object({ key: keyZ })
   .transform(({ key }) => ({ keys: [key] }));
 
-export const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveReqZ]);
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
-export type RetrieveSingleParams = z.input<typeof singleRetrieveArgsZ>;
+export const retrieveParamsZ = z.union([singleRetrieveParamsZ, retrieveReqZ]);
+export type RetrieveParams = z.input<typeof retrieveParamsZ>;
+export type RetrieveSingleParams = z.input<typeof singleRetrieveParamsZ>;
 export type RetrieveMultipleParams = z.input<typeof retrieveReqZ>;
 
-const retrieveResZ = z.object({ tables: array.nullishToEmpty(tableZ) });
+interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
+
+const retrieveResZ = z.object({ tables: tableZ.array().default(() => []) });
 
-const createReqZ = z.object({ workspace: workspace.keyZ, tables: newZ.array() });
+const createReqZ = z.object({ project: project.keyZ, tables: tableZ.array() });
 const createResZ = z.object({ tables: tableZ.array() });
 
 const emptyResZ = z.object({});
 
-export class Client {
-  private readonly client: UnaryClient;
+/**
+ * Client-side matching for a request: exact for the requested key set, the
+ * only field a request carries.
+ */
+const requestFilter = (req: RetrieveRequest): ((t: Table) => boolean) => {
+  const keySet = new Set(req.keys);
+  return (t) => keySet.has(t.key);
+};
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  cache: query.Cache;
+  ontology: ontology.Client;
+}
+
+export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Table> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, Table>;
+  private readonly dispatcher: actions.Controller<Key, Table, Action>;
 
-  constructor(client: UnaryClient) {
-    this.client = client;
+  constructor(cfg: ClientConfig) {
+    const { cache } = cfg;
+    // Dispatch mutates documents server-side, so fetched copies never clobber
+    // a doc holding locally replayed edits: the table hydrates if-absent.
+    const store = cache.createTable<Key, Table>({
+      name: "tables",
+      hydrate: "if-absent",
+      fetch: async (keys) =>
+        await this.execRetrieve({ keys, ignoreNotFoundError: true }),
+      listen: [query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ)],
+    });
+    const dispatcher = new actions.Controller<Key, Table, Action>({
+      store,
+      onError: cache.onError,
+      reduce: reduceAll,
+      kindOf,
+      createOf,
+    });
+    cache.listen(dispatcher.listener(SET_CHANNEL_NAME, scopedActionZ));
+    super(cache, {
+      name: "table",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.execRetrieve(req),
+        matches: (table, req) => requestFilter(req)(table),
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
+    this.dispatcher = dispatcher;
   }
 
-  async create(workspace: workspace.Key, table: New): Promise<Table>;
-  async create(workspace: workspace.Key, tables: New[]): Promise<Table[]>;
   async create(
-    workspace: workspace.Key,
+    project: project.Key,
+    table: New,
+    opts?: query.WriteOptions<Table[]>,
+  ): Promise<Table>;
+  async create(
+    project: project.Key,
+    tables: New[],
+    opts?: query.WriteOptions<Table[]>,
+  ): Promise<Table[]>;
+  async create(
+    project: project.Key,
     tables: New | New[],
+    opts: query.WriteOptions<Table[]> = {},
   ): Promise<Table | Table[]> {
     const isMany = Array.isArray(tables);
-    const res = await this.client.send(
-      "/table/create",
-      { workspace, tables: array.toArray(tables) },
-      createReqZ,
-      createResZ,
-    );
+    const optimistic = array
+      .toArray(tables)
+      .map((t) => zod.parse(tableZ, t, { label: "table" }));
+    const res = await query.optimistic({
+      rollbacks: [this.store.set(optimistic)],
+      onOptimistic: () => opts.onOptimistic?.(optimistic),
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/table/create",
+          { project, tables: optimistic },
+          createReqZ,
+          createResZ,
+        ),
+    });
+    this.store.set(res.tables);
     return isMany ? res.tables : res.tables[0];
   }
 
-  async rename(key: Key, name: string): Promise<void> {
-    await this.client.send("/table/rename", { key, name }, renameReqZ, emptyResZ);
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const rename = () => [
+      query.partialUpdate(this.store, key, { name }),
+      this.cfg.ontology.cache.renameResource(ontologyID(key), name),
+    ];
+    await query.optimistic({
+      rollbacks: rename(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () => await this.sendDispatch(key, "", [renameAction({ name })]),
+    });
+    rename();
+  }
+
+  /**
+   * Applies actions to the cached table and sends them to the server, recording an
+   * undoable entry. Returns false without side effects when the table isn't cached.
+   * Rolls back the local apply and rethrows on send failure.
+   */
+  async dispatch(
+    key: Key,
+    actions: Action | Action[],
+    opts: actions.Options<Table, Action> = {},
+  ): Promise<boolean> {
+    return await this.dispatcher.dispatch(
+      key,
+      array.toArray(actions),
+      this.dispatchSender(key),
+      opts,
+    );
+  }
+
+  /**
+   * Reverts the table's most recent undoable entry. Returns false when
+   * nothing is undoable.
+   */
+  async undo(key: Key): Promise<boolean> {
+    return await this.dispatcher.undo(key, this.dispatchSender(key));
+  }
+
+  /**
+   * Re-applies the table's most recently undone entry. Returns false when
+   * nothing is redoable.
+   */
+  async redo(key: Key): Promise<boolean> {
+    return await this.dispatcher.redo(key, this.dispatchSender(key));
+  }
+
+  /** Whether the table has a live undo entry. */
+  hasUndo(key: Key): boolean {
+    return this.dispatcher.hasUndo(key);
+  }
+
+  /** Whether the table has a live redo entry. */
+  hasRedo(key: Key): boolean {
+    return this.dispatcher.hasRedo(key);
+  }
+
+  /**
+   * Subscribes to changes in the table's undo/redo stacks. Returns a
+   * destructor that unsubscribes.
+   */
+  onUndoStateChange(callback: () => void, key?: Key): destructor.Destructor {
+    return this.dispatcher.onUndoStateChange(callback, key);
+  }
+
+  /** Stages actions committed atomically as one undoable entry. */
+  beginTransaction(key: Key, kind?: string): actions.Transaction<Action> {
+    return this.dispatcher.transaction(key, this.dispatchSender(key), kind);
   }
 
-  async setData(key: Key, data: SetDataBody): Promise<void> {
-    await this.client.send("/table/set-data", { key, data }, setDataReqZ, emptyResZ);
+  private dispatchSender(key: Key): actions.SendDispatch<Action> {
+    return async (actions, dispatchKey) =>
+      await this.sendDispatch(key, dispatchKey, actions);
   }
 
-  async dispatch(key: Key, dispatchKey: string, actions: Action[]): Promise<void> {
-    await this.client.send(
+  private async sendDispatch(
+    key: Key,
+    dispatchKey: string,
+    actions: Action[],
+  ): Promise<void> {
+    await this.cfg.unary.send(
       "/table/dispatch",
       { key, dispatchKey, actions },
       dispatchReqZ,
@@ -82,28 +234,40 @@ export class Client {
     );
   }
 
-  async retrieve(args: RetrieveSingleParams): Promise<Table>;
-  async retrieve(args: RetrieveMultipleParams): Promise<Table[]>;
-  async retrieve(
-    args: RetrieveSingleParams | RetrieveMultipleParams,
-  ): Promise<Table | Table[]> {
-    const isSingle = singleRetrieveArgsZ.safeParse(args).success;
-    const res = await this.client.send(
-      "/table/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResZ,
-    );
-    checkForMultipleOrNoResults("Table", args, res.tables, isSingle);
-    return isSingle ? res.tables[0] : res.tables;
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => [
+      this.cfg.ontology.cache.deleteRelationships(ontologyID(keysArr)),
+      this.store.delete(keysArr),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/table/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/table/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      emptyResZ,
+  /** Subscribes to every table delete delivered to the cache. */
+  onDelete(handler: (key: Key) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "delete") handler(event.key);
+    });
+  }
+
+  private async execRetrieve(params: RetrieveMultipleParams): Promise<Table[]> {
+    const res = await this.cfg.unary.send(
+      "/table/retrieve",
+      params,
+      retrieveReqZ,
+      retrieveResZ,
     );
+    return res.tables;
   }
 }

package/src/table/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, caseconv, record } from "@synnaxlabs/x";
+import { caseconv, record, uuid } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
@@ -20,17 +20,15 @@ export const cellZ = z.object({
   key: z.string(),
   /**
    * variant is the cell variant identifier (e.g. "text", "value"). The variant
-   * determines the shape of props and which Pluto cell component renders
-   * the cell.
+   * determines the shape of props and which Pluto cell component renders the cell.
    */
   variant: z.string(),
   /**
-   * props is the variant-specific cell configuration. The shape is determined
-   * by the variant; the wire format intentionally stores it as an
-   * opaque record so new variants can be added without a schema
-   * migration.
+   * props is the variant-specific cell configuration. The shape is determined by the
+   * variant; the wire format intentionally stores it as an opaque record so new
+   * variants can be added without a schema migration.
    */
-  props: caseconv.preserveCase(record.nullishToEmpty()),
+  props: caseconv.preserveCase(record.unknownZ().default(() => ({}))),
 });
 export interface Cell extends z.infer<typeof cellZ> {}
 
@@ -39,10 +37,13 @@ export const rowZ = z.object({
   /** size is the height of the row in pixels. */
   size: z.number(),
   /**
-   * cells is the ordered list of cell keys in this row from left to right.
-   * Each key points at an entry in the table's cells map.
+   * cells is the ordered list of cell keys in this row from left to right. Each key
+   * points at an entry in the table's cells map.
    */
-  cells: array.nullishToEmpty(z.string()),
+  cells: z
+    .string()
+    .array()
+    .default(() => []),
 });
 export interface Row extends z.infer<typeof rowZ> {}
 
@@ -60,36 +61,28 @@ export const cellTemplateZ = cellZ.omit({ key: true });
 export interface CellTemplate extends z.infer<typeof cellTemplateZ> {}
 
 /**
- * Table is a tabular data display component for viewing structured telemetry
- * data. Tables support multiple columns, channel data sources, and
- * customizable formatting options.
+ * Table is a tabular data display component for viewing structured telemetry data.
+ * Tables support multiple columns, channel data sources, and customizable formatting
+ * options.
  */
 export const tableZ = z.object({
   /** key is the unique identifier for this table. */
-  key: keyZ,
+  key: keyZ.default(uuid.create),
   /** name is a human-readable name for the table. */
-  name: z.string(),
+  name: z.string().min(1, "name is required"),
   /** rows are the table rows in display order, top to bottom. */
-  rows: array.nullishToEmpty(rowZ),
+  rows: rowZ.array().default(() => []),
   /** columns are the table columns in display order, left to right. */
-  columns: array.nullishToEmpty(columnZ),
+  columns: columnZ.array().default(() => []),
   /**
-   * cells contains all cells in the table, keyed by cell key. Cell positions
-   * are derived from rows[*].cells[*] references; cells not referenced
-   * by any row are orphaned and will be pruned on the next structural
-   * edit.
+   * cells contains all cells in the table, keyed by cell key. Cell positions are
+   * derived from rows[*].cells[*] references; cells not referenced by any row are
+   * orphaned and will be pruned on the next structural edit.
    */
-  cells: caseconv.preserveCase(record.nullishToEmpty(z.string(), cellZ)),
+  cells: caseconv.preserveCase(z.record(z.string(), cellZ).default(() => ({}))),
 });
 export interface Table extends z.infer<typeof tableZ> {}
-
-export const newZ = tableZ.partial({
-  key: true,
-  rows: true,
-  columns: true,
-  cells: true,
-});
-export interface New extends z.input<typeof newZ> {}
+export interface New extends z.input<typeof tableZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("table");
 export const TYPE_ONTOLOGY_ID = ontologyID("");