@synnaxlabs/client 0.2.1 → 0.13.6

package/src/ranger/kv.ts

@@ -0,0 +1,91 @@
+// 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, sendRequired } from "@synnaxlabs/freighter";
+import { isObject, toArray } from "@synnaxlabs/x";
+import { z } from "zod";
+
+import { type Key, keyZ } from "@/ranger/payload";
+
+const getReqZ = z.object({
+  range: keyZ,
+  keys: z.string().array(),
+});
+
+const getResZ = z.object({
+  pairs: z.record(z.string(), z.string()),
+});
+
+export type GetRequest = z.infer<typeof getReqZ>;
+
+const setReqZ = z.object({
+  range: keyZ,
+  pairs: z.record(z.string(), z.string()),
+});
+
+export type SetRequest = z.infer<typeof setReqZ>;
+
+const deleteReqZ = z.object({
+  range: keyZ,
+  keys: z.string().array(),
+});
+
+export type DeleteRequest = z.infer<typeof deleteReqZ>;
+
+export class KV {
+  private static readonly GET_ENDPOINT = "/range/kv/get";
+  private static readonly SET_ENDPOINT = "/range/kv/set";
+  private static readonly DELETE_ENDPOINT = "/range/kv/delete";
+  private readonly rangeKey: Key;
+  private readonly client: UnaryClient;
+
+  constructor(rng: Key, client: UnaryClient) {
+    this.rangeKey = rng;
+    this.client = client;
+  }
+
+  async get(key: string): Promise<string>;
+
+  async get(keys: string[]): Promise<Record<string, string>>;
+
+  async get(keys: string | string[]): Promise<string | Record<string, string>> {
+    const [res, err] = await this.client.send(
+      KV.GET_ENDPOINT,
+      { range: this.rangeKey, keys: toArray(keys) },
+      getResZ,
+    );
+    if (err != null) throw err;
+    return Array.isArray(keys) ? res.pairs : res.pairs[keys];
+  }
+
+  async set(key: string, value: string): Promise<void>;
+
+  async set(kv: Record<string, string>): Promise<void>;
+
+  async set(key: string | Record<string, string>, value?: string): Promise<void> {
+    await sendRequired(
+      this.client,
+      KV.SET_ENDPOINT,
+      {
+        range: this.rangeKey,
+        pairs: isObject(key) ? key : { [key]: value },
+      },
+      z.unknown(),
+    );
+  }
+
+  async delete(key: string | string[]): Promise<void> {
+    await sendRequired(
+      this.client,
+      KV.DELETE_ENDPOINT,
+      { range: this.rangeKey, keys: toArray(key) },
+      z.unknown(),
+    );
+  }
+}

package/src/ranger/payload.ts

@@ -0,0 +1,70 @@
+// 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 { TimeRange, 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().min(1),
+  timeRange: TimeRange.z,
+});
+export type Payload = z.infer<typeof payloadZ>;
+
+export const newPayloadZ = payloadZ.extend({
+  key: z.string().uuid().optional(),
+});
+export type NewPayload = z.infer<typeof newPayloadZ>;
+
+export type ParamAnalsysisResult =
+  | {
+      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): ParamAnalsysisResult => {
+  const normal = toArray(params) as Keys | Names;
+  if (normal.length === 0) {
+    throw new Error("Range params must not be empty");
+  }
+  const isKey = keyZ.safeParse(normal[0]).success;
+  return {
+    single: !Array.isArray(params),
+    variant: isKey ? "keys" : "names",
+    normalized: normal,
+    actual: params,
+  } as const as ParamAnalsysisResult;
+};

package/src/ranger/range.ts

