@synnaxlabs/client 0.56.2 → 0.57.1

package/src/ranger/kv/client.ts

@@ -11,21 +11,25 @@ import { type UnaryClient } from "@synnaxlabs/freighter";
 import { array } from "@synnaxlabs/x";
 import { z } from "zod";
 
+import { query } from "@/query";
+import { createPairKey } from "@/ranger/kv/payload";
 import { type Pair, pairZ } from "@/ranger/kv/types.gen";
 import { type Key, keyZ } from "@/ranger/types.gen";
 
 const getReqZ = z.object({ range: keyZ, keys: z.string().array() });
-const getResZ = z.object({ pairs: array.nullishToEmpty(pairZ) });
+const getResZ = z.object({ pairs: pairZ.array().default(() => []) });
 const setReqZ = z.object({ range: keyZ, pairs: pairZ.array() });
 const deleteReqZ = z.object({ range: keyZ, keys: z.string().array() });
 
 export class Client {
   private readonly rangeKey: Key;
   private readonly client: UnaryClient;
+  private readonly pairs: query.Table<string, Pair>;
 
-  constructor(rng: Key, client: UnaryClient) {
+  constructor(rng: Key, client: UnaryClient, pairs: query.Table<string, Pair>) {
     this.rangeKey = rng;
     this.client = client;
+    this.pairs = pairs;
   }
 
   async get(key: string): Promise<string>;
@@ -45,32 +49,59 @@ export class Client {
     return await this.get([]);
   }
 
-  async set(key: string, value: string): Promise<void>;
-  async set(kv: Record<string, string>): Promise<void>;
-  async set(key: string | Record<string, string>, value: string = ""): Promise<void> {
+  async set(key: string, value: string, opts?: query.WriteOptions): Promise<void>;
+  async set(kv: Record<string, string>, opts?: query.WriteOptions): Promise<void>;
+  async set(
+    key: string | Record<string, string>,
+    valueOrOpts: string | query.WriteOptions = "",
+    opts: query.WriteOptions = {},
+  ): Promise<void> {
     let pairs: Pair[];
-    if (typeof key == "string") pairs = [{ range: this.rangeKey, key, value }];
-    else
+    if (typeof key === "string")
+      pairs = [{ range: this.rangeKey, key, value: valueOrOpts as string }];
+    else {
       pairs = Object.entries(key).map(([k, v]) => ({
         range: this.rangeKey,
         key: k,
         value: v,
       }));
-
-    await this.client.send(
-      "/range/kv/set",
-      { range: this.rangeKey, pairs },
-      setReqZ,
-      z.unknown(),
-    );
+      if (typeof valueOrOpts === "object") opts = valueOrOpts;
+    }
+    // Pair.key is the bare key; the table is keyed by createPairKey, so keyed-object
+    // set would mis-key entries.
+    const apply = () => pairs.map((p) => this.pairs.set(createPairKey(p), p));
+    await query.optimistic({
+      rollbacks: apply(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.client.send(
+          "/range/kv/set",
+          { range: this.rangeKey, pairs },
+          setReqZ,
+          z.unknown(),
+        ),
+    });
+    apply();
   }
 
-  async delete(key: string | string[]): Promise<void> {
-    await this.client.send(
-      "/range/kv/delete",
-      { range: this.rangeKey, keys: array.toArray(key) },
-      deleteReqZ,
-      z.unknown(),
-    );
+  async delete(key: string | string[], opts: query.WriteOptions = {}): Promise<void> {
+    const keys = array.toArray(key);
+    const drop = () => [
+      this.pairs.delete(
+        keys.map((k) => createPairKey({ range: this.rangeKey, key: k })),
+      ),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.client.send(
+          "/range/kv/delete",
+          { range: this.rangeKey, keys },
+          deleteReqZ,
+          z.unknown(),
+        ),
+    });
+    drop();
   }
 }

package/src/ranger/payload.ts

@@ -11,6 +11,9 @@ import { z } from "zod";
 
 import { type Key } from "@/ranger/types.gen";
 
+/** Zod schema for {@link Name}. A range name cannot be empty. */
 export const nameZ = z.string().min(1);
+/** A range's display name. */
 export type Name = z.infer<typeof nameZ>;
+/** One or many ranges, named by key or by name. */
 export type Params = Key | Name | Key[] | Name[];

package/src/ranger/types.gen.ts

@@ -9,20 +9,20 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { color, label, telem, zod } from "@synnaxlabs/x";
+import { color, telem, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
+import { label } from "@/label";
 import { ontology } from "@/ontology";
 
 export const keyZ = z.uuid();
 export type Key = z.infer<typeof keyZ>;
 
 /**
- * Base is a user-defined region of time in the Synnax cluster. Ranges act as a
- * method for labeling and categorizing telemetry data within specific time
- * periods.
+ * Payload is a user-defined region of time in the Synnax cluster. Ranges act as a
+ * method for labeling and categorizing telemetry data within specific time periods.
  */
-export const baseZ = z.object({
+export const payloadZ = z.object({
   /** key is the unique identifier for this range. */
   key: keyZ,
   /** name is a human-readable name for the range. */
@@ -31,35 +31,33 @@ export const baseZ = z.object({
    * timeRange is the temporal extent of the range, defining its start and end
    * timestamps.
    */
-  timeRange: telem.timeRangeZ,
+  timeRange: telem.timeRangeBoundedZ,
   /**
-   * color is an optional display color for visual identification of the range
-   * in user interfaces.
+   * color is an optional display color for visual identification of the range in user
+   * interfaces.
    */
   color: color.colorZ.optional(),
-});
-export interface Base extends z.infer<typeof baseZ> {}
-
-export const apiRangeZ = baseZ.extend({
-  labels: zod.nullToUndefined(label.labelZ.array()),
-  get parent(): z.ZodOptional<typeof apiRangeZ> {
-    return apiRangeZ.optional();
-  },
-});
-export interface APIRange extends z.infer<typeof apiRangeZ> {}
-
-export const payloadZ = baseZ.omit({ timeRange: true }).extend({
+  /**
+   * labels contains optional labels attached to this range for categorization and
+   * filtering.
+   */
   labels: zod.nullToUndefined(label.labelZ.array()),
+  /**
+   * parent is an optional parent range for hierarchical organization. Ranges can be
+   * nested within other ranges.
+   */
   get parent(): z.ZodOptional<typeof payloadZ> {
     return payloadZ.optional();
   },
-  timeRange: telem.timeRangeBoundedZ,
 });
 export interface Payload extends z.infer<typeof payloadZ> {}
 
 export const newZ = payloadZ
-  .omit({ parent: true, labels: true })
-  .partial({ key: true });
+  .omit({ labels: true, parent: true })
+  .partial({ key: true })
+  .extend({
+    parent: payloadZ.pick({ key: true }).optional(),
+  });
 export interface New extends z.input<typeof newZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("range");

package/src/ranger/writer.ts

@@ -10,23 +10,19 @@
 import { type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { ontology } from "@/ontology";
 import { nameZ } from "@/ranger/payload";
 import { keyZ, type New, newZ, type Payload, payloadZ } from "@/ranger/types.gen";
 
+const createReqZ = z.object({ ranges: newZ.array() });
 const createResZ = z.object({ ranges: payloadZ.array() });
 
-const createReqZ = z.object({ parent: ontology.idZ.optional(), ranges: newZ.array() });
-
-interface CreateRequest extends z.infer<typeof createReqZ> {}
-export interface CreateOptions extends Pick<CreateRequest, "parent"> {}
-
 const deleteReqZ = z.object({ keys: keyZ.array() });
 const deleteResZ = z.object({});
 
 const renameReqZ = z.object({ key: keyZ, name: nameZ });
 const renameResZ = z.object({});
 
+/** Creates, renames, and deletes ranges. Reach it through `client.ranges`. */
 export class Writer {
   client: UnaryClient;
 
@@ -38,10 +34,10 @@ export class Writer {
     await this.client.send("/range/rename", { key, name }, renameReqZ, renameResZ);
   }
 
-  async create(ranges: New[], options?: CreateOptions): Promise<Payload[]> {
+  async create(ranges: New[]): Promise<Payload[]> {
     const res = await this.client.send(
       "/range/create",
-      { ranges, ...options },
+      { ranges },
       createReqZ,
       createResZ,
     );

package/src/schematic/actions.gen.ts

@@ -13,7 +13,17 @@ import { type Draft } from "immer";
 import { z } from "zod";
 
 import { actions } from "@/actions";
-import { edgeZ, keyZ, nodeZ, type Schematic } from "@/schematic/types.gen";
+import { edgeZ, keyZ, nodeZ, type Schematic, schematicZ } from "@/schematic/types.gen";
+
+/**
+ * Create replaces the document with the given created state. Emitted by the Core on
+ * create so remote caches ingest new documents; clients never dispatch it.
+ */
+export const createPayloadZ = z.object({
+  schematic: schematicZ,
+});
+
+export type CreatePayload = z.infer<typeof createPayloadZ>;
 
 /** Rename renames the schematic. */
 export const renamePayloadZ = z.object({
@@ -31,21 +41,9 @@ export const setNodePositionPayloadZ = z.object({
 export type SetNodePositionPayload = z.infer<typeof setNodePositionPayloadZ>;
 
 /**
- * SetNodeMeasured updates the rendered pixel size of a node. Emitted by the
- * renderer after measuring the mounted node and stored on the
- * node so diagram measurements stay consistent across re-renders.
- */
-export const setNodeMeasuredPayloadZ = z.object({
-  key: z.string(),
-  measured: spatial.dimensionsZ,
-});
-
-export type SetNodeMeasuredPayload = z.infer<typeof setNodeMeasuredPayloadZ>;
-
-/**
- * SetNode inserts the node if no node with the same key exists, otherwise
- * replaces the existing node in place. If config is non-empty it is
- * stored under the node's key in the schematic configs map.
+ * SetNode inserts the node if no node with the same key exists, otherwise replaces the
+ * existing node in place. If config is non-empty it is stored under the node's key in
+ * the schematic configs map.
  */
 export const setNodePayloadZ = z.object({
   node: nodeZ,
@@ -62,8 +60,8 @@ export const removeNodePayloadZ = z.object({
 export type RemoveNodePayload = z.infer<typeof removeNodePayloadZ>;
 
 /**
- * AddEdge appends the edge to the schematic. No-op when an edge with the
- * same key already exists.
+ * AddEdge appends the edge to the schematic. No-op when an edge with the same key
+ * already exists.
  */
 export const addEdgePayloadZ = z.object({
   edge: edgeZ,
@@ -79,30 +77,26 @@ export const removeEdgePayloadZ = z.object({
 export type RemoveEdgePayload = z.infer<typeof removeEdgePayloadZ>;
 
 /**
- * SetConfig merges the given config fields into the existing config entry for
- * the given node or edge key. Top-level fields present in the payload
- * overwrite existing fields; fields absent from the payload are
- * preserved. When no entry exists yet and the key matches an edge
- * whose source node carries a color, the source color overrides
+ * SetConfig merges the given config fields into the existing config entry for the given
+ * node or edge key. Top-level fields present in the payload overwrite existing fields;
+ * fields absent from the payload are preserved. When no entry exists yet and the key
+ * matches an edge whose source node carries a color, the source color overrides
  * whatever color (if any) was in the payload.
  */
 export const setConfigPayloadZ = z.object({
   key: z.string(),
-  config: caseconv.preserveCase(record.nullishToEmpty()),
+  config: caseconv.preserveCase(record.unknownZ().default(() => ({}))),
 });
 
 export type SetConfigPayload = z.infer<typeof setConfigPayloadZ>;
 
 export const actionZ = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("create"), create: createPayloadZ }),
   z.object({ type: z.literal("rename"), rename: renamePayloadZ }),
   z.object({
     type: z.literal("set_node_position"),
     setNodePosition: setNodePositionPayloadZ,
   }),
-  z.object({
-    type: z.literal("set_node_measured"),
-    setNodeMeasured: setNodeMeasuredPayloadZ,
-  }),
   z.object({ type: z.literal("set_node"), setNode: setNodePayloadZ }),
   z.object({ type: z.literal("remove_node"), removeNode: removeNodePayloadZ }),
   z.object({ type: z.literal("add_edge"), addEdge: addEdgePayloadZ }),
@@ -112,44 +106,62 @@ export const actionZ = z.discriminatedUnion("type", [
 
 export type Action = z.infer<typeof actionZ>;
 
-export const rename = (payload: RenamePayload): Action => ({
-  type: "rename",
-  rename: payload,
+export const create = (payload: z.input<typeof createPayloadZ>): Action => ({
+  type: "create",
+  create: zod.parse(createPayloadZ, payload, {
+    label: "schematic create action payload",
+  }),
 });
 
-export const setNodePosition = (payload: SetNodePositionPayload): Action => ({
-  type: "set_node_position",
-  setNodePosition: payload,
+export const rename = (payload: z.input<typeof renamePayloadZ>): Action => ({
+  type: "rename",
+  rename: zod.parse(renamePayloadZ, payload, {
+    label: "schematic rename action payload",
+  }),
 });
 
-export const setNodeMeasured = (payload: SetNodeMeasuredPayload): Action => ({
-  type: "set_node_measured",
-  setNodeMeasured: payload,
+export const setNodePosition = (
+  payload: z.input<typeof setNodePositionPayloadZ>,
+): Action => ({
+  type: "set_node_position",
+  setNodePosition: zod.parse(setNodePositionPayloadZ, payload, {
+    label: "schematic set_node_position action payload",
+  }),
 });
 
-export const setNode = (payload: SetNodePayload): Action => ({
+export const setNode = (payload: z.input<typeof setNodePayloadZ>): Action => ({
   type: "set_node",
-  setNode: payload,
+  setNode: zod.parse(setNodePayloadZ, payload, {
+    label: "schematic set_node action payload",
+  }),
 });
 
-export const removeNode = (payload: RemoveNodePayload): Action => ({
+export const removeNode = (payload: z.input<typeof removeNodePayloadZ>): Action => ({
   type: "remove_node",
-  removeNode: payload,
+  removeNode: zod.parse(removeNodePayloadZ, payload, {
+    label: "schematic remove_node action payload",
+  }),
 });
 
-export const addEdge = (payload: AddEdgePayload): Action => ({
+export const addEdge = (payload: z.input<typeof addEdgePayloadZ>): Action => ({
   type: "add_edge",
-  addEdge: payload,
+  addEdge: zod.parse(addEdgePayloadZ, payload, {
+    label: "schematic add_edge action payload",
+  }),
 });
 
-export const removeEdge = (payload: RemoveEdgePayload): Action => ({
+export const removeEdge = (payload: z.input<typeof removeEdgePayloadZ>): Action => ({
   type: "remove_edge",
-  removeEdge: payload,
+  removeEdge: zod.parse(removeEdgePayloadZ, payload, {
+    label: "schematic remove_edge action payload",
+  }),
 });
 
-export const setConfig = (payload: SetConfigPayload): Action => ({
+export const setConfig = (payload: z.input<typeof setConfigPayloadZ>): Action => ({
   type: "set_config",
-  setConfig: payload,
+  setConfig: zod.parse(setConfigPayloadZ, payload, {
+    label: "schematic set_config action payload",
+  }),
 });
 
 export type HandlerResult = actions.HandlerResult<Action>;
@@ -157,15 +169,12 @@ export type HandlerResult = actions.HandlerResult<Action>;
 export type ReduceAllResult = actions.ReduceAllResult<Schematic, Action>;
 
 export interface Handlers {
+  create: (state: Draft<Schematic>, payload: CreatePayload) => HandlerResult;
   rename: (state: Draft<Schematic>, payload: RenamePayload) => HandlerResult;
   setNodePosition: (
     state: Draft<Schematic>,
     payload: SetNodePositionPayload,
   ) => HandlerResult;
-  setNodeMeasured: (
-    state: Draft<Schematic>,
-    payload: SetNodeMeasuredPayload,
-  ) => HandlerResult;
   setNode: (state: Draft<Schematic>, payload: SetNodePayload) => HandlerResult;
   removeNode: (state: Draft<Schematic>, payload: RemoveNodePayload) => HandlerResult;
   addEdge: (state: Draft<Schematic>, payload: AddEdgePayload) => HandlerResult;
@@ -176,12 +185,12 @@ export interface Handlers {
 export const createReduceAll = (handlers: Handlers) =>
   actions.createReduceAll<Schematic, Action>((state, action) => {
     switch (action.type) {
+      case "create":
+        return handlers.create(state, action.create);
       case "rename":
         return handlers.rename(state, action.rename);
       case "set_node_position":
         return handlers.setNodePosition(state, action.setNodePosition);
-      case "set_node_measured":
-        return handlers.setNodeMeasured(state, action.setNodeMeasured);
       case "set_node":
         return handlers.setNode(state, action.setNode);
       case "remove_node":

package/src/schematic/actions.ts

@@ -8,13 +8,12 @@
 // included in the file licenses/APL.txt.
 
 import { color, type record } from "@synnaxlabs/x";
-import { current, type Draft, isDraft } from "immer";
 
+import { actions } from "@/actions";
 import {
   type Action,
   addEdge,
   createReduceAll,
-  type HandlerResult,
   type Handlers,
   removeEdge,
   removeNode,
@@ -24,16 +23,12 @@ import {
   setNodePosition,
 } from "@/schematic/actions.gen";
 
-const NO_OP: HandlerResult = { inverse: [], targets: [] };
-
-// Snapshots a value out of an Immer draft so the result is safe to embed in an
-// action stored on the undo stack. When reduceAll applies multiple actions in
-// one produce(), an earlier action's wholesale assignment (e.g. state.configs[k]
-// = {...existing, ...payload.config}) leaves the slot as a plain object — the
-// next action would crash if it called current() unconditionally.
-const snapshot = <T>(v: T): T => (isDraft(v) ? current(v as Draft<T>) : v);
-
 const handlers: Handlers = {
+  create: (state, payload) => {
+    Object.assign(state, payload.schematic);
+    return { inverse: [], targets: [payload.schematic.key] };
+  },
+
   rename: (state, payload) => {
     const oldName = state.name;
     state.name = payload.name;
@@ -44,7 +39,7 @@ const handlers: Handlers = {
   },
   setNodePosition: (state, payload) => {
     const node = state.nodes.find((n) => n.key === payload.key);
-    if (node == null) return NO_OP;
+    if (node == null) return actions.NO_OP_RESULT;
     const oldPosition = { x: node.position.x, y: node.position.y };
     node.position = payload.position;
     return {
@@ -52,17 +47,6 @@ const handlers: Handlers = {
       targets: [payload.key],
     };
   },
-
-  // set_node_measured carries layout-derived dimensions, not user intent.
-  // Both the inverse and the target list are empty so it neither contributes
-  // to the undo stack nor invalidates undoables targeting the same node when
-  // a remote session emits it.
-  setNodeMeasured: (state, payload) => {
-    const node = state.nodes.find((n) => n.key === payload.key);
-    if (node == null) return NO_OP;
-    node.measured = payload.measured;
-    return { inverse: [], targets: [] };
-  },
   setNode: (state, payload) => {
     const idx = state.nodes.findIndex((n) => n.key === payload.node.key);
     if (idx === -1) {
@@ -73,9 +57,10 @@ const handlers: Handlers = {
         targets: [payload.node.key],
       };
     }
-    const oldNode = snapshot(state.nodes[idx]);
+    const oldNode = actions.snapshotDraft(state.nodes[idx]);
     const oldConfigRaw = state.configs[payload.node.key];
-    const oldConfig = oldConfigRaw != null ? snapshot(oldConfigRaw) : undefined;
+    const oldConfig =
+      oldConfigRaw != null ? actions.snapshotDraft(oldConfigRaw) : undefined;
     state.nodes[idx] = payload.node;
     if (payload.config != null) state.configs[payload.node.key] = payload.config;
     return {
@@ -91,10 +76,11 @@ const handlers: Handlers = {
   },
   removeNode: (state, payload) => {
     const idx = state.nodes.findIndex((n) => n.key === payload.key);
-    if (idx === -1) return NO_OP;
-    const oldNode = snapshot(state.nodes[idx]);
+    if (idx === -1) return actions.NO_OP_RESULT;
+    const oldNode = actions.snapshotDraft(state.nodes[idx]);
     const oldConfigRaw = state.configs[payload.key];
-    const oldConfig = oldConfigRaw != null ? snapshot(oldConfigRaw) : undefined;
+    const oldConfig =
+      oldConfigRaw != null ? actions.snapshotDraft(oldConfigRaw) : undefined;
     state.nodes.splice(idx, 1);
     delete state.configs[payload.key];
     return {
@@ -109,7 +95,8 @@ const handlers: Handlers = {
     };
   },
   addEdge: (state, payload) => {
-    if (state.edges.some((e) => e.key === payload.edge.key)) return NO_OP;
+    if (state.edges.some((e) => e.key === payload.edge.key))
+      return actions.NO_OP_RESULT;
     state.edges.push(payload.edge);
     return {
       inverse: [removeEdge({ key: payload.edge.key })],
@@ -119,24 +106,23 @@ const handlers: Handlers = {
 
   removeEdge: (state, payload) => {
     const idx = state.edges.findIndex((e) => e.key === payload.key);
-    if (idx === -1) return NO_OP;
-    const oldEdge = snapshot(state.edges[idx]);
+    if (idx === -1) return actions.NO_OP_RESULT;
+    const oldEdge = actions.snapshotDraft(state.edges[idx]);
     state.edges.splice(idx, 1);
     return {
       inverse: [addEdge({ edge: oldEdge })],
       targets: [payload.key],
     };
   },
-  // The inverse of SetConfig is imperfect for keys the action newly
-  // introduces: SetConfig only merges, so it cannot remove keys that did not
-  // previously exist. The inverse here restores values for keys that DID
-  // exist before the merge; keys added by the action remain on undo as
-  // phantom fields. A future ReplaceConfig action can close the gap by
-  // enabling wholesale replacement.
+  // The inverse of SetConfig is imperfect for keys the action newly introduces:
+  // SetConfig only merges, so it cannot remove keys that did not previously exist. The
+  // inverse here restores values for keys that DID exist before the merge; keys added
+  // by the action remain on undo as phantom fields. A future ReplaceConfig action can
+  // close the gap by enabling wholesale replacement.
   setConfig: (state, payload) => {
     const existingRaw = state.configs[payload.key];
     if (existingRaw != null) {
-      const existing = snapshot(existingRaw);
+      const existing = actions.snapshotDraft(existingRaw);
       const restoreFields: record.Unknown = {};
       for (const k of Object.keys(payload.config))
         if (existing[k] !== undefined) restoreFields[k] = existing[k];
@@ -152,8 +138,7 @@ const handlers: Handlers = {
     const edge = state.edges.find((e) => e.key === payload.key);
     if (edge != null) {
       const srcCfg = state.configs[edge.source.node] as
-        | { color?: color.Crude }
-        | undefined;
+        { color?: color.Crude } | undefined;
       if (srcCfg?.color != null && !color.isZero(srcCfg.color))
         cfg = { ...cfg, color: srcCfg.color };
     }
@@ -164,5 +149,22 @@ const handlers: Handlers = {
 
 export const reduceAll = createReduceAll(handlers);
 
-export const isUndoable = (action: Action): boolean =>
-  action.type !== "set_node_measured";
+// 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.schematic : undefined;
+
+export const kindOf = (actions: Action[]): string => {
+  if (actions.length === 0) return "default";
+  // A drag dispatches a stream of `set_node_position` per frame, plus `set_config`
+  // companions synthesized by augmentWithEdgeSegments for any affected edges. Both
+  // shapes are part of one user gesture and must coalesce together; classify them all
+  // as "move" so the per-kind coalesce window collapses them into a single undoable.
+  const hasMove = actions.some((a) => a.type === "set_node_position");
+  const onlyMoveOrSegment = actions.every(
+    (a) => a.type === "set_node_position" || a.type === "set_config",
+  );
+  if (hasMove && onlyMoveOrSegment) return "move";
+  if (actions.length === 1) return actions[0].type;
+  return "transaction";
+};