@synnaxlabs/client 0.2.1 → 0.13.6

package/src/ontology/client.ts

@@ -0,0 +1,104 @@
+// Copyright 2023 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 { type UnaryClient } from "@synnaxlabs/freighter";
+import { type AsyncTermSearcher } from "@synnaxlabs/x";
+
+import { type Client as FrameClient } from "@/framer/client";
+import { group } from "@/ontology/group";
+import { type ID, type Resource } from "@/ontology/payload";
+import { Retriever } from "@/ontology/retriever";
+import { Writer } from "@/ontology/writer";
+
+import { QueryError } from "..";
+
+import { ChangeTracker } from "@/ontology/signals";
+
+/** The core client class for executing queries against a Synnax cluster ontology */
+export class Client implements AsyncTermSearcher<string, string, Resource> {
+  groups: group.Client;
+  retriever: Retriever;
+  private readonly writer: Writer;
+  private readonly framer: FrameClient;
+
+  constructor(unary: UnaryClient, framer: FrameClient) {
+    this.retriever = new Retriever(unary);
+    this.writer = new Writer(unary);
+    this.groups = new group.Client(unary);
+    this.framer = framer;
+  }
+
+  async search(term: string): Promise<Resource[]> {
+    return await this.retriever.search(term);
+  }
+
+  async retrieve(
+    id: ID | string,
+    includeSchema?: boolean,
+    includeFieldData?: boolean,
+  ): Promise<Resource>;
+
+  async retrieve(
+    ids: ID[] | string[],
+    includeSchema?: boolean,
+    includeFieldData?: boolean,
+  ): Promise<Resource[]>;
+
+  async retrieve(
+    ids: ID | ID[] | string | string[],
+    includeSchema?: boolean,
+    includeFieldData?: boolean,
+  ): Promise<Resource | Resource[]> {
+    const resources = await this.retriever.retrieve(
+      ids,
+      includeSchema,
+      includeFieldData,
+    );
+    if (Array.isArray(ids)) return resources;
+    if (resources.length === 0)
+      throw new QueryError(`No resource found with ID ${ids.toString()}`);
+    return resources[0];
+  }
+
+  async page(offset: number, limit: number): Promise<Resource[]> {
+    return [];
+  }
+
+  async retrieveChildren(
+    IDs: ID | ID[],
+    includeSchema?: boolean,
+    includeFieldData?: boolean,
+  ): Promise<Resource[]> {
+    return await this.retriever.retrieveChildren(IDs, includeSchema, includeFieldData);
+  }
+
+  async retrieveParents(
+    IDs: ID | ID[],
+    includeSchema?: boolean,
+    includeFieldData?: boolean,
+  ): Promise<Resource[]> {
+    return await this.retriever.retrieveParents(IDs, includeSchema, includeFieldData);
+  }
+
+  async addChildren(id: ID, ...children: ID[]): Promise<void> {
+    return await this.writer.addChildren(id, ...children);
+  }
+
+  async removeChildren(id: ID, ...children: ID[]): Promise<void> {
+    return await this.writer.removeChildren(id, ...children);
+  }
+
+  async moveChildren(from: ID, to: ID, ...children: ID[]): Promise<void> {
+    return await this.writer.moveChildren(from, to, ...children);
+  }
+
+  async openChangeTracker(): Promise<ChangeTracker> {
+    return await ChangeTracker.open(this.framer, this.retriever);
+  }
+}

package/src/ontology/external.ts

@@ -0,0 +1,12 @@
+// Copyright 2023 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.
+
+export * from "@/ontology/client";
+export * from "@/ontology/payload";
+export * from "@/ontology/signals";

package/src/ontology/group/client.ts

