@synnaxlabs/client 0.42.3 → 0.43.1

package/src/framer/streamer.ts

@@ -9,59 +9,129 @@
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
 import { breaker, observe, TimeSpan } from "@synnaxlabs/x";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { type channel } from "@/channel";
 import { ReadAdapter } from "@/framer/adapter";
 import { WSStreamerCodec } from "@/framer/codec";
 import { Frame, frameZ } from "@/framer/frame";
 import { StreamProxy } from "@/framer/streamProxy";
+import { payloadZ } from "@/ranger/payload";
 
-const reqZ = z.object({ keys: z.number().array(), downSampleFactor: z.number() });
+const reqZ = z.object({ keys: z.number().array(), downsampleFactor: z.number() });
 
-export type StreamerRequest = z.infer<typeof reqZ>;
+/**
+ * Request interface for streaming frames from a Synnax cluster.
+ * Contains the keys of channels to stream from and a downsample factor.
+ */
+export interface StreamerRequest extends z.infer<typeof reqZ> {}
 
 const resZ = z.object({ frame: frameZ });
 
-export type StreamerResponse = z.infer<typeof resZ>;
+/**
+ * Response interface for streaming frames from a Synnax cluster.
+ * Contains a frame of telemetry data.
+ */
+export interface StreamerResponse extends z.infer<typeof resZ> {}
 
 const ENDPOINT = "/frame/stream";
 
+/**
+ * Configuration options for creating a new streamer.
+ */
 export interface StreamerConfig {
+  /** The channels to stream data from. Can be channel keys, names, or payloads. */
   channels: channel.Params;
-  downSampleFactor?: number;
+  /** Optional factor to downsample the data by. Defaults to 1 (no downsampling). */
+  downsampleFactor?: number;
+  /** Whether to use the experimental codec for streaming. Defaults to false. */
   useExperimentalCodec?: boolean;
 }
 
+/**
+ * A streamer is used to stream frames of telemetry in real-time from a Synnax cluster.
+ * It should not be constructed directly, and should instead be created using the
+ * client's openStreamer method.
+ *
+ * To open a streamer, use the openStreamer method on the client and pass it in the list
+ * of channels you'd like to receive data from. Once the streamer has been opened, call
+ * the `read` method to read the next frame of telemetry, or use the streamer as an
+ * async iterator to iterate over the frames of telemetry as they are received.
+ *
+ * The list of channels being streamed can be updated at any time by using the `update`
+ * method.
+ *
+ * Once done, call the `close` method to close the streamer and free all associated
+ * resources. We recommend using the streamer within a try-finally block to ensure
+ * that it is closed properly in the event of an error.
+ *
+ * For details documentation, see https://docs.synnaxlabs.com/reference/typescript-client/stream-data
+ */
 export interface Streamer extends AsyncIterator<Frame>, AsyncIterable<Frame> {
+  /** The keys of the channels currently being streamed from. */
   keys: channel.Key[];
+  /**
+   * Update the list of channels being streamed from. This replaces the list of channels
+   * being streamed from with the new list of channels.
+   */
   update: (channels: channel.Params) => Promise<void>;
+  /** Close the streamer and free all associated resources. */
   close: () => void;
+  /** Read the next frame of telemetry. */
   read: () => Promise<Frame>;
 }
 
+/**
+ * A function that opens a streamer.
+ */
 export interface StreamOpener {
   (config: StreamerConfig | channel.Params): Promise<Streamer>;
 }
 
+export const parseStreamerConfig = (
+  config: StreamerConfig | channel.Params,
+): StreamerConfig => {
+  if (Array.isArray(config)) {
+    if (typeof config[0] === "object")
+      return {
+        channels: (config as channel.Payload[]).map((c) => c.key),
+        downsampleFactor: 1,
+      };
+    return { channels: config, downsampleFactor: 1 };
+  }
+  const parsed = payloadZ.safeParse(config);
+  if (parsed.success) return { channels: [parsed.data.key], downsampleFactor: 1 };
+  return config as StreamerConfig;
+};
+
+/**
+ * Creates a function that opens streamers with the given retriever and client.
+ * @param retriever - The channel retriever to use for resolving channel information
+ * @param client - The WebSocket client to use for streaming
+ * @returns A function that opens streamers with the given configuration
+ */
 export const createStreamOpener =
   (retriever: channel.Retriever, client: WebSocketClient): StreamOpener =>
   async (config) => {
-    let cfg: StreamerConfig;
-    if (Array.isArray(config) || typeof config !== "object")
-      cfg = { channels: config as channel.Params, downSampleFactor: 1 };
-    else cfg = config as StreamerConfig;
+    const cfg = parseStreamerConfig(config);
     const adapter = await ReadAdapter.open(retriever, cfg.channels);
     if (cfg.useExperimentalCodec)
       client = client.withCodec(new WSStreamerCodec(adapter.codec));
     const stream = await client.stream(ENDPOINT, reqZ, resZ);
     const streamer = new CoreStreamer(stream, adapter);
-    stream.send({ keys: adapter.keys, downSampleFactor: cfg.downSampleFactor ?? 1 });
+    stream.send({ keys: adapter.keys, downsampleFactor: cfg.downsampleFactor ?? 1 });
     const [, err] = await stream.receive();
     if (err != null) throw err;
     return streamer;
   };
 