@@ -0,0 +1,95 @@
+// 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 Series, TimeRange } from "@synnaxlabs/x";
+
+import { type Key, type Params, type Name } from "@/channel/payload";
+import { type Retriever as ChannelRetriever } from "@/channel/retriever";
+import { QueryError } from "@/errors";
+import { type framer } from "@/framer";
+import { type label } from "@/label";
+import { type Label } from "@/label/payload";
+import { ontology } from "@/ontology";
+import { type Alias, type Aliaser } from "@/ranger/alias";
+import { type KV } from "@/ranger/kv";
+import { type signals } from "@/signals";
+
+const ontologyID = (key: string): ontology.ID =>
+  new ontology.ID({ type: "range", key });
+
+export class Range {
+  key: string;
+  name: string;
+  readonly kv: KV;
+  readonly timeRange: TimeRange;
+  readonly channels: ChannelRetriever;
+  private readonly aliaser: Aliaser;
+  private readonly frameClient: framer.Client;
+  private readonly labelClient: label.Client;
+
+  constructor(
+    name: string,
+    timeRange: TimeRange = TimeRange.ZERO,
+    key: string,
+    _frameClient: framer.Client,
+    _kv: KV,
+    _aliaser: Aliaser,
+    _channels: ChannelRetriever,
+    _labelClient: label.Client,
+  ) {
+    this.key = key;
+    this.name = name;
+    this.timeRange = timeRange;
+    this.frameClient = _frameClient;
+    this.kv = _kv;
+    this.aliaser = _aliaser;
+    this.channels = _channels;
+    this.labelClient = _labelClient;
+  }
+
+  async setAlias(channel: Key | Name, alias: string): Promise<void> {
+    const ch = await this.channels.retrieve(channel);
+    if (ch.length === 0) {
+      throw new QueryError(`Channel ${channel} does not exist`);
+    }
+    await this.aliaser.set({ [ch[0].key]: alias });
+  }
+
+  async deleteAlias(...channels: Key[]): Promise<void> {
+    await this.aliaser.delete(channels);
+  }
+
+  async listAliases(): Promise<Record<Key, string>> {
+    return await this.aliaser.list();
+  }
+
+  async openAliasTracker(): Promise<signals.Observable<string, Alias>> {
+    return await this.aliaser.openChangeTracker();
+  }
+
+  async read(channel: Key | Name): Promise<Series>;
+
+  async read(channels: Params): Promise<framer.Frame>;
+
+  async read(channels: Params): Promise<Series | framer.Frame> {
+    return await this.frameClient.read(this.timeRange, channels);
+  }
+
+  async labels(): Promise<Label[]> {
+    return await this.labelClient.retrieveFor(ontologyID(this.key));
+  }
+
+  async addLabel(...labels: label.Key[]): Promise<void> {
+    await this.labelClient.label(ontologyID(this.key), labels);
+  }
+
+  async removeLabel(...labels: label.Key[]): Promise<void> {
+    await this.labelClient.removeLabels(ontologyID(this.key), labels);
+  }
+}

package/src/ranger/ranger.spec.ts

