@synnaxlabs/client 0.26.1 → 0.27.0

package/src/label/client.ts

@@ -8,13 +8,14 @@
 // included in the file licenses/APL.txt.
 
 import { type UnaryClient } from "@synnaxlabs/freighter";
+import { observe } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 
 import { type framer } from "@/framer";
 import { type Key, type Label, labelZ } from "@/label/payload";
 import { Retriever } from "@/label/retriever";
-import { type NewLabelPayload,Writer } from "@/label/writer";
-import { type ontology } from "@/ontology";
+import { type NewLabelPayload, SetOptions, Writer } from "@/label/writer";
+import { ontology } from "@/ontology";
 import { signals } from "@/signals";
 
 const LABEL_SET_NAME = "sy_label_set";
@@ -25,11 +26,17 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
   private readonly retriever: Retriever;
   private readonly writer: Writer;
   private readonly frameClient: framer.Client;
+  private readonly ontology: ontology.Client;
 
-  constructor(client: UnaryClient, frameClient: framer.Client) {
+  constructor(
+    client: UnaryClient,
+    frameClient: framer.Client,
+    ontology: ontology.Client,
+  ) {
     this.writer = new Writer(client);
     this.retriever = new Retriever(client);
     this.frameClient = frameClient;
+    this.ontology = ontology;
   }
 
   async search(term: string): Promise<Label[]> {
@@ -46,16 +53,20 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
     return isMany ? res : res[0];
   }
 
-  async retrieveFor(id: ontology.ID): Promise<Label[]> {
-    return await this.retriever.retrieveFor(id);
+  async retrieveFor(id: ontology.CrudeID): Promise<Label[]> {
+    return await this.retriever.retrieveFor(new ontology.ID(id));
   }
 
-  async label(id: ontology.ID, labels: Key[]): Promise<void> {
-    await this.writer.set(id, labels);
+  async label(
+    id: ontology.CrudeID,
+    labels: Key[],
+    opts: SetOptions = {},
+  ): Promise<void> {
+    await this.writer.set(new ontology.ID(id), labels, opts);
   }
 
-  async removeLabels(id: ontology.ID, labels: Key[]): Promise<void> {
-    await this.writer.remove(id, labels);
+  async removeLabels(id: ontology.CrudeID, labels: Key[]): Promise<void> {
+    await this.writer.remove(new ontology.ID(id), labels);
   }
 
   async page(offset: number, limit: number): Promise<Label[]> {
@@ -88,17 +99,36 @@ export class Client implements AsyncTermSearcher<string, Key, Label> {
       decodeChanges,
     );
   }
+
+  async trackLabelsOf(
+    id: ontology.CrudeID,
+  ): Promise<observe.ObservableAsyncCloseable<Label[]>> {
+    const wrapper = new observe.Observer<Label[]>();
+    const initial = (await this.retrieveFor(id)).map((l) => ({
+      id: new ontology.ID({ key: l.key, type: "label" }),
+      key: l.key,
+      name: l.name,
+      data: l,
+    }));
+    const base = await this.ontology.openDependentTracker(
+      new ontology.ID(id),
+      initial,
+      "labeled_by",
+    );
+    base.onChange((resources: ontology.Resource[]) =>
+      wrapper.notify(
+        resources.map((r) => ({
+          key: r.id.key,
+          color: r.data?.color as string,
+          name: r.data?.name as string,
+        })),
+      ),
+    );
+    return wrapper;
+  }
 }
 
 const decodeChanges: signals.Decoder<string, Label> = (variant, data) => {
-  if (variant === "delete")
-    return data.toUUIDs().map((v) => ({
-      variant,
-      key: v,
-    }));
-  return data.parseJSON(labelZ).map((l) => ({
-    variant,
-    key: l.key,
-    value: l,
-  }));
+  if (variant === "delete") return data.toUUIDs().map((v) => ({ variant, key: v }));
+  return data.parseJSON(labelZ).map((l) => ({ variant, key: l.key, value: l }));
 };

package/src/label/label.spec.ts

@@ -47,5 +47,14 @@ describe("Label", () => {
       expect(labels).toHaveLength(1);
       expect(labels[0].key).toEqual(l2.key);
     });
+    it("should replace the labels on an item", async () => {
+      const l1 = await client.labels.create({ name: "Label One", color: "#E774D)" });
+      const l2 = await client.labels.create({ name: "Label Two", color: "#E774D)" });
+      await client.labels.label(label.ontologyID(l1.key), [l2.key]);
+      await client.labels.label(label.ontologyID(l1.key), [l1.key], { replace: true });
+      const labels = await client.labels.retrieveFor(label.ontologyID(l1.key));
+      expect(labels).toHaveLength(1);
+      expect(labels[0].key).toEqual(l1.key);
+    });
   });
 });

