@synnaxlabs/client 0.21.0 → 0.22.0

package/src/framer/writer.spec.ts

@@ -7,7 +7,7 @@
 // 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, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x";
+import { DataType, Rate, TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, test } from "vitest";
 
 import { type channel } from "@/channel";
@@ -68,7 +68,11 @@ describe("Writer", () => {
     });
     test("write with auto commit on", async () => {
       const ch = await newChannel();
-      const writer = await client.openWriter({ start: 0, channels: ch.key, enableAutoCommit: true });
+      const writer = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        enableAutoCommit: true,
+      });
       try {
         await writer.write(ch.key, randomSeries(10, ch.dataType));
       } finally {
@@ -76,31 +80,39 @@ describe("Writer", () => {
       }
       expect(true).toBeTruthy();
 
-      const f = await client.read(new TimeRange(0, TimeStamp.seconds(10)), ch.key)
-      expect(f.length).toEqual(10)
-    })
+      const f = await client.read(new TimeRange(0, TimeStamp.seconds(10)), ch.key);
+      expect(f.length).toEqual(10);
+    });
     test("write with auto commit and alwaysPersist", async () => {
       const ch = await newChannel();
-      const writer = await client.openWriter({ start: 0, channels: ch.key,
-        enableAutoCommit: true, autoIndexPersistInterval: ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT});
+      const writer = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        enableAutoCommit: true,
+        autoIndexPersistInterval: ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT,
+      });
       try {
         await writer.write(ch.key, randomSeries(10, ch.dataType));
       } finally {
         await writer.close();
       }
       expect(true).toBeTruthy();
-    })
+    });
     test("write with auto commit and a set interval", async () => {
       const ch = await newChannel();
-      const writer = await client.openWriter({ start: 0, channels: ch.key,
-        enableAutoCommit: true, autoIndexPersistInterval: TimeSpan.milliseconds(100)});
+      const writer = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        enableAutoCommit: true,
+        autoIndexPersistInterval: TimeSpan.milliseconds(100),
+      });
       try {
         await writer.write(ch.key, randomSeries(10, ch.dataType));
       } finally {
         await writer.close();
       }
       expect(true).toBeTruthy();