@@ -0,0 +1,201 @@
+// 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 { DataType, Rate, TimeSpan, TimeStamp } from "@synnaxlabs/x";
+import { describe, expect, it } from "vitest";
+
+import { QueryError } from "@/errors";
+import { type NewPayload } from "@/ranger/payload";
+import { newClient } from "@/setupspecs";
+
+const client = newClient();
+
+describe("Ranger", () => {
+  describe("create", () => {
+    it("should create a single range", async () => {
+      const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));
+      const range = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange,
+      });
+      expect(range.key).not.toHaveLength(0);
+      expect(timeRange).toEqual(range.timeRange);
+    });
+    it("should create multiple ranges", async () => {
+      const ranges: NewPayload[] = [
+        {
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        },
+        {
+          name: "My New Two Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(2)),
+        },
+      ];
+      const createdRanges = await client.ranges.create(ranges);
+      expect(createdRanges).toHaveLength(2);
+      expect(createdRanges[0].key).not.toHaveLength(0);
+      expect(createdRanges[1].key).not.toHaveLength(0);
+      expect(createdRanges[0].timeRange).toEqual(ranges[0].timeRange);
+      expect(createdRanges[1].timeRange).toEqual(ranges[1].timeRange);
+    });
+  });
+
+  describe("delete", () => {
+    it("should delete a single range", async () => {
+      const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));
+      const range = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange,
+      });
+      await client.ranges.delete(range.key);
+      await expect(async () => await client.ranges.retrieve(range.key)).rejects.toThrow(
+        QueryError,
+      );
+    });
+  });
+
+  describe("rename", () => {
+    it("should rename a single range", async () => {
+      const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));
+      const range = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange,
+      });
+      await client.ranges.rename(range.key, "My New One Second Range Renamed");
+      const renamed = await client.ranges.retrieve(range.key);
+      expect(renamed.name).toEqual("My New One Second Range Renamed");
+    });
+  });
+
+  describe("retrieve", () => {
+    it("should retrieve a range by key", async () => {
+      const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));
+      const range = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange,
+      });
+      const retrieved = await client.ranges.retrieve(range.key);
+      expect(retrieved.key).toEqual(range.key);
+      expect(retrieved.timeRange).toEqual(range.timeRange);
+    });
+    it("should retrieve a range by name", async () => {
+      const timeRange = TimeStamp.now().spanRange(TimeSpan.seconds(1));
+      const range = await client.ranges.create({
+        name: "My New Three Second Range",
+        timeRange,
+      });
+      const retrieved = await client.ranges.retrieve([range.name]);
+      expect(retrieved.length).toBeGreaterThan(0);
+      expect(retrieved[0].name).toEqual(range.name);
+    });
+  });
+
+  describe("KV", () => {
+    it("should set, get, and delete a single key", async () => {
+      const rng = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+      });
+      await rng.kv.set("foo", "bar");
+      const val = await rng.kv.get("foo");
+      expect(val).toEqual("bar");
+      await rng.kv.delete("foo");
+      await expect(async () => await rng.kv.get("foo")).rejects.toThrow(QueryError);
+    });
+
+    it("should set and get multiple keys", async () => {
+      const rng = await client.ranges.create({
+        name: "My New One Second Range",
+        timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+      });
+      await rng.kv.set({ foo: "bar", baz: "qux" });
+      const res = await rng.kv.get(["foo", "baz"]);
+      expect(res).toEqual({ foo: "bar", baz: "qux" });
+    });
+  });
+
+  describe("Alias", () => {
+    describe("list", () => {
+      it("should list the aliases for the range", async () => {
+        const ch = await client.channels.create({
+          name: "My New Channel",
+          dataType: DataType.FLOAT32,
+          rate: Rate.hz(1),
+        });
+        const rng = await client.ranges.create({
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        });
+        await rng.setAlias(ch.key, "myalias");
+        const aliases = await rng.listAliases();
+        expect(aliases).toEqual({ [ch.key]: "myalias" });
+      });
+    });
+  });
+
+  describe("Active", () => {
+    describe("setActive", () => {
+      it("should create and set a range as active", async () => {
+        const rng = await client.ranges.create({
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        });
+        await client.ranges.setActive(rng.key);
+        const retrieved = await client.ranges.retrieveActive();
+        expect(retrieved).not.toBeNull();
+        expect(retrieved?.key).toEqual(rng.key);
+      });
+      it("should clear the active range", async () => {
+        const rng = await client.ranges.create({
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        });
+        await client.ranges.setActive(rng.key);
+        await client.ranges.clearActive(rng.key);
+        const retrieved = await client.ranges.retrieveActive();
+        expect(retrieved).toBeNull();
+      });
+    });
+  });
+
+  describe("Labels", () => {
+    describe("set", () => {
+      it("should set a label on a range", async () => {
+        const rng = await client.ranges.create({
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        });
+        const lbl = await client.labels.create({
+          name: "My New Label",
+          color: "#E774D0",
+        });
+        await rng.addLabel(lbl.key);
+        const retrieved = await rng.labels();
+        expect(retrieved).toEqual([lbl]);
+      });
+    });
+    describe("remove", () => {
+      it("should remove a label from a range", async () => {
+        const rng = await client.ranges.create({
+          name: "My New One Second Range",
+          timeRange: TimeStamp.now().spanRange(TimeSpan.seconds(1)),
+        });
+        const lbl = await client.labels.create({
+          name: "My New Label",
+          color: "#E774D0",
+        });
+        await rng.addLabel(lbl.key);
+        await rng.removeLabel(lbl.key);
+        const retrieved = await rng.labels();
+        expect(retrieved).toEqual([]);
+      });
+    });
+  });
+});