package/src/label/retriever.ts

@@ -13,6 +13,7 @@ import { z } from "zod";
 
 import { keyZ, type Label, labelZ, type Params } from "@/label/payload";
 import { ontology } from "@/ontology";
+import { nullableArrayZ } from "@/util/zod";
 
 const reqZ = z.object({
   keys: keyZ.array().optional(),
@@ -25,7 +26,7 @@ const reqZ = z.object({
 type Request = z.infer<typeof reqZ>;
 
 const resZ = z.object({
-  labels: labelZ.array().optional().default([]),
+  labels: nullableArrayZ(labelZ),
 });
 
 export class Retriever {

package/src/label/writer.ts

@@ -33,9 +33,13 @@ const deleteReqZ = z.object({
 const setReqZ = z.object({
   id: ontology.idZ,
   labels: keyZ.array(),
+  replace: z.boolean().optional(),
 });
 
-const removeReqZ = setReqZ;
+type SetReq = z.infer<typeof setReqZ>;
+export type SetOptions = Pick<SetReq, "replace">;
+
+const removeReqZ = setReqZ.omit({ replace: true });
 
 const emptyResZ = z.object({});
 
@@ -72,11 +76,15 @@ export class Writer {
     );
   }
 
-  async set(id: ontology.ID, labels: Key[]): Promise<void> {
+  async set(
+    id: ontology.ID,
+    labels: Key[],
+    { replace }: SetOptions = {},
+  ): Promise<void> {
     await sendRequired<typeof setReqZ, typeof emptyResZ>(
       this.client,
       SET_ENDPOINT,
-      { id, labels },
+      { id, labels, replace },
       setReqZ,
       emptyResZ,
     );

package/src/ontology/client.ts

@@ -17,11 +17,13 @@ import { framer } from "@/framer";
 import { Frame } from "@/framer/frame";
 import { group } from "@/ontology/group";
 import {
+  CrudeID,
   ID,
   IDPayload,
   idZ,
   parseRelationship,
   RelationshipChange,
+  RelationshipDirection,
   type Resource,
   ResourceChange,
   resourceSchemaZ,
@@ -52,7 +54,7 @@ const retrieveResZ = z.object({
   resources: resourceSchemaZ.array(),
 });
 
-const parseIDs = (ids: ID | ID[] | string | string[]): IDPayload[] =>
+export const parseIDs = (ids: CrudeID | CrudeID[] | string | string[]): IDPayload[] =>
   toArray(ids).map((id) => new ID(id).payload);
 
 /** The core client class for executing queries against a Synnax cluster ontology */
@@ -70,16 +72,50 @@ export class Client implements AsyncTermSearcher<string, string, Resource> {
     this.framer = framer;
   }
 
+  /**
+   * Executes a fuzzy search on the ontology for resources with names/fields similar to the
+   * given term.
+   *
+   * @param term The search term.
+   * @param options Additional options for the search.
+   * @param options.includeSchema Whether to include the schema of the resources in the
+   * results.
+   * @param options.excludeFieldData Whether to exclude the field data of the resources in
+   * the results.
+   * @returns A list of resources that match the search term.
+   */
   async search(term: string, options?: RetrieveOptions): Promise<Resource[]> {
     return await this.execRetrieve({ term, ...options });
   }
 
-  async retrieve(id: ID | string, options?: RetrieveOptions): Promise<Resource>;
-
-  async retrieve(ids: ID[] | string[], options?: RetrieveOptions): Promise<Resource[]>;
+  /**
+   * Retrieves the resource in the ontology with the given ID.
+   * @param id The ID of the resource to retrieve.
+   * @param options Additional options for the retrieval.
+   * @param options.includeSchema Whether to include the schema of the resource in the
+   * results.
+   * @param options.excludeFieldData Whether to exclude the field data of the resource in
+   * the results.
+   * @returns The resource with the given ID.
+   * @throws {QueryError} If no resource is found with the given ID.
+   */
+  async retrieve(id: CrudeID, options?: RetrieveOptions): Promise<Resource>;
+
+  /**
+   * Retrieves the resources in the ontology with the given IDs.
+   * @param ids The IDs of the resources to retrieve.
+   * @param options Additional options for the retrieval.
+   * @param options.includeSchema Whether to include the schema of the resources in the
+   * results.
+   * @param options.excludeFieldData Whether to exclude the field data of the resources in
+   * the results.
+   * @returns The resources with the given IDs.
+   * @throws {QueryError} If no resource is found with any of the given IDs.
+   */
+  async retrieve(ids: CrudeID[], options?: RetrieveOptions): Promise<Resource[]>;
 
   async retrieve(
-    ids: ID | ID[] | string | string[],
+    ids: CrudeID | CrudeID[],
     options?: RetrieveOptions,
   ): Promise<Resource | Resource[]> {
     const resources = await this.execRetrieve({ ids: parseIDs(ids), ...options });
@@ -89,6 +125,15 @@ export class Client implements AsyncTermSearcher<string, string, Resource> {
     return resources[0];
   }
 
+  /**
+   * Retrieves resources from the ontology in a paginated manner.
+   *
+   * @param offset - The offset of the page (i.e. how many resources to skip before
+   * returning results).
+   * @param limit - The maximum number of resources to return.
+   * @param options - Additional options for the retrieval.
+   * @returns A list of resources in the ontology.
+   */
   async page(
     offset: number,
     limit: number,
@@ -97,36 +142,98 @@ export class Client implements AsyncTermSearcher<string, string, Resource> {
     return await this.execRetrieve({ offset, limit, ...options });
   }
 
+  /**
+   * Retrieves the children of the resources with the given IDs.
+   * @param ids - The IDs of the resources whose children to retrieve.
+   * @param options - Additional options for the retrieval.
+   * @param options.includeSchema - Whether to include the schema of the children in the
+   * results.
+   * @param options.excludeFieldData - Whether to exclude the field data of the children in
+   * the results.
+   * @returns The children of the resources with the given IDs.
+   */
   async retrieveChildren(
-    ids: ID | ID[],
+    ids: CrudeID | CrudeID[],
     options?: RetrieveOptions,
   ): Promise<Resource[]> {
     return await this.execRetrieve({ ids: parseIDs(ids), children: true, ...options });
   }
 
+  /**
+   * Retrieves the parents of the resources with the given IDs.
+   *
+   * @param ids the IDs of the resources whose parents to retrieve
+   * @param options additional options for the retrieval
+   * @param options.includeSchema whether to include the schema of the parents in the results
+   * @param options.excludeFieldData whether to exclude the field data of the parents in the results
+   * @returns the parents of the resources with the given IDs
+   */
   async retrieveParents(
-    ids: ID | ID[],
+    ids: CrudeID | CrudeID[],
     options?: RetrieveOptions,
   ): Promise<Resource[]> {
     return await this.execRetrieve({ ids: parseIDs(ids), parents: true, ...options });
   }
 
-  async addChildren(id: ID, ...children: ID[]): Promise<void> {
+  /**
+   * Adds children to a resource in the ontology.
+   * @param id The ID of the resource to add children to.
+   * @param children The IDs of the children to add.
+   */
+  async addChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     return await this.writer.addChildren(id, ...children);
   }
 
-  async removeChildren(id: ID, ...children: ID[]): Promise<void> {
+  /**
+   * Removes children from a resource in the ontology.
+   * @param id The ID of the resource to remove children from.
+   * @param children The IDs of the children
+   * to remove.
+   */
+  async removeChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     return await this.writer.removeChildren(id, ...children);
   }
 
-  async moveChildren(from: ID, to: ID, ...children: ID[]): Promise<void> {
+  /**
+   * Moves children from one resource to another in the ontology.
+   * @param from The ID of the resource to move children from.
+   * @param to The ID of the resource to move children to.
+   * @param children The IDs of the children to move.
+   */
+  async moveChildren(
+    from: CrudeID,
+    to: CrudeID,
+    ...children: CrudeID[]
+  ): Promise<void> {
     return await this.writer.moveChildren(from, to, ...children);
   }
 
+  /**
+   * Opens an observable that can be used to subscribe to changes in both the ontology's
+   * resources and relationships.
+   * @see ChangeTracker for more information.
+   * @returns An observable that emits changes to the ontology's resources and relationships.
+   */
   async openChangeTracker(): Promise<ChangeTracker> {
     return await ChangeTracker.open(this.framer, this);
   }
 
+  async openDependentTracker(
+    parent: ID,
+    initial: Resource[],
+    type: string = "parent",
+    direction: RelationshipDirection = "from",
+  ): Promise<observe.ObservableAsyncCloseable<Resource[]>> {
+    return await DependentTracker.open(
+      parent,
+      this,
+      this.framer,
+      initial,
+      type,
+      direction,
+    );
+  }
+
   newSearcherWithOptions(
     options: RetrieveOptions,
   ): AsyncTermSearcher<string, string, Resource> {
@@ -155,13 +262,21 @@ const RESOURCE_DELETE_NAME = "sy_ontology_resource_delete";
 const RELATIONSHIP_SET_NAME = "sy_ontology_relationship_set";
 const RELATIONSHIP_DELETE_NAME = "sy_ontology_relationship_delete";
 
+/**
+ * A class that tracks changes to the ontology's resources and relationships.
+ */
 export class ChangeTracker {
-  private readonly resourceObs: observe.Observer<ResourceChange[]>;
-  private readonly relationshipObs: observe.Observer<RelationshipChange[]>;
-
+  /**
+   * An observable that emits changes to the ontology's relationships.
+   */
   readonly relationships: observe.Observable<RelationshipChange[]>;
+  /**
+   * An observable that emits changes to the ontology's resources.
+   */
   readonly resources: observe.Observable<ResourceChange[]>;
 
+  private readonly resourceObs: observe.Observer<ResourceChange[]>;
+  private readonly relationshipObs: observe.Observer<RelationshipChange[]>;
   private readonly streamer: framer.Streamer;
   private readonly client: Client;
   private readonly closePromise: Promise<void>;
@@ -256,3 +371,89 @@ export class ChangeTracker {
     return new ChangeTracker(streamer, retriever);
   }
 }
+
+/**
+ * A class that tracks a resource (called the 'target' resource) and related resources
+ * (called 'dependents') of a particular type (called the 'type') in a Synnax cluster
+ * ontology.
+ */
+export class DependentTracker
+  extends observe.Observer<Resource[]>
+  implements observe.ObservableAsyncCloseable<Resource[]>
+{
+  private readonly internal: ChangeTracker;
+  private readonly target: ID;
+  private readonly direction: RelationshipDirection;
+  private dependents: Resource[];
+  private readonly client: Client;
+  private readonly type: string;
+
+  private constructor(
+    target: ID,
+    internal: ChangeTracker,
+    dependents: Resource[],
+    client: Client,
+    type: string = "parent",
+    direction: RelationshipDirection = "from",
+  ) {
+    super();
+    this.internal = internal;
+    this.target = target;
+    this.dependents = dependents;
+    this.client = client;
+    this.type = type;
+    this.direction = direction;
+    this.internal.resources.onChange(this.handleResourceChange);
+    this.internal.relationships.onChange(this.handleRelationshipChange);
+  }
+  static async open(
+    from: ID,
+    client: Client,
+    framer: framer.Client,
+    initial: Resource[],
+    type: string = "parent",
+    direction: RelationshipDirection = "from",
+  ): Promise<DependentTracker> {
+    const internal = await ChangeTracker.open(framer, client);
+    return new DependentTracker(from, internal, initial, client, type, direction);
+  }
+
+  private handleResourceChange = (changes: ResourceChange[]): void => {
+    this.dependents = this.dependents.map((child) => {
+      const change = changes.find((c) => c.key.toString() == child.id.toString());
+      if (change == null || change.variant === "delete") return child;
+      return change.value;
+    });
+    this.notify(this.dependents);
+  };
+
+  private handleRelationshipChange = (changes: RelationshipChange[]): void => {
+    const deletes = changes.filter(
+      (c) =>
+        c.variant === "delete" &&
+        c.key[this.direction].toString() === this.target.toString(),
+    );
+    this.dependents = this.dependents.filter(
+      (child) =>
+        !deletes.some(
+          (del) =>
+            del.key.to.toString() === child.id.toString() && del.key.type === this.type,
+        ),
+    );
+    const sets = changes.filter(
+      (c) =>
+        c.variant === "set" &&
+        c.key.type === this.type &&
+        c.key[this.direction].toString() === this.target.toString(),
+    );
+    if (sets.length === 0) return this.notify(this.dependents);
+    this.client.retrieve(sets.map((s) => s.key.to)).then((resources) => {
+      this.dependents = this.dependents.concat(resources);
+      this.notify(this.dependents);
+    });
+  };
+
+  async close(): Promise<void> {
+    await this.internal.close();
+  }
+}

package/src/ontology/payload.ts

@@ -53,6 +53,8 @@ export const stringIDZ = z.string().transform((v) => {
 
 export const crudeIDZ = z.union([stringIDZ, idZ]);
 
+export type CrudeID = { type: ResourceType; key: string } | string;
+
 export class ID {
   type: ResourceType;
   key: string;
@@ -119,6 +121,8 @@ export type Resource<T extends UnknownRecord = UnknownRecord> = Omit<
   "data"
 > & { data?: T | null };
 
+export type RelationshipDirection = "from" | "to";
+
 export const relationshipSchemaZ = z.object({
   from: ID.z,
   type: z.string(),

package/src/ontology/writer.ts

@@ -10,7 +10,7 @@
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { type ID,idZ } from "@/ontology/payload";
+import { type CrudeID, ID, idZ } from "@/ontology/payload";
 
 const ENDPOINTS = {
   ADD_CHILDREN: "/ontology/add-children",
@@ -36,28 +36,42 @@ export class Writer {
     this.client = client;
   }
 
-  async addChildren(id: ID, ...children: ID[]): Promise<void> {
+  async addChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     await sendRequired<typeof addRemoveChildrenReqZ, z.ZodTypeAny>(
-      this.client, 
-      ENDPOINTS.ADD_CHILDREN, 
-      { id, children },
-      addRemoveChildrenReqZ, 
-      z.object({})
+      this.client,
+      ENDPOINTS.ADD_CHILDREN,
+      { id: new ID(id).payload, children: children.map((c) => new ID(c).payload) },
+      addRemoveChildrenReqZ,
+      z.object({}),
     );
   }
 
-  async removeChildren(id: ID, ...children: ID[]): Promise<void> {
+  async removeChildren(id: CrudeID, ...children: CrudeID[]): Promise<void> {
     await sendRequired<typeof addRemoveChildrenReqZ, z.ZodTypeAny>(
       this.client,
       ENDPOINTS.REMOVE_CHILDREN,
-      { id, children },
+      { id: new ID(id).payload, children: children.map((c) => new ID(c).payload) },
       addRemoveChildrenReqZ,
       z.object({}),
     );
   }
 
-  async moveChildren(from: ID, to: ID, ...children: ID[]): Promise<void> {
-    const req = { from, to, children };
-    await sendRequired(this.client, ENDPOINTS.MOVE_CHILDREN, req, moveChildrenReqZ, z.object({}));
+  async moveChildren(
+    from: CrudeID,
+    to: CrudeID,
+    ...children: CrudeID[]
+  ): Promise<void> {
+    const req = {
+      from: new ID(from).payload,
+      to: new ID(to).payload,
+      children: children.map((c) => new ID(c).payload),
+    };
+    await sendRequired(
+      this.client,
+      ENDPOINTS.MOVE_CHILDREN,
+      req,
+      moveChildrenReqZ,
+      z.object({}),
+    );
   }
 }