+/**
+ * Opens a new streamer with the given configuration.
+ * @param retriever - The channel retriever to use for resolving channel information
+ * @param client - The WebSocket client to use for streaming
+ * @param config - The configuration for the streamer
+ * @returns A promise that resolves to a new streamer
+ */
 export const openStreamer = async (
   retriever: channel.Retriever,
   client: WebSocketClient,
@@ -101,7 +171,7 @@ class CoreStreamer implements Streamer {
     await this.adapter.update(channels);
     this.stream.send({
       keys: this.adapter.keys,
-      downSampleFactor: this.downsampleFactor,
+      downsampleFactor: this.downsampleFactor,
     });
   }
 
@@ -114,30 +184,46 @@ class CoreStreamer implements Streamer {
   }
 }
 
+/**
+ * A hardened streamer that automatically reconnects on failure.
+ * This streamer wraps a regular streamer and adds automatic reconnection
+ * logic when the connection is lost or errors occur.
+ */
 export class HardenedStreamer implements Streamer {
   private wrapped_: Streamer | null = null;
   private readonly breaker: breaker.Breaker;
   private readonly opener: StreamOpener;
   private readonly config: StreamerConfig;
 
-  private constructor(opener: StreamOpener, config: StreamerConfig | channel.Params) {
+  private constructor(
+    opener: StreamOpener,
+    config: StreamerConfig | channel.Params,
+    breakerConfig: breaker.Config = {},
+  ) {
     this.opener = opener;
-    if (Array.isArray(config) || typeof config !== "object")
-      this.config = { channels: config as channel.Params, downSampleFactor: 1 };
-    else this.config = config as StreamerConfig;
-    this.breaker = new breaker.Breaker({
-      maxRetries: 5000,
-      baseInterval: TimeSpan.seconds(1),
-      scale: 1,
-    });
+    this.config = parseStreamerConfig(config);
+    const {
+      maxRetries = 5000,
+      baseInterval = TimeSpan.seconds(1),
+      scale = 1,
+    } = breakerConfig ?? {};
+    this.breaker = new breaker.Breaker({ maxRetries, baseInterval, scale });
   }
 
+  /**
+   * Opens a new hardened streamer with the given configuration.
+   * @param opener - The function to use for opening streamers
+   * @param config - The configuration for the streamer
+   * @returns A promise that resolves to a new hardened streamer
+   */
   static async open(
     opener: StreamOpener,
     config: StreamerConfig | channel.Params,
+    breakerConfig?: breaker.Config,
   ): Promise<HardenedStreamer> {
-    const h = new HardenedStreamer(opener, config);
+    const h = new HardenedStreamer(opener, config, breakerConfig);
     await h.runStreamer();
+
     return h;
   }
 
@@ -151,6 +237,7 @@ export class HardenedStreamer implements Streamer {
       } catch (e) {
         this.wrapped_ = null;
         if (!(await this.breaker.wait())) throw e;
+        console.error("failed to open streamer", e);
         continue;
       }
   }
@@ -203,6 +290,10 @@ export class HardenedStreamer implements Streamer {
   }
 }
 
+/**
+ * Wraps a standard streamer to implement an observable interface for handling changes
+ * to channel values through an onChange handler.
+ */
 export class ObservableStreamer<V = Frame>
   extends observe.Observer<Frame, V>
   implements observe.ObservableAsyncCloseable<V>
@@ -210,6 +301,13 @@ export class ObservableStreamer<V = Frame>
   private readonly streamer: Streamer;
   private readonly closePromise: Promise<void>;
 
