@synnaxlabs/client 0.20.0 → 0.22.0

package/src/framer/writer.spec.ts

@@ -7,11 +7,11 @@
 // 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, 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";
-import { WriterMode } from "@/framer/writer";
+import { ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT, WriterMode } from "@/framer/writer";
 import { newClient } from "@/setupspecs";
 import { randomSeries } from "@/util/telem";
 
@@ -66,6 +66,53 @@ describe("Writer", () => {
       ]);
       expect(v).toEqual(123);
     });
+    test("write with auto commit on", async () => {
+      const ch = await newChannel();
+      const writer = await client.openWriter({
+        start: 0,
+        channels: ch.key,
+        enableAutoCommit: true,
+      });
+      try {
+        await writer.write(ch.key, randomSeries(10, ch.dataType));
+      } finally {
+        await writer.close();
+      }
+      expect(true).toBeTruthy();
+
+      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,
+      });
+      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),
+      });
+      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,9 +13,10 @@ import { decodeError, errorZ } from "@synnaxlabs/freighter";
 import {
   TimeStamp,
   type CrudeTimeStamp,
-  toArray,
   type CrudeSeries,
-} from "@synnaxlabs/x";
+  TimeSpan,
+} from "@synnaxlabs/x/telem";
+import { toArray } from "@synnaxlabs/x/toArray";
 import { z } from "zod";
 
 import {
@@ -49,12 +50,16 @@ export enum WriterMode {
   StreamOnly = 3,
 }
 
+export const ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT: TimeSpan = new TimeSpan(-1);
+
 const netConfigZ = z.object({
   start: TimeStamp.z.optional(),
   controlSubject: controlSubjectZ.optional(),
   keys: z.number().array().optional(),
   authorities: Authority.z.array().optional(),
   mode: z.nativeEnum(WriterMode).optional(),
+  enableAutoCommit: z.boolean().optional(),
+  autoIndexPersistInterval: TimeSpan.z.optional(),
 });
 
 const reqZ = z.object({
@@ -74,11 +79,27 @@ const resZ = z.object({
 type Response = z.infer<typeof resZ>;
 
 export interface WriterConfig {
+  // channels denote the channels to write to.
   channels: Params;
+  // start sets the starting timestamp for the first sample in the writer.
   start?: CrudeTimeStamp;
+  // controlSubject sets the control subject of the writer.
   controlSubject?: ControlSubject;
+  // authorities set the control authority to set for each channel on the writer.
+  // Defaults to absolute authority. If not working with concurrent control,
+  // it's best to leave this as the default.
   authorities?: Authority | Authority[];
+  // mode sets the persistence and streaming mode of the writer. The default
+  // mode is WriterModePersistStream.
   mode?: WriterMode;
+  //  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;
+  // 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;
 }
 
 /**
@@ -141,6 +162,8 @@ export class Writer {
       authorities = Authority.Absolute,
       controlSubject: subject,
       mode = WriterMode.PersistStream,
+      enableAutoCommit = false,
+      autoIndexPersistInterval = TimeSpan.SECOND,
     }: WriterConfig,
   ): Promise<Writer> {
     const adapter = await WriteFrameAdapter.open(retriever, channels);
@@ -154,6 +177,8 @@ export class Writer {
         controlSubject: subject,
         authorities: toArray(authorities),
         mode,
+        enableAutoCommit,
+        autoIndexPersistInterval,
       },
     });
     return writer;

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";