-    })
+    });
   });
   describe("Client", () => {
     test("Client - basic write", async () => {

package/src/framer/writer.ts

@@ -13,10 +13,10 @@ import { decodeError, errorZ } from "@synnaxlabs/freighter";
 import {
   TimeStamp,
   type CrudeTimeStamp,
-  toArray,
   type CrudeSeries,
   TimeSpan,
-} from "@synnaxlabs/x";
+} from "@synnaxlabs/x/telem";
+import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import {
@@ -50,7 +50,7 @@ export enum WriterMode {
   StreamOnly = 3,
 }
 
-export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT : TimeSpan = new TimeSpan(-1);
+export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
 
 const netConfigZ = z.object({
   start: TimeStamp.z.optional(),
@@ -95,11 +95,11 @@ export interface WriterConfig {
   //  enableAutoCommit determines whether the writer will automatically commit.
   //  If enableAutoCommit is true, then the writer will commit after each write, and
   //  will flush that commit to index after the specified autoIndexPersistInterval.
-  enableAutoCommit?: boolean
+  enableAutoCommit?: boolean;
   // autoIndexPersistInterval sets the interval at which commits to the index will be
   // persisted. To persist every commit to guarantee minimal loss of data, set
   // auto_index_persist_interval to AlwaysAutoIndexPersist.
-  autoIndexPersistInterval?: TimeSpan
+  autoIndexPersistInterval?: TimeSpan;
 }
 
 /**
@@ -163,7 +163,7 @@ export class Writer {
       controlSubject: subject,
       mode = WriterMode.PersistStream,
       enableAutoCommit = false,
-      autoIndexPersistInterval = TimeSpan.SECOND
+      autoIndexPersistInterval = TimeSpan.SECOND,
     }: WriterConfig,
   ): Promise<Writer> {
     const adapter = await WriteFrameAdapter.open(retriever, channels);

package/src/hardware/device/client.ts

@@ -7,63 +7,190 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { AsyncTermSearcher, toArray } from "@synnaxlabs/x";
+import { type UnaryClient, sendRequired } from "@synnaxlabs/freighter";
+import { type UnknownRecord, toArray } from "@synnaxlabs/x";
+import { binary } from "@synnaxlabs/x/binary";
+import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
+import { z } from "zod";
 
 import { type framer } from "@/framer";
-import { type Device, deviceZ, DeviceKey } from "@/hardware/device/payload";
-import { type Retriever } from "@/hardware/device/retriever";
-import { type Writer } from "@/hardware/device/writer";
+import { rackKeyZ } from "@/hardware/rack/client";
 import { signals } from "@/signals";
+import { checkForMultipleOrNoResults } from "@/util/retrieve";
+import { nullableArrayZ } from "@/util/zod";
 
 const DEVICE_SET_NAME = "sy_device_set";
 const DEVICE_DELETE_NAME = "sy_device_delete";
 
-export class Client implements AsyncTermSearcher<string, DeviceKey, Device>{
-  private readonly retriever: Retriever;
-  private readonly writer: Writer;
+const RETRIEVE_ENDPOINT = "/hardware/device/retrieve";
+const CREATE_ENDPOINT = "/hardware/device/create";
+const DELETE_ENDPOINT = "/hardware/device/delete";
+
+export const deviceKeyZ = z.string();
+
+export const deviceZ = z.object({
+  key: deviceKeyZ,
+  rack: rackKeyZ,
+  name: z.string(),
+  make: z.string(),
+  model: z.string(),
+  location: z.string(),
+  configured: z.boolean().optional(),
+  properties: z.record(z.unknown()).or(
+    z.string().transform((c) => {
+      if (c === "") return {};
+      return binary.JSON_ECD.decodeString(c);
+    }),
+  ) as z.ZodType<UnknownRecord>,
+});
+
+export type Device<P extends UnknownRecord = UnknownRecord> = Omit<
+  z.output<typeof deviceZ>,
+  "properties"
+> & { properties: P };
+
+export type DeviceKey = z.infer<typeof deviceKeyZ>;
+
+export const newDeviceZ = deviceZ.extend({
+  properties: z.unknown().transform((c) => binary.JSON_ECD.encodeString(c)),
+});
+
+export type NewDevice<P extends UnknownRecord = UnknownRecord> = Omit<
+  z.input<typeof newDeviceZ>,
+  "properties"
+> & { properties: P };
+
+const createReqZ = z.object({ devices: newDeviceZ.array() });
+
+const createResZ = z.object({ devices: deviceZ.array() });
+
+const deleteReqZ = z.object({ keys: deviceKeyZ.array() });
+
+const deleteResZ = z.object({});
+
+const retrieveReqZ = z.object({
+  search: z.string().optional(),
+  limit: z.number().optional(),
+  offset: z.number().optional(),
+  keys: deviceKeyZ.array().optional(),
+  names: z.string().array().optional(),
+  makes: z.string().array().optional(),
+});
+
+type RetrieveRequest = z.input<typeof retrieveReqZ>;
+
+export type RetrieveOptions = Pick<RetrieveRequest, "limit" | "offset" | "makes">;
+
+type PageOptions = Pick<RetrieveOptions, "makes">;
+
+const retrieveResZ = z.object({ devices: nullableArrayZ(deviceZ) });
+
+export class Client implements AsyncTermSearcher<string, DeviceKey, Device> {
+  readonly type = "device";
+  private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
 
-  constructor(retriever: Retriever, writer: Writer, frameClient: framer.Client) {
-    this.retriever = retriever;
-    this.writer = writer;
+  constructor(client: UnaryClient, frameClient: framer.Client) {
+    this.client = client;
     this.frameClient = frameClient;
   }
 
-  async create(device: Device): Promise<Device> {
-    const res = await this.writer.create([device]);
-    return res[0];
-  }
+  async retrieve<P extends UnknownRecord = UnknownRecord>(
+    key: string,
+    options?: RetrieveOptions,
+  ): Promise<Device<P>>;
 
-  async retrieve(key: string): Promise<Device>;
-  async retrieve(keys: string[]): Promise<Device[]>;
+  async retrieve<P extends UnknownRecord = UnknownRecord>(
+    keys: string[],
+    options?: RetrieveOptions,
+  ): Promise<Array<Device<P>>>;
 
-  async retrieve(keys: string | string[]): Promise<Device | Device[]> {
-    const res = await this.retriever.retrieve(toArray(keys));
-    return Array.isArray(keys) ? res : res[0];
+  async retrieve<P extends UnknownRecord = UnknownRecord>(
+    keys: string | string[],
+    options?: RetrieveOptions,
+  ): Promise<Device<P> | Array<Device<P>>> {
+    const isSingle = !Array.isArray(keys);
+    const res = await sendRequired(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { keys: toArray(keys), ...options },
+      retrieveReqZ,
+      retrieveResZ,
+    );
+    checkForMultipleOrNoResults("Device", keys, res.devices, isSingle);
+    return (isSingle ? res.devices[0] : res.devices) as Device<P> | Array<Device<P>>;
   }
 
-  async search(term: string): Promise<Device[]> {
-    const res = await this.retriever.search(term);
-    return res;
+  async search(term: string, options?: RetrieveOptions): Promise<Device[]> {
+    return (
+      await sendRequired(
+        this.client,
+        RETRIEVE_ENDPOINT,
+        { search: term, ...options },
+        retrieveReqZ,
+        retrieveResZ,
+      )
+    ).devices;
   }
 
-  async page(offset: number, limit: number): Promise<Device[]> {
-    const res = await this.retriever.page(offset, limit);
-    return res;
+  async page(offset: number, limit: number, options?: PageOptions): Promise<Device[]> {
+    return (
+      await sendRequired(
+        this.client,
+        RETRIEVE_ENDPOINT,
+        { offset, limit, ...options },
+        retrieveReqZ,
+        retrieveResZ,
+      )
+    ).devices;
   }
 
-  async delete(keys: string[]): Promise<void> {
-    await this.writer.delete(keys);
+  async create(device: NewDevice): Promise<Device>;
+
+  async create(devices: NewDevice[]): Promise<Device[]>;
+
+  async create(devices: NewDevice | NewDevice[]): Promise<Device | Device[]> {
+    const isSingle = !Array.isArray(devices);
+    const res = await sendRequired(
+      this.client,
+      CREATE_ENDPOINT,
+      { devices: toArray(devices) },
+      createReqZ,
+      createResZ,
+    );
+    return isSingle ? res.devices[0] : res.devices;
+  }
+
+  async delete(keys: string | string[]): Promise<void> {
+    await sendRequired(
+      this.client,
+      DELETE_ENDPOINT,
+      { keys: toArray(keys) },
+      deleteReqZ,
+      deleteResZ,
+    );
   }
 
   async openDeviceTracker(): Promise<signals.Observable<string, Device>> {
-    return await signals.Observable.open<string, Device>(
+    return await signals.openObservable<string, Device>(
       this.frameClient,
       DEVICE_SET_NAME,
       DEVICE_DELETE_NAME,
       decodeDeviceChanges,
     );
   }
+
+  newSearcherWithOptions(
+    options: RetrieveOptions,
+  ): AsyncTermSearcher<string, DeviceKey, Device> {
+    return {
+      type: this.type,
+      search: async (term: string) => await this.search(term, options),
+      retrieve: async (keys: string[]) => await this.retrieve(keys, options),
+      page: async (offset: number, limit: number) =>
+        await this.page(offset, limit, options),
+    };
+  }
 }
 
 const decodeDeviceChanges: signals.Decoder<string, Device> = (variant, data) => {

package/src/hardware/device/device.spec.ts

@@ -25,7 +25,7 @@ describe("Device", () => {
           name: "test",
           make: "ni",
           model: "dog",
-          properties: "dog",
+          properties: { cat: "dog" },
         });
         expect(d.key).toEqual("SN222");
         expect(d.name).toBe("test");
@@ -42,7 +42,7 @@ describe("Device", () => {
           name: "test",
           make: "ni",
           model: "dog",
-          properties: "dog",
+          properties: { cat: "dog" },
         });
         const retrieved = await client.hardware.devices.retrieve(d.key);
         expect(retrieved.key).toBe(d.key);

package/src/hardware/device/external.ts

@@ -8,5 +8,3 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/hardware/device/client";
-export * from "@/hardware/device/retriever";
-export * from "@/hardware/device/writer";

package/src/hardware/device/index.ts

@@ -1,4 +1,4 @@
-// Copyright 2024 Synnax Labs, Inc.
+// Copyright 2023 Synnax Labs, Inc.
 //
 // Use of this software is governed by the Business Source License included in the file
 // licenses/BSL.txt.
@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as device from "@/hardware/device/external";
+export * as device from "@/hardware/device/client";

package/src/hardware/rack/client.ts

@@ -7,105 +7,188 @@
 // 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 { type UnknownRecord } from "@synnaxlabs/x";
+import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
+import { toArray } from "@synnaxlabs/x/toArray";
+import { z } from "zod";
+
 import { type framer } from "@/framer";
-import { RackKey, type NewRack, type RackPayload } from "@/hardware/rack/payload";
-import { type Retriever } from "@/hardware/rack/retriever";
-import { type Writer } from "@/hardware/rack/writer";
-import { type NewTask, type Task } from "@/hardware/task/payload";
-import { type Retriever as TaskRetriever } from "@/hardware/task/retriever";
-import { type Writer as TaskWriter } from "@/hardware/task/writer";
-import { AsyncTermSearcher, toArray } from "@synnaxlabs/x";
+import { type task } from "@/hardware/task";
+import { analyzeParams, checkForMultipleOrNoResults } from "@/util/retrieve";
+import { nullableArrayZ } from "@/util/zod";
+
+export const rackKeyZ = z.number();
+
+export type RackKey = z.infer<typeof rackKeyZ>;
+
+export const rackZ = z.object({
+  key: rackKeyZ,
+  name: z.string(),
+});
+
+export type RackPayload = z.infer<typeof rackZ>;
+
+export const newRackZ = rackZ.partial({ key: true });
+
+export type NewRack = z.input<typeof newRackZ>;
+
+const RETRIEVE_ENDPOINT = "/hardware/rack/retrieve";
+const CREATE_RACK_ENDPOINT = "/hardware/rack/create";
+const DELETE_RACK_ENDPOINT = "/hardware/rack/delete";
+
+const retrieveRackReqZ = z.object({
+  keys: rackKeyZ.array().optional(),
+  names: z.string().array().optional(),
+  search: z.string().optional(),
+  offset: z.number().optional(),
+  limit: z.number().optional(),
+});
+
+const retrieveRackResZ = z.object({
+  racks: nullableArrayZ(rackZ),
+});
+
+const createReqZ = z.object({
+  racks: newRackZ.array(),
+});
+
+const createResZ = z.object({
+  racks: rackZ.array(),
+});
+
+const deleteReqZ = z.object({
+  keys: rackKeyZ.array(),
+});
+
+const deleteResZ = z.object({});
 
 export class Client implements AsyncTermSearcher<string, RackKey, Rack> {
-  private readonly retriever: Retriever;
-  private readonly writer: Writer;
+  readonly type: string = "rack";
+  private readonly client: UnaryClient;
   private readonly frameClient: framer.Client;
-  private readonly taskWriter: TaskWriter;
-  private readonly taskRetriever: TaskRetriever;
+  private readonly tasks: task.Client;
 
   constructor(
-    retriever: Retriever,
-    writer: Writer,
+    client: UnaryClient,
     frameClient: framer.Client,
-    taskWriter: TaskWriter,
-    taskRetriever: TaskRetriever,
+    taskClient: task.Client,
   ) {
-    this.retriever = retriever;
-    this.writer = writer;
+    this.client = client;
     this.frameClient = frameClient;
-    this.taskWriter = taskWriter;
-    this.taskRetriever = taskRetriever;
+    this.tasks = taskClient;
   }
 
-  async create(rack: NewRack): Promise<Rack> {
-    const res = await this.writer.create([rack]);
-    return this.sugar(res)[0];
+  async delete(keys: RackKey | RackKey[]): Promise<void> {
+    await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
+      this.client,
+      DELETE_RACK_ENDPOINT,
+      { keys: toArray(keys) },
+      deleteReqZ,
+      deleteResZ,
+    );
+  }
+
+  async create(rack: NewRack): Promise<Rack>;
+
+  async create(racks: NewRack[]): Promise<Rack[]>;
+
+  async create(rack: NewRack | NewRack[]): Promise<Rack | Rack[]> {
+    const isSingle = !Array.isArray(rack);
+    const res = await sendRequired<typeof createReqZ, typeof createResZ>(
+      this.client,
+      CREATE_RACK_ENDPOINT,
+      { racks: toArray(rack) },
+      createReqZ,
+      createResZ,
+    );
+    const sugared = this.sugar(res.racks);
+    if (isSingle) return sugared[0];
+    return sugared;
   }
 
   async search(term: string): Promise<Rack[]> {
-    const res = await this.retriever.search(term);
-    return this.sugar(res);
+    const res = await sendRequired<typeof retrieveRackReqZ, typeof retrieveRackResZ>(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { search: term },
+      retrieveRackReqZ,
+      retrieveRackResZ,
+    );
+    return this.sugar(res.racks);
   }
 
   async page(offset: number, limit: number): Promise<Rack[]> {
-    const res = await this.retriever.page(offset, limit);
-    return this.sugar(res);
+    const res = await sendRequired<typeof retrieveRackReqZ, typeof retrieveRackResZ>(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { offset, limit },
+      retrieveRackReqZ,
+      retrieveRackResZ,
+    );
+    return this.sugar(res.racks);
   }
 
-  async retrieve(key: RackKey): Promise<Rack>;
-
-  async retrieve(keys: RackKey[]): Promise<Rack[]>;
-
-  async retrieve(key: RackKey | RackKey[]): Promise<Rack | Rack[]> {
-    const res = await this.retriever.retrieve(toArray(key));
-    if (Array.isArray(key)) return this.sugar(res);
-    return this.sugar(res)[0];
+  async retrieve(key: string | RackKey): Promise<Rack>;
+
+  async retrieve(keys: number[] | RackKey[]): Promise<Rack[]>;
+
+  async retrieve(
+    params: string | RackKey | string[] | RackKey[],
+  ): Promise<Rack | Rack[]> {
+    const { variant, normalized, single } = analyzeParams(params, {
+      string: "names",
+      number: "keys",
+    });
+    const res = await sendRequired<typeof retrieveRackReqZ, typeof retrieveRackResZ>(
+      this.client,
+      RETRIEVE_ENDPOINT,
+      { [variant]: normalized },
+      retrieveRackReqZ,
+      retrieveRackResZ,
+    );
+    const sugared = this.sugar(res.racks);
+    checkForMultipleOrNoResults("Rack", params, sugared, single);
+    return single ? sugared[0] : sugared;
   }
 
   private sugar(payloads: RackPayload[]): Rack[] {
-    return payloads.map(
-      (payload) =>
-        new Rack(payload.key, payload.name, this.taskWriter, this.taskRetriever),
-    );
+    return payloads.map(({ key, name }) => new Rack(key, name, this.tasks));
   }
 }
 
 export class Rack {
   key: number;
   name: string;
-  private readonly writer: TaskWriter;
-  private readonly tasks: TaskRetriever;
+  private readonly tasks: task.Client;
 
-  constructor(
-    key: number,
-    name: string,
-    _writer: TaskWriter,
-    _retriever: TaskRetriever,
-  ) {
+  constructor(key: number, name: string, client: task.Client) {
     this.key = key;
     this.name = name;
-    this.writer = _writer;
-    this.tasks = _retriever;
+    this.tasks = client;
   }
 
-  async listTasks(): Promise<Task[]> {
-    return await this.tasks.retrieve({ rack: this.key });
+  async listTasks(): Promise<task.Task[]> {
+    return await this.tasks.retrieve(this.key);
   }
 
-  async retrieveTasks(): Promise<Task[]> {
-    return [];
+  async retrieveTaskByName(name: string): Promise<task.Task> {
+    return await this.tasks.retrieveByName(name, this.key);
   }
 
-  async createTask(task: NewTask): Promise<Task> {
+  async createTask<
+    C extends UnknownRecord,
+    D extends {} = UnknownRecord,
+    T extends string = string,
+  >(task: task.NewTask<C, T>): Promise<task.Task<C, D, T>> {
     task.key = (
       (BigInt(this.key) << 32n) +
       (BigInt(task.key ?? 0) & 0xffffffffn)
     ).toString();
-    const res = await this.writer.create([task]);
-    return res[0];
+    return await this.tasks.create<C, D, T>(task);
   }
 
   async deleteTask(task: bigint): Promise<void> {
-    await this.writer.delete([task]);
+    await this.tasks.delete([task]);
   }
 }

package/src/hardware/rack/external.ts

@@ -8,5 +8,3 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/hardware/rack/client";
-export * from "@/hardware/rack/writer";
-export * from "@/hardware/rack/retriever";

package/src/hardware/rack/rack.spec.ts

@@ -8,7 +8,9 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it } from "vitest";
+import { ZodError } from "zod";
 
+import { NotFoundError } from "@/errors";
 import { newClient } from "@/setupspecs";
 
 const client = newClient();
@@ -19,6 +21,10 @@ describe("Rack", () => {
       const r = await client.hardware.racks.create({ name: "test" });
       expect(r.key).toBeGreaterThan(0n);
     });
+    it("should return an error if the rack doesn't have a name", async () => {
+      // @ts-expect-error
+      await expect(client.hardware.racks.create({})).rejects.toThrow(ZodError);
+    });
   });
   describe("retrieve", () => {
     it("should retrieve a rack by its key", async () => {
@@ -27,6 +33,13 @@ describe("Rack", () => {
       expect(retrieved.key).toBe(r.key);
       expect(retrieved.name).toBe("test");
     });
+    it("should retrieve a rack by its name", async () => {
+      const name = `TimeStamp.now().toString()}-${Math.random()}`;
+      const r = await client.hardware.racks.create({ name });
+      const retrieved = await client.hardware.racks.retrieve(name);
+      expect(retrieved.key).toBe(r.key);
+      expect(retrieved.name).toEqual(name);
+    });
   });
   describe("tasks", () => {
     it("should list the tasks on a rack", async () => {
@@ -34,5 +47,11 @@ describe("Rack", () => {
       const tasks = await r.listTasks();
       expect(tasks).toHaveLength(0);
     });
-  })
+    it("should throw an error if a task cannot be found by name", async () => {
+      const r = await client.hardware.racks.create({ name: "test" });
+      await expect(
+        async () => await r.retrieveTaskByName("nonexistent"),
+      ).rejects.toThrow(NotFoundError);
+    });
+  });
 });