+  /**
+   * Creates a new observable streamer.
+   * @param streamer - The streamer to wrap
+   * @param transform - An optional transform function to apply to each frame
+   * @template V - The type of the transformed value. Only relevant if transform is
+   * provided. Defaults to Frame.
+   */
   constructor(streamer: Streamer, transform?: observe.Transform<Frame, V>) {
     super(transform);
     this.streamer = streamer;

package/src/framer/writer.spec.ts

@@ -13,7 +13,7 @@ import { describe, expect, it, test } from "vitest";
 import { UnauthorizedError, ValidationError } from "@/errors";
 import { ALWAYS_INDEX_PERSIST_ON_AUTO_COMMIT, WriterMode } from "@/framer/writer";
 import { newClient } from "@/setupspecs";
-import { newIndexedPair } from "@/testutil/indexedPair";
+import { newIndexedPair } from "@/testutil/channels";
 import { secondsLinspace } from "@/testutil/telem";
 import { randomSeries } from "@/util/telem";
 

package/src/framer/writer.ts

@@ -8,21 +8,20 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
-import { control, errors } from "@synnaxlabs/x";
+import { array, control, errors } from "@synnaxlabs/x";
 import {
   type CrudeSeries,
   type CrudeTimeStamp,
   TimeSpan,
   TimeStamp,
 } from "@synnaxlabs/x/telem";
-import { toArray } from "@synnaxlabs/x/toArray";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { channel } from "@/channel";
 import { SynnaxError } from "@/errors";
 import { WriteAdapter } from "@/framer/adapter";
 import { WSWriterCodec } from "@/framer/codec";
-import { type Crude, frameZ } from "@/framer/frame";
+import { type CrudeFrame, frameZ } from "@/framer/frame";
 
 export enum WriterCommand {
   Open = 0,
@@ -194,7 +193,7 @@ export class Writer {
         start: new TimeStamp(start),
         keys: adapter.keys,
         controlSubject: subject,
-        authorities: toArray(authorities),
+        authorities: array.toArray(authorities),
         mode: constructWriterMode(mode),
         errOnUnauthorized,
         enableAutoCommit,
@@ -206,9 +205,14 @@ export class Writer {
 
   async write(channel: channel.KeyOrName, data: CrudeSeries): Promise<void>;
   async write(channel: channel.KeysOrNames, data: CrudeSeries[]): Promise<void>;
-  async write(frame: Crude | Record<channel.KeyOrName, CrudeSeries>): Promise<void>;
   async write(
-    channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
+    frame: CrudeFrame | Record<channel.KeyOrName, CrudeSeries>,
+  ): Promise<void>;
+  async write(
+    channelsOrData:
+      | channel.Params
+      | Record<channel.KeyOrName, CrudeSeries>
+      | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<void>;
 
@@ -227,7 +231,10 @@ export class Writer {
    * should acknowledge the error by calling the error method or closing the writer.
    */
   async write(
-    channelsOrData: channel.Params | Record<channel.KeyOrName, CrudeSeries> | Crude,
+    channelsOrData:
+      | channel.Params
+      | Record<channel.KeyOrName, CrudeSeries>
+      | CrudeFrame,
     series?: CrudeSeries | CrudeSeries[],
   ): Promise<void> {
     if (this.closeErr != null) throw this.closeErr;

package/src/hardware/device/client.ts

@@ -8,9 +8,9 @@
 // included in the file licenses/APL.txt.
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
-import { toArray, type UnknownRecord } from "@synnaxlabs/x";
+import { array, type UnknownRecord } from "@synnaxlabs/x";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { framer } from "@/framer";
 import {
@@ -118,7 +118,7 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     const res = await sendRequired(
       this.client,
       RETRIEVE_ENDPOINT,
-      { keys: toArray(keys), ...options },
+      { keys: array.toArray(keys), ...options },
       retrieveReqZ,
       retrieveResZ,
     );
@@ -173,7 +173,7 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     const res = await sendRequired(
       this.client,
       CREATE_ENDPOINT,
-      { devices: toArray(devices) },
+      { devices: array.toArray(devices) },
       createReqZ,
       createResZ,
     );
@@ -186,7 +186,7 @@ export class Client implements AsyncTermSearcher<string, Key, Device> {
     await sendRequired(
       this.client,
       DELETE_ENDPOINT,
-      { keys: toArray(keys) },
+      { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
     );

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

@@ -19,16 +19,17 @@ describe("Device", async () => {
   const testRack = await client.hardware.racks.create({ name: "test" });
   describe("create", () => {
     it("should create a device on a rack", async () => {
+      const key = id.create();
       const d = await client.hardware.devices.create({
         rack: testRack.key,
         location: "Dev1",
-        key: "SN222",
+        key,
         name: "test",
         make: "ni",
         model: "dog",
         properties: { cat: "dog" },
       });
-      expect(d.key).toEqual("SN222");
+      expect(d.key).toEqual(key);
       expect(d.name).toBe("test");
       expect(d.make).toBe("ni");
     });
@@ -41,7 +42,7 @@ describe("Device", async () => {
       outputChannels: [{ port2: 232 }],
     };
     const d = await client.hardware.devices.create({
-      key: "SN222",
+      key: id.create(),
       rack: testRack.key,
       location: "Dev1",
       name: "test",
@@ -55,7 +56,7 @@ describe("Device", async () => {
   describe("retrieve", () => {
     it("should retrieve a device by its key", async () => {
       const d = await client.hardware.devices.create({
-        key: "SN222",
+        key: id.create(),
         rack: testRack.key,
         location: "Dev1",
         name: "test",
@@ -112,7 +113,7 @@ describe("Device", async () => {
     describe("state", () => {
       it("should not include state by default", async () => {
         const d = await client.hardware.devices.create({
-          key: "SN_STATE_TEST1",
+          key: id.create(),
           rack: testRack.key,
           location: "Dev1",
           name: "state_test1",
@@ -122,12 +123,12 @@ describe("Device", async () => {
         });
 
         const retrieved = await client.hardware.devices.retrieve(d.key);
-        expect(retrieved.state?.key).toHaveLength(0);
+        expect(retrieved.state).toBeUndefined();
       });
 
       it("should include state when includeState is true", async () => {
         const d = await client.hardware.devices.create({
-          key: "SN_STATE_TEST2",
+          key: id.create(),
           rack: testRack.key,
           location: "Dev1",
           name: "state_test2",
@@ -136,20 +137,19 @@ describe("Device", async () => {
           properties: { cat: "dog" },
         });
 
-        const retrieved = await client.hardware.devices.retrieve(d.key, {
-          includeState: true,
-        });
-        expect(retrieved.state).toBeDefined();
-        if (retrieved.state) {
-          expect(retrieved.state.variant).toBeDefined();
-          expect(retrieved.state.key).toBeDefined();
-          expect(retrieved.state.details).toBeDefined();
-        }
+        await expect
+          .poll(async () => {
+            const { state } = await client.hardware.devices.retrieve(d.key, {
+              includeState: true,
+            });
+            return state !== undefined;
+          })
+          .toBeTruthy();
       });
 
       it("should include state for multiple devices", async () => {
         const d1 = await client.hardware.devices.create({
-          key: "SN_STATE_TEST3",
+          key: id.create(),
           rack: testRack.key,
           location: "Dev1",
           name: "state_test3",
@@ -159,7 +159,7 @@ describe("Device", async () => {
         });
 
         const d2 = await client.hardware.devices.create({
-          key: "SN_STATE_TEST4",
+          key: id.create(),
           rack: testRack.key,
           location: "Dev2",
           name: "state_test4",
@@ -168,18 +168,16 @@ describe("Device", async () => {
           properties: { cat: "dog" },
         });
 
-        const retrieved = await client.hardware.devices.retrieve([d1.key, d2.key], {
-          includeState: true,
-        });
-        expect(retrieved).toHaveLength(2);
-        retrieved.forEach((device) => {
-          expect(device.state).toBeDefined();
-          if (device.state) {
-            expect(device.state.variant).toBeDefined();
-            expect(device.state.key).toBeDefined();
-            expect(device.state.details).toBeDefined();
-          }
-        });
+        await expect
+          .poll(async () => {
+            const retrievedDevices = await client.hardware.devices.retrieve(
+              [d1.key, d2.key],
+              { includeState: true },
+            );
+            if (retrievedDevices.length !== 2) return false;
+            return retrievedDevices.every(({ state }) => state !== undefined);
+          })
+          .toBeTruthy();
       });
 
       it("should handle state with type-safe details", async () => {

package/src/hardware/device/payload.ts

@@ -7,8 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { binary, type UnknownRecord, unknownRecordZ } from "@synnaxlabs/x";
-import { z } from "zod";
+import { binary, status, type UnknownRecord, unknownRecordZ, zod } from "@synnaxlabs/x";
+import { z } from "zod/v4";
 
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
 import { decodeJSONString } from "@/util/decodeJSONString";
@@ -18,7 +18,7 @@ export type Key = z.infer<typeof keyZ>;
 
 export const stateZ = z.object({
   key: keyZ,
-  variant: z.string(),
+  variant: status.variantZ.or(z.literal("").transform<status.Variant>(() => "info")),
   details: unknownRecordZ.or(z.string().transform(decodeJSONString)),
 });
 
@@ -36,7 +36,7 @@ export const deviceZ = z.object({
   location: z.string(),
   configured: z.boolean().optional(),
   properties: unknownRecordZ.or(z.string().transform(decodeJSONString)),
-  state: stateZ.optional(),
+  state: zod.nullToUndefined(stateZ),
 });
 
 export interface Device<
@@ -44,7 +44,7 @@ export interface Device<
   Make extends string = string,
   Model extends string = string,
   StateDetails extends {} = UnknownRecord,
-> extends Omit<z.output<typeof deviceZ>, "properties" | "state"> {
+> extends Omit<z.infer<typeof deviceZ>, "properties" | "state"> {
   properties: Properties;
   make: Make;
   model: Model;

package/src/hardware/rack/client.ts

@@ -9,9 +9,9 @@
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { type UnknownRecord } from "@synnaxlabs/x";
+import { array } from "@synnaxlabs/x/array";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
-import { toArray } from "@synnaxlabs/x/toArray";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { framer } from "@/framer";
 import {
@@ -81,7 +81,7 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
       this.client,
       DELETE_ENDPOINT,
-      { keys: toArray(keys) },
+      { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
     );
@@ -94,7 +94,7 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     const res = await sendRequired<typeof createReqZ, typeof createResZ>(
       this.client,
       CREATE_ENDPOINT,
-      { racks: toArray(rack) },
+      { racks: array.toArray(rack) },
       createReqZ,
       createResZ,
     );

package/src/hardware/rack/payload.ts

@@ -7,18 +7,18 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { zod } from "@synnaxlabs/x";
+import { status, zod } from "@synnaxlabs/x";
 import { TimeStamp } from "@synnaxlabs/x/telem";
-import { z } from "zod";
+import { z } from "zod/v4";
 
-export const keyZ = zod.uint32;
+export const keyZ = z.uint32();
 export type Key = z.infer<typeof keyZ>;
 
 export const stateZ = z.object({
   key: keyZ,
-  variant: z.string(),
+  variant: status.variantZ.or(z.literal("").transform<status.Variant>(() => "info")),
   message: z.string(),
-  lastReceived: TimeStamp.z.optional(),
+  lastReceived: TimeStamp.z,
 });
 
 export interface State extends z.infer<typeof stateZ> {}
@@ -26,7 +26,7 @@ export interface State extends z.infer<typeof stateZ> {}
 export const rackZ = z.object({
   key: keyZ,
   name: z.string(),
-  state: stateZ.optional(),
+  state: zod.nullToUndefined(stateZ),
 });
 
 export interface Payload extends z.infer<typeof rackZ> {}

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

@@ -9,7 +9,7 @@
 
 import { TimeStamp } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
-import { ZodError } from "zod";
+import { ZodError } from "zod/v4";
 
 import { NotFoundError } from "@/errors";
 import { newClient } from "@/setupspecs";

package/src/hardware/task/client.ts

@@ -9,11 +9,11 @@
 
 import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { id } from "@synnaxlabs/x";
+import { array } from "@synnaxlabs/x/array";
 import { type UnknownRecord } from "@synnaxlabs/x/record";
 import { type AsyncTermSearcher } from "@synnaxlabs/x/search";
 import { type CrudeTimeSpan, TimeSpan } from "@synnaxlabs/x/telem";
-import { toArray } from "@synnaxlabs/x/toArray";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { framer } from "@/framer";
 import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
@@ -264,7 +264,7 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     const res = await sendRequired<typeof createReqZ, typeof createResZ>(
       this.client,
       CREATE_ENDPOINT,
-      { tasks: toArray(task) },
+      { tasks: array.toArray(task) },
       createReqZ,
       createResZ,
     );
@@ -276,7 +276,7 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
     await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
       this.client,
       DELETE_ENDPOINT,
-      { keys: toArray(keys) },
+      { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
     );
@@ -393,21 +393,23 @@ export class Client implements AsyncTermSearcher<string, Key, Payload> {
 
   sugar(payloads: Payload | Payload[]): Task | Task[] {
     const isSingle = !Array.isArray(payloads);
-    const res = toArray(payloads).map(
-      ({ key, name, type, config, state, internal, snapshot }) =>
-        new Task(
-          key,
-          name,
-          type,
-          config,
-          internal,
-          snapshot,
-          state,
-          this.frameClient,
-          this.ontologyClient,
-          this.rangeClient,
-        ),
-    );
+    const res = array
+      .toArray(payloads)
+      .map(
+        ({ key, name, type, config, state, internal, snapshot }) =>
+          new Task(
+            key,
+            name,
+            type,
+            config,
+            internal,
+            snapshot,
+            state,
+            this.frameClient,
+            this.ontologyClient,
+            this.rangeClient,
+          ),
+      );
     return isSingle ? res[0] : res;
   }