@synnaxlabs/client 0.26.7 → 0.28.0

package/src/hardware/task/payload.ts

@@ -1,3 +1,12 @@
+// Copyright 2024 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
 import { binary, observe, UnknownRecord } from "@synnaxlabs/x";
 import { z } from "zod";
 
@@ -46,6 +55,7 @@ export const taskZ = z.object({
     }),
   ) as z.ZodType<UnknownRecord>,
   state: stateZ.optional().nullable(),
+  snapshot: z.boolean().optional(),
 });
 
 export const newTaskZ = taskZ.omit({ key: true }).extend({

package/src/hardware/task/task.spec.ts

@@ -44,46 +44,61 @@ describe("Hardware", () => {
         expect(retrieved.config).toStrictEqual({ a: "dog" });
         expect(retrieved.type).toBe("ni");
       });
-    });
-    describe("retrieveByName", () => {
-      it("should retrieve a task by its name", async () => {
-        const name = `test-${Date.now()}-${Math.random()}`;
-        const r = await client.hardware.racks.create({ name });
-        const m = await r.createTask({
-          name,
-          config: { a: "dog" },
-          type: "ni",
+      describe("retrieveByName", () => {
+        it("should retrieve a task by its name", async () => {
+          const name = `test-${Date.now()}-${Math.random()}`;
+          const r = await client.hardware.racks.create({ name });
+          const m = await r.createTask({
+            name,
+            config: { a: "dog" },
+            type: "ni",
+          });
+          const retrieved = await client.hardware.tasks.retrieveByName(name);
+          expect(retrieved.key).toBe(m.key);
+        });
+      });
+      describe("retrieve with state", () => {
+        it("should also send the tasks state", async () => {
+          const r = await client.hardware.racks.create({ name: "test" });
+          const t = await r.createTask({
+            name: "test",
+            config: { a: "dog" },
+            type: "ni",
+          });
+          const w = await client.openWriter(["sy_task_state"]);
+          interface StateDetails {
+            dog: string;
+          }
+          const state: task.State<StateDetails> = {
+            key: id.id(),
+            task: t.key,
+            variant: "success",
+          };
+          expect(await w.write("sy_task_state", [state])).toBeTruthy();
+          await w.close();
+          const retrieved = await client.hardware.tasks.retrieve(t.key, {
+            includeState: true,
+          });
+          expect(retrieved.state).not.toBeNull();
+          expect(retrieved.state?.variant).toBe(state.variant);
         });
-        const retrieved = await client.hardware.tasks.retrieveByName(name);
-        expect(retrieved.key).toBe(m.key);
       });
     });
-    describe("retrieve with state", () => {
-      it("should also send the tasks state", async () => {
+
+    describe("copy", () => {
+      it("should correctly copy the task", async () => {
         const r = await client.hardware.racks.create({ name: "test" });
-        const t = await r.createTask({
+        const m = await r.createTask({
           name: "test",
           config: { a: "dog" },
           type: "ni",
         });
-        const w = await client.openWriter(["sy_task_state"]);
-        interface StateDetails {
-          dog: string;
-        }
-        const state: task.State<StateDetails> = {
-          key: id.id(),
-          task: t.key,
-          variant: "success",
-        };
-        expect(await w.write("sy_task_state", [state])).toBeTruthy();
-        await w.close();
-        const retrieved = await client.hardware.tasks.retrieve(t.key, {
-          includeState: true,
-        });
-        expect(retrieved.state).not.toBeNull();
-        expect(retrieved.state?.variant).toBe(state.variant);
+        const copy = await client.hardware.tasks.copy(m.key, "New Name", false);
+        expect(copy.name).toBe("New Name");
+        expect(copy.config).toStrictEqual({ a: "dog" });
       });
     });
+
     describe("list", () => {
       it("should list all tasks", async () => {
         const t = await client.hardware.racks.create({ name: "test" });

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({
+      target: new ontology.ID(id),
+      dependents: initial,
+      relationshipType: "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,14 +17,17 @@ 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,
+  resourceTypeZ,
 } from "@/ontology/payload";
 import { Writer } from "@/ontology/writer";
 
@@ -39,20 +42,21 @@ const retrieveReqZ = z.object({
   term: z.string().optional(),
   limit: z.number().optional(),
   offset: z.number().optional(),
+  types: resourceTypeZ.array().optional(),
 });
 
 type RetrieveRequest = z.infer<typeof retrieveReqZ>;
 
 export type RetrieveOptions = Pick<
   RetrieveRequest,
-  "includeSchema" | "excludeFieldData"
+  "includeSchema" | "excludeFieldData" | "types"
 >;
 
 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 +74,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 +127,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 +144,88 @@ 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(
+    props: DependentTrackerProps,
+  ): Promise<observe.ObservableAsyncCloseable<Resource[]>> {
+    return await DependentTracker.open(props, this.framer, this);
+  }
+
   newSearcherWithOptions(
     options: RetrieveOptions,
   ): AsyncTermSearcher<string, string, Resource> {
@@ -155,13 +254,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 +363,109 @@ export class ChangeTracker {
     return new ChangeTracker(streamer, retriever);
   }
 }
+
+const oppositeDirection = (dir: RelationshipDirection): RelationshipDirection =>
+  dir === "from" ? "to" : "from";
+
+interface DependentTrackerProps {
+  target: ID;
+  dependents: Resource[];
+  relationshipType?: string;
+  relationshipDirection?: RelationshipDirection;
+  resourceType?: string;
+}
+
+/**
+ * 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 relDir: RelationshipDirection;
+  private readonly resourceType?: string;
+  private dependents: Resource[];
+  private readonly client: Client;
+  private readonly relType: string;
+
+  private constructor(
+    {
+      target,
+      dependents,
+      relationshipType = "parent",
+      relationshipDirection = "from",
+      resourceType,
+    }: DependentTrackerProps,
+    internal: ChangeTracker,
+    client: Client,
+  ) {
+    super();
+    this.resourceType = resourceType;
+    this.internal = internal;
+    this.target = target;
+    this.dependents = dependents;
+    if (this.resourceType != null)
+      this.dependents = this.dependents.filter((r) => r.id.type === this.resourceType);
+    this.client = client;
+    this.relType = relationshipType;
+    this.relDir = relationshipDirection;
+    this.internal.resources.onChange(this.handleResourceChange);
+    this.internal.relationships.onChange(this.handleRelationshipChange);
+  }
+  static async open(
+    props: DependentTrackerProps,
+    framer: framer.Client,
+    client: Client,
+  ): Promise<DependentTracker> {
+    const internal = await ChangeTracker.open(framer, client);
+    return new DependentTracker(props, internal, client);
+  }
+
+  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.relDir].toString() === this.target.toString() &&
+        (this.resourceType == null ||
+          c.key[oppositeDirection(this.relDir)].type === this.resourceType),
+    );
+    this.dependents = this.dependents.filter(
+      (child) =>
+        !deletes.some(
+          (del) =>
+            del.key.to.toString() === child.id.toString() &&
+            del.key.type === this.relType,
+        ),
+    );
+    const sets = changes.filter(
+      (c) =>
+        c.variant === "set" &&
+        c.key.type === this.relType &&
+        c.key[this.relDir].toString() === this.target.toString() &&
+        (this.resourceType == null ||
+          c.key[oppositeDirection(this.relDir)].type === this.resourceType),
+    );
+    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/group/writer.ts

@@ -7,10 +7,10 @@
 // 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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { z } from "zod";
 
-import { groupZ,type Payload } from "@/ontology/group/payload";
+import { groupZ, type Payload } from "@/ontology/group/payload";
 import { type ID, idZ } from "@/ontology/payload";
 
 const resZ = z.object({
@@ -43,35 +43,33 @@ export class Writer {
   }
 
   async create(parent: ID, name: string, key?: string): Promise<Payload> {
-    const [res, err] = await this.client.send(
+    const res = await sendRequired(
+      this.client,
       Writer.ENDPOINT,
       { parent, name, key },
       createReqZ,
       resZ,
     );
-    if (err != null) throw err;
     return res.group;
   }
 
   async rename(key: string, name: string): Promise<void> {
-    const req = { key, name };
-    const [, err] = await this.client.send(
+    await sendRequired(
+      this.client,
       Writer.ENDPOINT_RENAME,
-      req,
+      { key, name },
       renameReqZ,
       z.object({}),
     );
-    if (err != null) throw err;
   }
 
   async delete(keys: string[]): Promise<void> {
-    const req = { keys };
-    const [, err] = await this.client.send(
+    await sendRequired(
+      this.client,
       Writer.ENDPOINT_DELETE,
-      req,
+      { keys },
       deleteReqZ,
       z.object({}),
     );
-    if (err != null) throw err;
   }
 }