@@ -0,0 +1,40 @@
+// Copyright 2023 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 { type UnaryClient } from "@synnaxlabs/freighter";
+
+import { type ID } from "@/ontology/payload";
+
+import { Group } from "./group";
+import { type Payload } from "./payload";
+import { Writer } from "./writer";
+
+export class Client {
+  private readonly creator: Writer;
+
+  constructor(unary: UnaryClient) {
+    this.creator = new Writer(unary);
+  }
+
+  async create(parent: ID, name: string): Promise<Group> {
+    return this.sugar(await this.creator.create(parent, name));
+  }
+
+  async rename(key: string, name: string): Promise<void> {
+    return await this.creator.rename(key, name);
+  }
+
+  async delete(...keys: string[]): Promise<void> {
+    return await this.creator.delete(keys);
+  }
+
+  private sugar(payload: Payload): Group {
+    return new Group(payload.name, payload.key);
+  }
+}

package/src/ontology/group/external.ts

@@ -0,0 +1,11 @@
+// Copyright 2023 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.
+
+export * from "@/ontology/group/group";
+export * from "@/ontology/group/client";

package/src/ontology/group/group.spec.ts

@@ -0,0 +1,46 @@
+// Copyright 2023 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 { describe, it, expect } from "vitest";
+
+import { QueryError } from "@/errors";
+import { ontology } from "@/ontology";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+describe("Group", () => {
+  describe("create", () => {
+    it("should correctly create a group", async () => {
+      const name = `group-${Math.random()}`;
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      expect(g.name).toEqual(name);
+    });
+  });
+  describe("rename", () => {
+    it("should correctly rename a group", async () => {
+      const name = `group-${Math.random()}`;
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const newName = `group-${Math.random()}`;
+      await client.ontology.groups.rename(g.key, newName);
+      const g2 = await client.ontology.retrieve(g.ontologyID);
+      expect(g2.name).toEqual(newName);
+    });
+  });
+  describe("delete", () => {
+    it("should correctly delete the group", async () => {
+      const name = `group-${Math.random()}`;
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      await client.ontology.groups.delete(g.key);
+      await expect(
+        async () => await client.ontology.retrieve(g.ontologyID),
+      ).rejects.toThrow(QueryError);
+    });
+  });
+});

package/src/ontology/group/group.ts

@@ -0,0 +1,27 @@
+// Copyright 2023 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 { ontology } from "@/ontology";
+
+export class Group {
+  key: string;
+  name: string;
+
+  constructor(name: string, key: string) {
+    this.key = key;
+    this.name = name;
+  }
+
+  get ontologyID(): ontology.ID {
+    return new ontology.ID({
+      type: "group",
+      key: this.key,
+    });
+  }
+}

package/src/ontology/group/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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.
+
+export * as group from "@/ontology/group/external";

package/src/ontology/group/payload.ts

@@ -0,0 +1,65 @@
+// Copyright 2023 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 { toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+export const keyZ = z.string().uuid();
+export type Key = z.infer<typeof keyZ>;
+export type Name = string;
+export type Keys = Key[];
+export type Names = Name[];
+export type Params = Key | Name | Keys | Names;
+
+export const payloadZ = z.object({
+  key: keyZ,
+  name: z.string(),
+});
+
+export type Payload = z.infer<typeof payloadZ>;
+
+export type ParamAnalysisResult =
+  | {
+      single: true;
+      variant: "keys";
+      normalized: Keys;
+      actual: Key;
+    }
+  | {
+      single: true;
+      variant: "names";
+      normalized: Names;
+      actual: Name;
+    }
+  | {
+      single: false;
+      variant: "keys";
+      normalized: Keys;
+      actual: Keys;
+    }
+  | {
+      single: false;
+      variant: "names";
+      normalized: Names;
+      actual: Names;
+    };
+
+export const analyzeParams = (params: Params): ParamAnalysisResult => {
+  const normal = toArray(params) as Keys | Names;
+  if (normal.length === 0) {
+    throw new Error("No groups specified");
+  }
+  const isKey = keyZ.safeParse(normal[0]).success;
+  return {
+    single: !Array.isArray(params),
+    variant: isKey ? "keys" : "names",
+    normalized: normal,
+    actual: params,
+  } as const as ParamAnalysisResult;
+};

package/src/ontology/group/writer.ts