package/src/ranger/retriever.ts

@@ -0,0 +1,50 @@
+// 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 Params, type Payload, analyzeParams, keyZ, payloadZ } from "./payload";
+
+const reqZ = z.object({
+  keys: keyZ.array().optional(),
+  names: z.array(z.string()).optional(),
+  term: z.string().optional(),
+});
+
+type Request = z.infer<typeof reqZ>;
+
+const resZ = z.object({
+  ranges: z.array(payloadZ),
+});
+
+export class Retriever {
+  private readonly ENDPOINT = "/range/retrieve";
+  private readonly client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async retrieve(params: Params): Promise<Payload[]> {
+    const { normalized, variant } = analyzeParams(params);
+    const res = await this.execute({ [variant]: normalized });
+    return res;
+  }
+
+  async search(term: string): Promise<Payload[]> {
+    return await this.execute({ term });
+  }
+
+  private async execute(request: Request): Promise<Payload[]> {
+    const [res, err] = await this.client.send(this.ENDPOINT, request, resZ);
+    if (err != null) throw err;
+    return res.ranges;
+  }
+}

package/src/ranger/writer.ts

@@ -0,0 +1,80 @@
+// 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 { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
+import { z } from "zod";
+
+import {
+  type NewPayload,
+  type Payload,
+  payloadZ,
+  keyZ,
+  newPayloadZ,
+} from "@/ranger/payload";
+
+const createResZ = z.object({
+  ranges: payloadZ.array(),
+});
+
+const createReqZ = z.object({
+  ranges: newPayloadZ.array(),
+});
+
+const deleteReqZ = z.object({
+  keys: keyZ.array(),
+});
+
+const deleteResZ = z.object({});
+
+const renameReqZ = z.object({
+  key: keyZ,
+  name: z.string(),
+});
+
+const renameResZ = z.object({});
+
+const CREATE_ENDPOINT = "/range/create";
+const DELETE_ENDPOINT = "/range/delete";
+const RENAME_ENDPOINT = "/range/rename";
+
+export class Writer {
+  client: UnaryClient;
+
+  constructor(client: UnaryClient) {
+    this.client = client;
+  }
+
+  async rename(key: string, name: string): Promise<void> {
+    await sendRequired<typeof renameReqZ, typeof renameResZ>(
+      this.client,
+      RENAME_ENDPOINT,
+      { key, name },
+      renameResZ,
+    );
+  }
+
+  async create(ranges: NewPayload[]): Promise<Payload[]> {
+    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+      this.client,
+      CREATE_ENDPOINT,
+      { ranges },
+      createResZ,
+    );
+    return res.ranges;
+  }
+
+  async delete(keys: string[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys },
+      deleteResZ,
+    );
+  }
+}

package/src/setupspecs.ts

@@ -0,0 +1,25 @@
+// 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 Synnax, { type SynnaxProps } from "@/client";
+
+export const HOST = "localhost";
+export const PORT = 9090;
+
+export const newClient = (...props: SynnaxProps[]): Synnax => {
+  let _props = {};
+  if (props.length > 0) _props = props[0];
+  return new Synnax({
+    host: HOST,
+    port: PORT,
+    username: "synnax",
+    password: "seldon",
+    ..._props,
+  });
+};

package/src/signals/external.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 * from "@/signals/observable";

package/src/signals/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 signals from "@/signals/external";