@synnaxlabs/client 0.56.2 → 0.57.1

package/src/schematic/symbol/client.ts

@@ -7,114 +7,291 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type UnaryClient } from "@synnaxlabs/freighter";
-import { array } from "@synnaxlabs/x";
+import {
+  type FileTransport,
+  type UnaryClient,
+  type UploadBody,
+} from "@synnaxlabs/freighter";
+import { array, primitive } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { group } from "@/group";
+import { imex } from "@/imex";
 import { ontology } from "@/ontology";
+import { query } from "@/query";
 import {
   type Key,
   keyZ,
   type New,
-  newZ,
+  ontologyID,
   type Symbol,
   symbolZ,
 } from "@/schematic/symbol/types.gen";
-import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
-const createReqZ = z.object({ symbols: newZ.array(), parent: ontology.idZ });
+export const SET_CHANNEL_NAME = "sy_schematic_symbol_set";
+export const DELETE_CHANNEL_NAME = "sy_schematic_symbol_delete";
+
+const createReqZ = z.object({ symbols: symbolZ.array(), parent: ontology.idZ });
 const renameReqZ = z.object({ key: keyZ, name: z.string() });
 const deleteReqZ = z.object({ keys: keyZ.array() });
 
-const retrieveRequestZ = z.object({
+// The server only understands keys and searchTerm; parent scoping is resolved
+// client-side through the ontology, so it never reaches the wire.
+const wireRetrieveRequestZ = z.object({
   keys: keyZ.array().optional(),
   searchTerm: z.string().optional(),
 });
 
-const singleRetrieveArgsZ = z
+const retrieveRequestZ = wireRetrieveRequestZ.extend({
+  parent: ontology.idZ.optional(),
+});
+const retrieveMultiParamsZ = retrieveRequestZ.or(query.keyListZ(keyZ));
+
+const singleRetrieveParamsZ = z
   .object({ key: keyZ })
   .transform(({ key }) => ({ keys: [key] }));
 
-const retrieveArgsZ = z.union([singleRetrieveArgsZ, retrieveRequestZ]);
+const retrieveParamsZ = z.union([singleRetrieveParamsZ, wireRetrieveRequestZ]);
 
-export type RetrieveArgs = z.input<typeof retrieveArgsZ>;
-export type RetrieveSingleParams = z.input<typeof singleRetrieveArgsZ>;
+export type RetrieveSingleParams = z.input<typeof singleRetrieveParamsZ>;
 export type RetrieveMultipleParams = z.input<typeof retrieveRequestZ>;
+export type RetrieveParams = RetrieveSingleParams | RetrieveMultipleParams;
+
+interface RetrieveRequest extends z.infer<typeof retrieveRequestZ> {}
 
-const retrieveResZ = z.object({ symbols: array.nullishToEmpty(symbolZ) });
+const retrieveResZ = z.object({ symbols: symbolZ.array().default(() => []) });
 const createResZ = z.object({ symbols: symbolZ.array() });
 const emptyResZ = z.object({});
 const retrieveGroupReqZ = z.object({});
 const retrieveGroupResZ = z.object({ group: group.groupZ });
+const exportGroupReqZ = z.object({ key: group.keyZ, encoding: imex.encodingZ });
+const importGroupResZ = z.object({ group: group.groupZ });
+const deleteGroupReqZ = z.object({ key: group.keyZ });
 
-export const SET_CHANNEL_NAME = "sy_schematic_symbol_set";
-export const DELETE_CHANNEL_NAME = "sy_schematic_symbol_delete";
-
-export interface CreateArgs extends New {
+export interface CreateParams extends New {
   parent: ontology.ID;
 }
 
-export interface CreateMultipleArgs {
+export interface CreateMultipleParams {
   symbols: New[];
   parent: ontology.ID;
 }
 
-export class Client {
-  private readonly client: UnaryClient;
+/** Query fields only the server can evaluate. */
+const SERVER_FIELDS = ["searchTerm"] as const;
 
-  constructor(client: UnaryClient) {
-    this.client = client;
+const childRel = (parent: ontology.ID, key: Key): ontology.Relationship => ({
+  from: parent,
+  type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+  to: ontologyID(key),
+});
+
+const matchChildRel = (rel: ontology.Relationship, parent: ontology.ID): boolean =>
+  ontology.matchRelationship(rel, {
+    from: parent,
+    type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+    to: { type: "schematic_symbol" },
+  });
+
+export interface ClientConfig {
+  unary: UnaryClient;
+  file: FileTransport;
+  ontology: ontology.Client;
+  cache: query.Cache;
+  groupStore: query.Table<group.Key, group.Group>;
+}
+
+export class Client extends query.Retriever<typeof retrieveMultiParamsZ, Key, Symbol> {
+  private readonly cfg: ClientConfig;
+  private readonly store: query.Table<Key, Symbol>;
+
+  constructor(cfg: ClientConfig) {
+    const { cache, ontology: ontologyClient } = cfg;
+    const store = cache.createTable<Key, Symbol>({
+      name: "schematicSymbols",
+      fetch: async (keys) => await this.execRetrieve({ keys }),
+      listen: [
+        query.createSetListener(SET_CHANNEL_NAME, symbolZ),
+        query.createDeleteListener(DELETE_CHANNEL_NAME, keyZ),
+      ],
+    });
+    super(cache, {
+      name: "schematic symbol",
+      table: store,
+      request: {
+        schema: retrieveMultiParamsZ,
+        fetch: async (req) => await this.fetchRequest(req),
+        matches: (sym, req) => this.requestFilter(req)(sym),
+        serverFields: SERVER_FIELDS,
+        watch: [
+          query.watch(
+            ontologyClient.cache.relationships,
+            (event, req: RetrieveRequest) => {
+              if (req.parent == null) return null;
+              const rel =
+                event.variant === "set"
+                  ? event.value
+                  : ontology.relationshipZ.parse(event.key);
+              if (!matchChildRel(rel, req.parent)) return null;
+              return [rel.to.key];
+            },
+          ),
+        ],
+      },
+    });
+    this.cfg = cfg;
+    this.store = store;
   }
 
-  async create(options: CreateArgs): Promise<Symbol>;
-  async create(options: CreateMultipleArgs): Promise<Symbol[]>;
-  async create(options: CreateArgs | CreateMultipleArgs): Promise<Symbol | Symbol[]> {
+  async create(options: CreateParams): Promise<Symbol>;
+  async create(options: CreateMultipleParams): Promise<Symbol[]>;
+  async create(
+    options: CreateParams | CreateMultipleParams,
+  ): Promise<Symbol | Symbol[]> {
     const isMany = "symbols" in options;
     const symbols = isMany ? options.symbols : [options];
-    const res = await this.client.send(
+    const res = await this.cfg.unary.send(
       "/schematic/symbol/create",
       { symbols, parent: options.parent },
       createReqZ,
       createResZ,
     );
+    // Relationships first: parent-scoped answers check membership when the
+    // symbol write lands.
+    const rels = this.cfg.ontology.cache.relationships;
+    res.symbols.forEach((s) => {
+      const rel = childRel(options.parent, s.key);
+      rels.set(ontology.relationshipToString(rel), rel);
+    });
+    this.store.set(res.symbols);
     return isMany ? res.symbols : res.symbols[0];
   }
 
-  async rename(key: Key, name: string): Promise<void> {
-    await this.client.send(
-      "/schematic/symbol/rename",
-      { key, name },
-      renameReqZ,
-      emptyResZ,
+  async rename(key: Key, name: string, opts: query.WriteOptions = {}): Promise<void> {
+    const rename = () => query.partialUpdate(this.store, key, { name });
+    await query.optimistic({
+      rollbacks: [rename()],
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/schematic/symbol/rename",
+          { key, name },
+          renameReqZ,
+          emptyResZ,
+        ),
+    });
+    rename();
+  }
+
+  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(
+          "/schematic/symbol/delete",
+          { keys: keysArr },
+          deleteReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
+    this.cfg.ontology.cache.relationships.delete(
+      (r) =>
+        r.type === ontology.PARENT_OF_RELATIONSHIP_TYPE &&
+        r.to.type === "schematic_symbol" &&
+        keysArr.includes(r.to.key),
     );
   }
 
-  async retrieve(args: RetrieveSingleParams): Promise<Symbol>;
-  async retrieve(args: RetrieveMultipleParams): Promise<Symbol[]>;
-  async retrieve(args: RetrieveArgs): Promise<Symbol | Symbol[]> {
-    const isSingle = "key" in args;
-    const res = await this.client.send(
-      "/schematic/symbol/retrieve",
-      args,
-      retrieveArgsZ,
-      retrieveResZ,
+  /**
+   * Exports every symbol in the group as a bundle: a zip archive holding one JSON file
+   * per symbol beside a manifest.json naming the group. Two symbols that take the same
+   * file name keep distinct names through a numeric suffix, and children that are not
+   * symbols are skipped. The caller pipes the stream wherever it likes without the
+   * client buffering the whole archive.
+   * @param options - the export options, including the serialization member files are
+   * written in.
+   * @returns the bundle as a stream of zip bytes.
+   */
+  async exportGroup(
+    key: group.Key,
+    options: imex.Options,
+  ): Promise<ReadableStream<Uint8Array>> {
+    return await this.cfg.file.download(
+      "/schematic/symbol/group/export",
+      { key, encoding: options.encoding },
+      exportGroupReqZ,
+      { encoding: "ZIP" },
     );
-    checkForMultipleOrNoResults("Schematic Symbol", args, res.symbols, isSingle);
-    return isSingle ? res.symbols[0] : res.symbols;
   }
 
-  async delete(keys: Key | Key[]): Promise<void> {
-    await this.client.send(
-      "/schematic/symbol/delete",
-      { keys: array.toArray(keys) },
-      deleteReqZ,
-      emptyResZ,
+  /**
+   * Imports a symbol group bundle: a zip archive holding one JSON envelope per symbol
+   * beside a manifest.json naming the group. The Core creates a fresh group under the
+   * permanent symbol group and imports every member in a single transaction, so a
+   * failure leaves nothing behind.
+   * @returns the created group.
+   * @throws {ValidationError} if the manifest is missing, malformed, or of another
+   * bundle kind, if two member names collide, or if a member is not a symbol.
+   */
+  async importGroup(data: UploadBody): Promise<group.Group> {
+    const res = await this.cfg.file.upload(
+      "/schematic/symbol/group/import",
+      data,
+      { encoding: "ZIP" },
+      importGroupResZ,
     );
+    const parent = await this.retrieveGroup();
+    this.cfg.groupStore.set(res.group);
+    const rel: ontology.Relationship = {
+      from: group.ontologyID(parent.key),
+      type: ontology.PARENT_OF_RELATIONSHIP_TYPE,
+      to: group.ontologyID(res.group.key),
+    };
+    this.cfg.ontology.cache.relationships.set(ontology.relationshipToString(rel), rel);
+    return res.group;
+  }
+
+  /**
+   * Deletes the group and every symbol in it. The Core removes both in a single
+   * transaction, so a failure leaves the group and its symbols untouched. A child that
+   * is not a symbol survives: the Core moves it to the permanent symbol group.
+   */
+  async deleteGroup(key: group.Key, opts: query.WriteOptions = {}): Promise<void> {
+    const groupID = group.ontologyID(key);
+    const rels = this.cfg.ontology.cache.relationships;
+    // Read the members before the delete drops the relationships naming them.
+    const memberKeys = rels.get((r) => matchChildRel(r, groupID)).map((r) => r.to.key);
+    const drop = () => [
+      this.store.delete(memberKeys),
+      this.cfg.groupStore.delete(key),
+      // Both the relationships to the group's children and the one naming the group as
+      // its parent's child: the group and every symbol in it are gone.
+      rels.delete(
+        (r) =>
+          r.type === ontology.PARENT_OF_RELATIONSHIP_TYPE &&
+          (ontology.idsEqual(r.from, groupID) || ontology.idsEqual(r.to, groupID)),
+      ),
+    ];
+    await query.optimistic({
+      rollbacks: drop(),
+      onOptimistic: opts.onOptimistic,
+      commit: async () =>
+        await this.cfg.unary.send(
+          "/schematic/symbol/group/delete",
+          { key },
+          deleteGroupReqZ,
+          emptyResZ,
+        ),
+    });
+    drop();
   }
 
   async retrieveGroup(): Promise<group.Group> {
-    const res = await this.client.send(
+    const res = await this.cfg.unary.send(
       "/schematic/symbol/retrieve-group",
       {},
       retrieveGroupReqZ,
@@ -122,4 +299,56 @@ export class Client {
     );
     return res.group;
   }
+
+  private async execRetrieve(
+    params: RetrieveSingleParams | z.input<typeof wireRetrieveRequestZ>,
+  ): Promise<Symbol[]> {
+    const res = await this.cfg.unary.send(
+      "/schematic/symbol/retrieve",
+      params,
+      retrieveParamsZ,
+      retrieveResZ,
+    );
+    return res.symbols;
+  }
+
+  /** Resolves a parent scope to its symbol children's keys via the ontology. */
+  private async resolveChildKeys(parent: ontology.ID): Promise<Key[]> {
+    // The children space writes the parent relationships through, so
+    // membership checks in requestFilter see them.
+    const children = await this.cfg.ontology.children.retrieve({
+      ids: parent,
+      types: ["schematic_symbol"],
+    });
+    return children.map(({ id: { key } }) => key);
+  }
+
+  private async fetchRequest(req: RetrieveRequest): Promise<Symbol[]> {
+    const { parent, ...rest } = req;
+    if (parent == null) return await this.execRetrieve(rest);
+    const keys = await this.resolveChildKeys(parent);
+    if (keys.length === 0) return [];
+    if (primitive.isZero(rest.searchTerm)) return await this.store.retrieve(keys);
+    return await this.execRetrieve({ keys, searchTerm: rest.searchTerm });
+  }
+
+  /**
+   * Client-side matching for a request: exact for key sets and parent
+   * membership via the relationship table. Server-computed shapes (search)
+   * never reach this filter; they refetch instead.
+   */
+  private requestFilter(req: RetrieveRequest): (s: Symbol) => boolean {
+    const keySet = primitive.isNonZero(req.keys) ? new Set(req.keys) : undefined;
+    return (s) => {
+      if (keySet != null && !keySet.has(s.key)) return false;
+      if (req.parent != null && !this.isChildOf(req.parent, s.key)) return false;
+      return true;
+    };
+  }
+
+  private isChildOf(parent: ontology.ID, key: Key): boolean {
+    return this.cfg.ontology.cache.relationships.has(
+      ontology.relationshipToString(childRel(parent, key)),
+    );
+  }
 }

package/src/schematic/symbol/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, spatial } from "@synnaxlabs/x";
+import { color, spatial, uuid } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
@@ -24,11 +24,14 @@ export const regionZ = z.object({
   /** name is a human-readable name for the region. */
   name: z.string(),
   /** selectors contains CSS selectors targeting SVG elements within the symbol. */
-  selectors: array.nullishToEmpty(z.string()),
-  /** strokeColor is an optional stroke color in hex format (#RRGGBB). */
-  strokeColor: z.string().optional(),
-  /** fillColor is an optional fill color in hex format (#RRGGBB). */
-  fillColor: z.string().optional(),
+  selectors: z
+    .string()
+    .array()
+    .default(() => []),
+  /** strokeColor is an optional stroke color override for the region. */
+  strokeColor: color.colorZ.optional(),
+  /** fillColor is an optional fill color override for the region. */
+  fillColor: color.colorZ.optional(),
 });
 export interface Region extends z.infer<typeof regionZ> {}
 
@@ -53,7 +56,7 @@ export const stateZ = z.object({
   /** name is a human-readable name for this state. */
   name: z.string(),
   /** regions contains style regions defining visual appearance for this state. */
-  regions: array.nullishToEmpty(regionZ),
+  regions: regionZ.array().default(() => []),
 });
 export interface State extends z.infer<typeof stateZ> {}
 
@@ -65,51 +68,36 @@ export const specZ = z.object({
   /** svg is the SVG markup defining the symbol's visual geometry. */
   svg: z.string().min(1),
   /** states contains available visual states with regional styling configurations. */
-  states: array.nullishToEmpty(stateZ),
-  /** variant is the symbol variant or category identifier (e.g., 'sensor', 'valve'). */
+  states: stateZ.array().default(() => []),
+  /** variant is the symbol variant: 'static' or 'actuator'. */
   variant: z.string().min(1),
   /** handles contains connection points for linking to other diagram elements. */
-  handles: array.nullishToEmpty(handleZ),
+  handles: handleZ.array().default(() => []),
   /** scale is the symbol scale factor. */
   scale: z.number().default(1),
-  /** scaleStroke indicates whether stroke width scales with the symbol size. */
-  scaleStroke: z.boolean().default(false),
-  /** previewViewport is an optional viewport configuration for symbol preview rendering. */
+  /** strokeScaled is true when stroke width scales with the symbol size. */
+  strokeScaled: z.boolean().default(false),
+  /**
+   * previewViewport is an optional viewport configuration for symbol preview rendering.
+   */
   previewViewport: spatial.viewportZ.optional(),
 });
 export interface Spec extends z.infer<typeof specZ> {}
 
 /**
- * Symbol is a persisted schematic symbol with versioning, defining reusable visual
- * components for diagrams.
+ * Symbol is a persisted schematic symbol defining reusable visual components for
+ * diagrams.
  */
 export const symbolZ = z.object({
   /** key is the unique identifier for this symbol. */
-  key: keyZ,
-  /** version is the symbol schema version for migration support. */
-  version: z.uint32().default(1),
+  key: keyZ.default(uuid.create),
   /** name is a human-readable name for the symbol. */
   name: z.string().min(1),
   /** data is the complete symbol specification. */
   data: specZ,
 });
 export interface Symbol extends z.infer<typeof symbolZ> {}
-
-/** New contains parameters for creating a new schematic symbol. */
-export const newZ = z.object({
-  /**
-   * key is an optional key for the symbol. If not provided, one will be
-   * automatically assigned.
-   */
-  key: keyZ.optional(),
-  /** version is the symbol schema version. */
-  version: z.uint32().default(1),
-  /** name is a human-readable name for the symbol. */
-  name: z.string().min(1),
-  /** data is the complete symbol specification. */
-  data: specZ,
-});
-export interface New extends z.input<typeof newZ> {}
+export interface New extends z.input<typeof symbolZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("schematic_symbol");
 export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/schematic/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, caseconv, record, spatial, zod } from "@synnaxlabs/x";
+import { caseconv, record, spatial, uuid, zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { ontology } from "@/ontology";
@@ -21,23 +21,16 @@ export const nodeZ = z.object({
   /** position is the top-left position of the node. */
   position: spatial.xyZ,
   /**
-   * zIndex is the stacking order of the node within the schematic. Higher
-   * values render above lower values. Set by the user via
-   * send-to-back / bring-to-front actions.
+   * zIndex is the stacking order of the node within the schematic. Higher values render
+   * above lower values. Set by the user via send-to-back / bring-to-front actions.
    */
-  zIndex: zod.int16.optional(),
-  /**
-   * measured is the rendered pixel size of the node. Populated by the
-   * renderer after the node is mounted and used to keep diagram
-   * measurements consistent across re-renders.
-   */
-  measured: spatial.dimensionsZ.optional(),
+  zIndex: zod.int16.default(0),
 });
 export interface Node extends z.infer<typeof nodeZ> {}
 
 /**
- * Handle is a reference to a specific connection point on a specific node.
- * For schematics, param is the symbol handle key (e.g. inlet, outlet).
+ * Handle is a reference to a specific connection point on a specific node. For
+ * schematics, param is the symbol handle key (e.g. inlet, outlet).
  */
 export const handleZ = z.object({
   /** node is the node identifier. */
@@ -62,32 +55,32 @@ export const edgeZ = z.object({
 export interface Edge extends z.infer<typeof edgeZ> {}
 
 /**
- * Schematic is a visual diagram editor component for drawing system schematics,
- * control flows, and process diagrams. Schematics support interactive
- * symbols, connection handles, and dynamic state visualization.
+ * Schematic is a visual diagram editor component for drawing system schematics, control
+ * flows, and process diagrams. Schematics support interactive symbols, connection
+ * handles, and dynamic state visualization.
  */
 export const schematicZ = z.object({
   /** key is the unique identifier for this schematic. */
-  key: keyZ,
+  key: keyZ.default(uuid.create),
   /** name is a human-readable name for the schematic. */
-  name: z.string(),
-  /** snapshot indicates whether this schematic represents a saved snapshot state. */
-  snapshot: z.boolean(),
+  name: z.string().min(1, "name is required"),
+  /** snapshot is true if this schematic is an immutable snapshot copy. */
+  snapshot: z.boolean().default(false),
   /** nodes contains all diagram nodes in the schematic. */
-  nodes: array.nullishToEmpty(nodeZ),
+  nodes: nodeZ.array().default(() => []),
   /** edges contains all connections between nodes. */
-  edges: array.nullishToEmpty(edgeZ),
+  edges: edgeZ.array().default(() => []),
   /**
-   * configs contains per-element configuration keyed by node or edge key. The
-   * shape of each value is determined by the element's variant; the
-   * wire format intentionally stores it as an opaque record.
+   * configs contains per-element configuration keyed by node or edge key. The shape of
+   * each value is determined by the element's variant; the wire format intentionally
+   * stores it as an opaque record.
    */
-  configs: caseconv.preserveCase(record.nullishToEmpty(z.string(), record.unknownZ())),
+  configs: caseconv.preserveCase(
+    z.record(z.string(), record.unknownZ()).default(() => ({})),
+  ),
 });
 export interface Schematic extends z.infer<typeof schematicZ> {}
-
-export const newZ = schematicZ.partial({ key: true, snapshot: true });
-export interface New extends z.input<typeof newZ> {}
+export interface New extends z.input<typeof schematicZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("schematic");
 export const TYPE_ONTOLOGY_ID = ontologyID("");