@@ -0,0 +1,48 @@
+// Copyright 2023 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 { type UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import { type Payload, payloadZ } from "@/ontology/group/payload";
+import { type ID } from "@/ontology/payload";
+
+const resZ = z.object({
+  group: payloadZ,
+});
+
+export class Writer {
+  private static readonly ENDPOINT = "/ontology/create-group";
+  private static readonly ENDPOINT_RENAME = "/ontology/rename-group";
+  private static readonly ENDPOINT_DELETE = "/ontology/delete-group";
+  client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async create(parent: ID, name: string): Promise<Payload> {
+    const req = { parent, name };
+    const [res, err] = await this.client.send(Writer.ENDPOINT, req, 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(Writer.ENDPOINT_RENAME, req, z.object({}));
+    if (err != null) throw err;
+  }
+
+  async delete(keys: string[]): Promise<void> {
+    const req = { keys };
+    const [, err] = await this.client.send(Writer.ENDPOINT_DELETE, req, z.object({}));
+    if (err != null) throw err;
+  }
+}

package/src/ontology/index.ts

@@ -0,0 +1,10 @@
+// Copyright 2023 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.
+
+export * as ontology from "@/ontology/external";

package/src/ontology/ontology.spec.ts

@@ -0,0 +1,114 @@
+// Copyright 2023 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 { describe, expect, test, it } from "vitest";
+
+import { ontology } from "@/ontology";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+const randomName = (): string => `group-${Math.random()}`;
+
+describe("Ontology", () => {
+  describe("retrieve", () => {
+    test("retrieve", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const g2 = await client.ontology.retrieve(g.ontologyID);
+      expect(g2.name).toEqual(name);
+    });
+    test("retrieve children", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const name2 = randomName();
+      await client.ontology.groups.create(g.ontologyID, name2);
+      const children = await client.ontology.retrieveChildren(g.ontologyID);
+      expect(children.length).toEqual(1);
+      expect(children[0].name).toEqual(name2);
+    });
+    test("retrieve parents", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const name2 = randomName();
+      const g2 = await client.ontology.groups.create(g.ontologyID, name2);
+      const parents = await client.ontology.retrieveParents(g2.ontologyID);
+      expect(parents.length).toEqual(1);
+      expect(parents[0].name).toEqual(name);
+    });
+    test("add children", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const name2 = randomName();
+      const g2 = await client.ontology.groups.create(ontology.Root, name2);
+      await client.ontology.addChildren(g.ontologyID, g2.ontologyID);
+      const children = await client.ontology.retrieveChildren(g.ontologyID);
+      expect(children.length).toEqual(1);
+      expect(children[0].name).toEqual(name2);
+    });
+    test("remove children", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const name2 = randomName();
+      const g2 = await client.ontology.groups.create(ontology.Root, name2);
+      await client.ontology.addChildren(g.ontologyID, g2.ontologyID);
+      await client.ontology.removeChildren(g.ontologyID, g2.ontologyID);
+      const children = await client.ontology.retrieveChildren(g.ontologyID);
+      expect(children.length).toEqual(0);
+    });
+    test("move children", async () => {
+      const name = randomName();
+      const g = await client.ontology.groups.create(ontology.Root, name);
+      const name2 = randomName();
+      const g2 = await client.ontology.groups.create(ontology.Root, name2);
+      const oldRootLength = (await client.ontology.retrieveChildren(ontology.Root))
+        .length;
+      await client.ontology.moveChildren(ontology.Root, g.ontologyID, g2.ontologyID);
+      const children = await client.ontology.retrieveChildren(g.ontologyID);
+      expect(children.length).toEqual(1);
+      const newRootLength = (await client.ontology.retrieveChildren(ontology.Root))
+        .length;
+      expect(newRootLength).toEqual(oldRootLength - 1);
+    });
+  });
+  describe("signals", async () => {
+    it("should correctly decode a set of relationships from a string", () => {
+      const rel = ontology.parseRelationship("typeA:keyA->parent->typeB:keyB");
+      expect(rel.type).toEqual("parent");
+      expect(rel.from.type).toEqual("typeA");
+      expect(rel.from.key).toEqual("keyA");
+      expect(rel.to.type).toEqual("typeB");
+      expect(rel.to.key).toEqual("keyB");
+    });
+    it("should correctly propagate resource changes to the ontology", async () => {
+      const change = await client.ontology.openChangeTracker();
+      const p = new Promise<ontology.ResourceChange[]>((resolve) => {
+        change.resources.onChange((changes) => {
+          resolve(changes);
+        });
+      });
+      await client.ontology.groups.create(ontology.Root, randomName());
+      const c = await p;
+      expect(c.length).toBeGreaterThan(0);
+      await change.close();
+    });
+    it("should correctly propagate relationship changes to the ontology", async () => {
+      const change = await client.ontology.openChangeTracker();
+      const p = new Promise<ontology.RelationshipChange[]>((resolve) => {
+        change.relationships.onChange((changes) => {
+          resolve(changes);
+        });
+      });
+      await client.ontology.groups.create(ontology.Root, randomName());
+      const c = await p;
+      expect(c.length).toBeGreaterThan(0);
+      await change.close();
+    });
+  });
+});

