@synnaxlabs/client 0.56.1 → 0.57.0

package/src/arc/client.ts

@@ -12,10 +12,32 @@ import {
   type StreamClient,
   type UnaryClient,
 } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import {
+  array,
+  deep,
+  type destructor,
+  errors,
+  id,
+  primitive,
+  zod,
+} from "@synnaxlabs/x";
 import { z } from "zod/v4";
 
-import { type Arc, arcZ, type Key, keyZ, type New, newZ } from "@/arc/types.gen";
+import { actions } from "@/actions";
+import { createOf, isUndoable, kindOf, reduceAll } from "@/arc/actions";
+import {
+  type Action,
+  dispatchReqZ,
+  rename as renameAction,
+  scopedActionZ,
+} from "@/arc/actions.gen";
+import { type Arc, arcZ, type Key, keyZ, type New, ontologyID } from "@/arc/types.gen";
+import { NotFoundError } from "@/errors";
+import { ontology } from "@/ontology";
+import { query } from "@/query";
+import { rack } from "@/rack";
+import { type status } from "@/status";
+import { task } from "@/task";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
 export const SET_CHANNEL_NAME = "sy_arc_set";
@@ -28,11 +50,13 @@ const retrieveReqZ = z.object({
   limit: z.int().optional(),
   offset: z.int().optional(),
   includeStatus: z.boolean().optional(),
+  ignoreNotFoundError: z.boolean().optional(),
 });
-const createReqZ = z.object({ arcs: newZ.array() });
+const retrieveMultiParamsZ = retrieveReqZ.or(query.keyListZ(keyZ));
+const createReqZ = z.object({ arcs: arcZ.array() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 
-const retrieveResZ = z.object({ arcs: array.nullishToEmpty(arcZ) });
+const retrieveResZ = z.object({ arcs: arcZ.array().default(() => []) });
 const createResZ = z.object({ arcs: arcZ.array() });
 const emptyResZ = z.object({});
 
@@ -55,60 +79,419 @@ const nameRetrieveRequestZ = z
   })
   .transform(({ name, includeStatus }) => ({ names: [name], includeStatus }));
 
-export const singleRetrieveArgsZ = z.union([keyRetrieveRequestZ, nameRetrieveRequestZ]);
+export const singleRetrieveParamsZ = z.union([
+  keyRetrieveRequestZ,
+  nameRetrieveRequestZ,
+]);
+
+export type SingleRetrieveParams = z.input<typeof singleRetrieveParamsZ>;
+
+const retrieveParamsZ = z.union([singleRetrieveParamsZ, retrieveReqZ]);
 
-export type SingleRetrieveArgs = z.input<typeof singleRetrieveArgsZ>;
+export type RetrieveParams = z.input<typeof retrieveParamsZ>;
 
-const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveReqZ]);
+const singleQueryZ = z.union([
+  z.strictObject({ key: keyZ, includeStatus: z.boolean().optional() }),
+  z.strictObject({ name: z.string(), includeStatus: z.boolean().optional() }),
+  keyZ.transform((key) => ({ key })),
+]);
 
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
+const setRackReqZ = z.object({ key: keyZ, rack: rack.keyZ });
+const setRackResZ = z.object({ task: task.payloadZ().nullish() });
 