package/src/ontology/payload.ts

@@ -0,0 +1,118 @@
+// Copyright 2023 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 { z } from "zod";
+
+const resourceTypeZ = z.union([
+  z.literal("label"),
+  z.literal("builtin"),
+  z.literal("cluster"),
+  z.literal("channel"),
+  z.literal("node"),
+  z.literal("group"),
+  z.literal("range"),
+  z.literal("range-alias"),
+  z.literal("user"),
+  z.literal("workspace"),
+  z.literal("pid"),
+  z.literal("lineplot"),
+]);
+
+export type ResourceType = z.infer<typeof resourceTypeZ>;
+
+export const idZ = z.object({
+  type: resourceTypeZ,
+  key: z.string(),
+});
+
+export const stringIDZ = z.string().transform((v) => {
+  const [type, key] = v.split(":");
+  return {
+    type: type as ResourceType,
+    key,
+  };
+});
+
+export const crudeIDZ = z.union([stringIDZ, idZ]);
+
+export class ID {
+  type: ResourceType;
+  key: string;
+
+  constructor(args: z.input<typeof crudeIDZ> | ID) {
+    if (args instanceof ID) {
+      this.type = args.type;
+      this.key = args.key;
+    } else if (typeof args === "string") {
+      const [type, key] = args.split(":");
+      this.type = type as ResourceType;
+      this.key = key;
+    } else {
+      this.type = args.type;
+      this.key = args.key;
+    }
+  }
+
+  toString(): string {
+    return `${this.type}:${this.key}`;
+  }
+
+  get payload(): z.infer<typeof idZ> {
+    return {
+      type: this.type,
+      key: this.key,
+    };
+  }
+
+  static readonly z = z.union([crudeIDZ, z.instanceof(ID)]).transform((v) => new ID(v));
+}
+
+export const Root = new ID({ type: "builtin", key: "root" });
+
+export const schemaFieldZ = z.object({
+  type: z.number(),
+});
+
+export type SchemaField = z.infer<typeof schemaFieldZ>;
+
+export const schemaZ = z.object({
+  type: resourceTypeZ,
+  fields: z.record(schemaFieldZ),
+});
+
+export type Schema = z.infer<typeof schemaZ>;
+
+export const resourceSchemaZ = z
+  .object({
+    id: ID.z,
+    name: z.string(),
+    schema: schemaZ.optional(),
+    data: z.record(z.unknown()).optional(),
+  })
+  .transform((resource) => {
+    return {
+      key: resource.id.toString(),
+      ...resource,
+    };
+  });
+
+export type Resource = z.infer<typeof resourceSchemaZ>;
+
+export const relationshipSchemaZ = z.object({
+  from: ID.z,
+  type: z.string(),
+  to: ID.z,
+});
+
+export type Relationship = z.infer<typeof relationshipSchemaZ>;
+
+export const parseRelationship = (str: string): Relationship => {
+  const [from, type, to] = str.split("->");
+  return { from: new ID(from), type, to: new ID(to) };
+};