-export class Client {
-  private readonly client: UnaryClient;
-  private readonly streamClient: StreamClient;
+/**
+ * Client-side matching for a request: key and name sets. Server-computed
+ * shapes (search, pagination) never reach this filter; they refetch instead.
+ */
+const requestFilter = (req: RetrieveRequest): ((a: Arc) => boolean) => {
+  const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+  const nameSet = primitive.isNonZero(req.names) ? new Set(req.names) : undefined;
+  return (a) => {
+    if (keySet != null && !keySet.has(a.key)) return false;
+    if (nameSet != null && !nameSet.has(a.name)) return false;
+    return true;
+  };
+};
 
-  constructor(client: UnaryClient, streamClient: StreamClient) {
-    this.client = client;
-    this.streamClient = streamClient;
+const isTaskChild = (rel: ontology.Relationship, arcKey: Key): boolean =>
+  ontology.matchRelationship(rel, {
+    from: ontologyID(arcKey),
+    type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+    to: { type: "task" },
+  });
+
+const taskStatusZ = z.object({ details: z.object({ task: task.keyZ }) });
+
+// Task statuses may arrive under any status key; the referenced task lives in
+// the details, with the "task:<key>" status key as a fallback.
+const affectedTaskKeys = (
+  event: query.TableEvent<status.Key, status.Status>,
+): task.Key[] | null => {
+  const keys: task.Key[] = [];
+  if (event.variant === "set") {
+    const parsed = taskStatusZ.safeParse(event.value);
+    if (parsed.success) keys.push(parsed.data.details.task);
   }
+  const [type, key] = event.key.split(":");
+  if (type === "task" && primitive.isNonZero(key) && !keys.includes(key))
+    keys.push(key);
+  return keys.length === 0 ? null : keys;
+};
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  stream: StreamClient;
+  ontology: ontology.Client;
+  tasks: task.Client;
+  cache: query.Cache;
+  statusStore: query.Table<status.Key, status.Status>;
+}
 
-  async create(arc: New): Promise<Arc>;
-  async create(arcs: New[]): Promise<Arc[]>;
-  async create(arcs: New | New[]): Promise<Arc | Arc[]> {
+export class Client extends query.Retriever<
+  typeof retrieveMultiParamsZ,
+  Key,
+  Arc,
+  Arc,
+  SingleRetrieveParams,
+  SingleRetrieveParams
+> {
+  private readonly cfg: ClientConfig;
+  private readonly dispatcher: actions.Controller<Key, Arc, Action>;
+  private readonly store: query.Table<Key, Arc>;
+  private readonly taskAnswers: query.Retrieves<Key, task.Task | null>;
+
+  constructor(cfg: ClientConfig) {
+    const { cache } = cfg;
+    // Fetched copies never clobber a doc holding locally replayed edits: the
+    // table hydrates if-absent, and hydrate() decides when a fresh network
+    // doc replaces the cached one.
+    const store = cache.createTable<Key, Arc>({
+      name: "Arcs",
+      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, Arc, Action>({
+      store,
+      onError: cache.onError,
+      reduce: reduceAll,
+      isUndoable,
+      kindOf,
+      createOf,
+    });
+    cache.listen(dispatcher.listener(SET_CHANNEL_NAME, scopedActionZ));
+    const single = cache.queries<SingleRetrieveParams, Arc, Key, Arc>({
+      name: "Arc",
+      table: store,
+      fetch: async (q) => [(await this.fetchSingle(q)).key],
+      compose: (records) => records[0],
+      keyOf: (q) => ("key" in q ? q.key : null),
+      matches: (a, q) => ("key" in q ? a.key === q.key : a.name === q.name),
+      single: true,
+    });
+    super(cache, {
+      name: "Arc",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) =>
+          (await this.execRetrieve(req)).map((a) => this.hydrate(a)),
+        matches: (a, req) => requestFilter(req)(a),
+      },
+      single: { schema: singleQueryZ, space: single },
+    });
+    this.cfg = cfg;
+    this.store = store;
+    this.dispatcher = dispatcher;
+    const composedTasks = cache.derive<task.Key, Omit<task.Task, "status">, task.Task>({
+      name: "arc.task.composed",
+      source: this.cfg.tasks.store,
+      compose: (record) => this.composeTask(record),
+      equal: (a, b) => deep.equal(a.payload, b.payload),
+      watch: [
+        query.deriveWatch(this.cfg.statusStore, (event) => affectedTaskKeys(event)),
+      ],
+    });
+    this.taskAnswers = cache.queries<Key, task.Task | null, task.Key, task.Task>({
+      name: "Arc task",
+      table: composedTasks,
+      fetch: async (q) => {
+        const tsk = await this.fetchTask(q);
+        return tsk == null ? [] : [tsk.key];
+      },
+      compose: (records) => records[0] ?? null,
+      matches: (t, q) =>
+        this.cfg.ontology.cache.relationships.has(
+          ontology.relationshipToString({
+            from: ontologyID(q),
+            type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+            to: task.ontologyID(t.key),
+          }),
+        ),
+      watch: [
+        query.watch(this.cfg.ontology.cache.relationships, (event, q: Key) => {
+          const rel =
+            event.variant === "set"
+              ? event.value
+              : ontology.relationshipZ.parse(event.key);
+          if (!isTaskChild(rel, q)) return null;
+          return [rel.to.key];
+        }),
+      ],
+    });
+  }
+
+  async create(arc: New, opts?: query.WriteOptions<Arc[]>): Promise<Arc>;
+  async create(arcs: New[], opts?: query.WriteOptions<Arc[]>): Promise<Arc[]>;
+  async create(
+    arcs: New | New[],
+    opts: query.WriteOptions<Arc[]> = {},
+  ): Promise<Arc | Arc[]> {
     const isMany = Array.isArray(arcs);
-    const res = await this.client.send(
-      "/arc/create",
-      { arcs: array.toArray(arcs) },
-      createReqZ,
-      createResZ,
-    );
+    const optimistic = array
+      .toArray(arcs)
+      .map((a) => zod.parse(arcZ, a, { label: "Arc" }));
+    const res = await query.optimistic({
+      rollbacks: [this.store.set(optimistic)],
+      onOptimistic: () => opts.onOptimistic?.(optimistic),
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/arc/create",
+          { arcs: optimistic },
+          createReqZ,
+          createResZ,
+        ),
+    });
+    this.store.set(res.arcs);
     return isMany ? res.arcs : res.arcs[0];
   }
 
-  async retrieve(args: SingleRetrieveArgs): Promise<Arc>;
-  async retrieve(args: RetrieveArgs): Promise<Arc[]>;
-  async retrieve(args: RetrieveArgs): Promise<Arc | Arc[]> {
-    const isSingle = "key" in args || "name" in args;
-    const res = await this.client.send(
-      "/arc/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResZ,
+  /**
+   * Binds the arc to the given rack, creating its task there or moving the
+   * existing one. A zero rack unbinds the arc, deleting its task. Returns the
+   * task, or null after an unbind.
+   * @throws {ValidationError} when unbinding while the task is running.
+   */
+  async setRack(key: Key, rackKey: rack.Key): Promise<task.Task | null> {
+    if (rackKey === 0) {
+      await this.clearRack(key);
+      return null;
+    }
+    const res = await this.cfg.unary.send(
+      "/arc/set-rack",
+      { key, rack: rackKey },
+      setRackReqZ,
+      setRackResZ,
     );
-    checkForMultipleOrNoResults("Arc", args, res.arcs, isSingle);
-    return isSingle ? res.arcs[0] : res.arcs;
+    if (res.task == null) return null;
+    const tsk = this.cfg.tasks.sugar(res.task);
+    this.cfg.tasks.store.set(tsk);
+    return tsk;
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/arc/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      emptyResZ,
+  // clearRack drops the deleted task from the cache so it is not served until
+  // the delete signal lands.
+  private async clearRack(key: Key): Promise<void> {
+    const tsk = await this.retrieveTask(key);
+    await this.cfg.unary.send(
+      "/arc/set-rack",
+      { key, rack: 0 },
+      setRackReqZ,
+      setRackResZ,
     );
+    if (tsk != null) this.cfg.tasks.dropCached(tsk.key);
+  }
+
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const tsk = await this.retrieveTask(key);
+    if (tsk != null) await this.cfg.tasks.rename(tsk.key, name);
+    const rename = () => query.partialUpdate(this.store, key, { name });
+    await query.optimistic({
+      rollbacks: [rename()],
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.sendDispatch(key, id.create(), [renameAction({ name })]),
+    });
+    rename();
+  }
+
+  private async retrieveTask(key: Key): Promise<task.Task | null> {
+    return await this.taskAnswers.retrieve(key);
+  }
+
+  /**
+   * Cached queries for the task deployed for an arc, keyed by the arc's key.
+   * Resolves null when the arc has no task.
+   */
+  get task(): query.Retrieves<Key, task.Task | null> {
+    return this.taskAnswers;
+  }
+
+  async delete(keys: Key | Key[], opts: query.WriteOptions = {}): Promise<void> {
+    const keysArr = array.toArray(keys);
+    const drop = () => this.store.delete(keysArr);
+    await query.optimistic({
+      rollbacks: [drop()],
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/arc/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
+  }
+
+  /** Subscribes to every arc delete delivered to the cache. */
+  onDelete(handler: (key: Key) => void): destructor.Destructor {
+    return this.store.subscribe((event) => {
+      if (event.variant === "delete") handler(event.key);
+    });
   }
 
   async openLSP(): Promise<Stream<typeof lspMessageZ, typeof lspMessageZ>> {
-    return await this.streamClient.stream("/arc/lsp", lspMessageZ, lspMessageZ);
+    return await this.cfg.stream.stream("/arc/lsp", lspMessageZ, lspMessageZ);
+  }
+
+  /**
+   * Applies actions to the cached arc and sends them to the server, recording an
+   * undoable entry. Returns false without side effects when the arc isn't cached. Rolls
+   * back the local apply and rethrows on send failure.
+   */
+  async dispatch(
+    key: Key,
+    actions: Action | Action[],
+    opts: actions.Options<Arc, Action> = {},
+  ): Promise<boolean> {
+    return await this.dispatcher.dispatch(
+      key,
+      array.toArray(actions),
+      this.dispatchSender(key),
+      opts,
+    );
+  }
+
+  /**
+   * Reverts the arc'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 arc'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 arc has a live undo entry. */
+  hasUndo(key: Key): boolean {
+    return this.dispatcher.hasUndo(key);
+  }
+
+  /** Whether the arc has a live redo entry. */
+  hasRedo(key: Key): boolean {
+    return this.dispatcher.hasRedo(key);
+  }
+
+  /**
+   * Subscribes to changes in the arc'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);
+  }
+
+  private dispatchSender(key: Key): actions.SendDispatch<Action> {
+    return async (actions, dispatchKey) =>
+      await this.sendDispatch(key, dispatchKey, actions);
+  }
+
+  private async sendDispatch(
+    key: Key,
+    dispatchKey: string,
+    actions: Action[],
+  ): Promise<void> {
+    await this.cfg.unary.send(
+      "/arc/dispatch",
+      { key, dispatchKey, actions },
+      dispatchReqZ,
+      emptyResZ,
+    );
+  }
+
+  private async execRetrieve(params: RetrieveParams): Promise<Arc[]> {
+    const res = await this.cfg.unary.send(
+      "/arc/retrieve",
+      params,
+      retrieveParamsZ,
+      retrieveResZ,
+    );
+    return res.arcs;
+  }
+
+  // Dispatch mutates documents server-side (including materialized text), so
+  // a cached copy is only as fresh as the streamer. Fetches always hit the
+  // network; only the server materializes text.
+  private async fetchSingle(q: SingleRetrieveParams): Promise<Arc> {
+    const arcs = await this.execRetrieve(q);
+    checkForMultipleOrNoResults("Arc", q, arcs, true);
+    return this.hydrate(arcs[0]);
+  }
+
+  // Answers reuse the identical store doc so selector references stay
+  // stable; a fresher network doc replaces it and answers. While a locally
+  // replayed dispatch awaits its echo the replayed doc stays, but the
+  // network doc answers: it carries the server-materialized text.
+  private hydrate(a: Arc): Arc {
+    if (this.dispatcher.hasOutstanding(a.key) === true) {
+      this.store.ingest(a);
+      return a;
+    }
+    const prev = this.store.get(a.key);
+    if (prev != null && deep.equal(prev, a)) return prev;
+    this.store.set(a);
+    return a;
+  }
+
+  /**
+   * Rebuilds a cached task with its cached status attached. The status is
+   * parsed because the status table holds every domain's statuses generically.
+   */
+  private composeTask(cached: Omit<task.Task, "status">): task.Task {
+    const cachedStatus = this.cfg.statusStore.get(task.statusKey(cached.key));
+    const payload = cached.payload;
+    if (cachedStatus == null) return this.cfg.tasks.sugar(payload);
+    const parsed = task.statusZ().safeParse(cachedStatus);
+    if (!parsed.success) return this.cfg.tasks.sugar(payload);
+    return this.cfg.tasks.sugar({ ...payload, status: parsed.data });
+  }
+
+  private async fetchTask(arcKey: Key): Promise<task.Task | null> {
+    let children: ontology.Resource[];
+    try {
+      children = await this.cfg.ontology.children.retrieve({
+        ids: ontologyID(arcKey),
+        types: ["task"],
+      });
+    } catch (e) {
+      // An arc that does not exist cannot have a task.
+      if (NotFoundError.matches(e)) return null;
+      throw errors.fromUnknown(e);
+    }
+    const child = children[0];
+    if (child == null) return null;
+    return await this.cfg.tasks.retrieve(child.id.key);
   }
 }

package/src/arc/compiler/types.gen.ts

@@ -9,20 +9,19 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { record } from "@synnaxlabs/x";
 import { z } from "zod";
 
 /**
- * Output is compiled output from the Arc compiler including WebAssembly bytecode
- * and memory layout.
+ * Output is compiled output from the Arc compiler including WebAssembly bytecode and
+ * memory layout.
  */
 export const outputZ = z.object({
   /** wasm is compiled WebAssembly bytecode for sandboxed execution. */
   wasm: z.instanceof(Uint8Array),
   /**
-   * outputMemoryBases contains memory base addresses for multi-output functions, mapping
-   * function keys to their base addresses.
+   * outputMemoryBases contains memory base addresses for multi-output functions,
+   * mapping function keys to their base addresses.
    */
-  outputMemoryBases: record.nullishToEmpty(z.string(), z.uint32()),
+  outputMemoryBases: z.record(z.string(), z.uint32()).default(() => ({})),
 });
 export interface Output extends z.infer<typeof outputZ> {}

package/src/arc/external.ts

@@ -7,6 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/arc/actions";
+export * from "@/arc/actions.gen";
 export * from "@/arc/client";
 export * from "@/arc/compiler";
 export * from "@/arc/graph";

package/src/arc/graph/types.gen.ts

@@ -9,51 +9,53 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, record, spatial } from "@synnaxlabs/x";
+import { caseconv, record, spatial } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ir } from "@/arc/ir";
 
 /**
- * Node is a visual node in the Arc graph editor representing a function
- * instantiation with position data.
+ * Node is a visual node in the Arc graph editor representing a function instantiation
+ * with position data. The function type and input parameter values are stored in the
+ * graph's inputs map, keyed by the node key.
  */
 export const nodeZ = z.object({
   /** key is the unique identifier for this node instance. */
   key: z.string(),
-  /** type is the function type being instantiated. */
-  type: z.string(),
-  /** config contains configuration parameter values as a JSON object. */
-  config: record.nullishToEmpty(),
   /** position is the canvas position (x, y) for visual layout. */
   position: spatial.xyZ,
 });
 export interface Node extends z.infer<typeof nodeZ> {}
 
-/** Viewport is the camera state for viewing the Arc graph editor canvas. */
-export const viewportZ = z.object({
-  /** position is the camera pan offset (x, y). */
-  position: spatial.xyZ,
-  /** zoom is the zoom level where 1.0 equals 100%. */
-  zoom: z.number(),
+export const edgeZ = ir.edgeZ.extend({
+  key: z.string(),
 });
-export interface Viewport extends z.infer<typeof viewportZ> {}
+export interface Edge extends z.infer<typeof edgeZ> {}
 
-export const nodesZ = array.nullishToEmpty(nodeZ);
+export const nodesZ = nodeZ.array().default(() => []);
 export type Nodes = z.infer<typeof nodesZ>;
 
+export const edgesZ = edgeZ.array().default(() => []);
+export type Edges = z.infer<typeof edgesZ>;
+
 /**
- * Graph is a visual dataflow graph representation combining IR elements with
- * canvas layout for the Arc graph editor.
+ * Graph is a visual dataflow graph representation combining IR elements with canvas
+ * layout for the Arc graph editor.
  */
 export const graphZ = z.object({
-  /** viewport is the current camera state for the graph view. */
-  viewport: viewportZ,
   /** functions contains function definitions available in this graph. */
-  functions: ir.functionsZ,
+  functions: ir.functionsZ.default([]),
   /** edges contains dataflow connections between node parameters. */
-  edges: ir.edgesZ,
+  edges: edgesZ.default([]),
   /** nodes contains visual nodes with canvas positions. */
-  nodes: nodesZ,
+  nodes: nodesZ.default([]),
+  /**
+   * inputs contains per-node inputs keyed by node key. Each value is a JSON object
+   * holding the node's function type under "type" plus its input parameter values. The
+   * wire format stores it as an opaque record; the client types it per function.
+   */
+  inputs: caseconv.preserveCase(
+    z.record(z.string(), record.unknownZ()).default(() => ({})),
+  ),
 });
 export interface Graph extends z.infer<typeof graphZ> {}

package/src/arc/ir/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as ir from "@/arc/ir/types.gen";
+export * as ir from "@/arc/ir/ir";

package/{eslint.config.ts → src/arc/ir/ir.ts}

@@ -7,7 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import cfg from "@synnaxlabs/eslint-config";
-import type { Linter } from "eslint";
-
-export default [...cfg, { ignores: ["examples"] }] as Linter.Config[];
+export * from "@/arc/ir/types.gen";