@synnaxlabs/client 0.43.1 → 0.44.2

package/src/framer/iterator.spec.ts

@@ -11,12 +11,12 @@ import { TimeRange, TimeSpan, TimeStamp } from "@synnaxlabs/x/telem";
 import { describe, expect, test } from "vitest";
 
 import { AUTO_SPAN } from "@/framer/iterator";
-import { newClient } from "@/setupspecs";
 import { newIndexedPair } from "@/testutil/channels";
+import { createTestClient } from "@/testutil/client";
 import { secondsLinspace } from "@/testutil/telem";
 import { randomSeries } from "@/util/telem";
 
-const client = newClient();
+const client = createTestClient();
 
 describe("Iterator", () => {
   test("happy path", async () => {
@@ -50,7 +50,7 @@ describe("Iterator", () => {
     );
 
     try {
-      expect(await iter.seekFirst()).toBeTruthy();
+      expect(await iter.seekFirst()).toBe(true);
       let c = 0;
       while (await iter.next(TimeSpan.seconds(1))) {
         c++;
@@ -78,24 +78,24 @@ describe("Iterator", () => {
     const iter = await client.openIterator(TimeRange.MAX, channels, { chunkSize: 4 });
 
     try {
-      expect(await iter.seekFirst()).toBeTruthy();
+      expect(await iter.seekFirst()).toBe(true);
 
-      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(await iter.next(AUTO_SPAN)).toBe(true);
       expect(iter.value.get(idx_ch.key).data).toEqual(
         new BigInt64Array(secondsLinspace(1, 4).map((v) => v.valueOf())),
       );
 
-      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(await iter.next(AUTO_SPAN)).toBe(true);
       expect(iter.value.get(idx_ch.key).data).toEqual(
         new BigInt64Array(secondsLinspace(5, 4).map((v) => v.valueOf())),
       );
 
-      expect(await iter.next(AUTO_SPAN)).toBeTruthy();
+      expect(await iter.next(AUTO_SPAN)).toBe(true);
       expect(iter.value.get(idx_ch.key).data).toEqual(
         new BigInt64Array(secondsLinspace(9, 2).map((v) => v.valueOf())),
       );
 
-      expect(await iter.next(AUTO_SPAN)).toBeFalsy();
+      expect(await iter.next(AUTO_SPAN)).toBe(false);
     } finally {
       await iter.close();
     }

package/src/framer/iterator.ts

@@ -17,7 +17,7 @@ import {
   TimeSpan,
   TimeStamp,
 } from "@synnaxlabs/x/telem";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { channel } from "@/channel";
 import { ReadAdapter } from "@/framer/adapter";

package/src/framer/streamProxy.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { EOF, type Stream } from "@synnaxlabs/freighter";
-import { type z } from "zod/v4";
+import { type z } from "zod";
 
 export class StreamProxy<RQ extends z.ZodType, RS extends z.ZodType> {
   readonly name: string;

package/src/framer/streamer.spec.ts

@@ -15,13 +15,14 @@ import { type channel } from "@/channel";
 import { Frame } from "@/framer/frame";
 import {
   HardenedStreamer,
-  parseStreamerConfig,
+  ObservableStreamer,
   type Streamer,
+  streamerConfigZ,
 } from "@/framer/streamer";
-import { newClient } from "@/setupspecs";
 import { newVirtualChannel } from "@/testutil/channels";
+import { createTestClient } from "@/testutil/client";
 
-const client = newClient();
+const client = createTestClient();
 
 describe("Streamer", () => {
   describe("standard", () => {
@@ -273,55 +274,60 @@ describe("Streamer", () => {
     });
   });
 
-  describe("hardened", () => {
-    class MockStreamer implements Streamer {
-      keys: channel.Key[] = [];
-      updateMock = vi.fn();
-      readMock = vi.fn();
-      closeMock = vi.fn();
-      responses: [Frame, Error | null][] = [];
-      updateErrors: (Error | null)[] = [];
-
-      update(channels: channel.Params): Promise<void> {
-        if (this.updateErrors.length > 0) {
-          const err = this.updateErrors.shift()!;
-          if (err) throw err;
-        }
-        this.updateMock(channels);
-        return Promise.resolve();
+  class MockStreamer implements Streamer {
+    keys: channel.Key[] = [];
+    updateMock = vi.fn();
+    readMock = vi.fn();
+    closeMock = vi.fn();
+    responses: [Frame, Error | null][] = [];
+    updateErrors: (Error | null)[] = [];
+
+    update(channels: channel.Params): Promise<void> {
+      if (this.updateErrors.length > 0) {
+        const err = this.updateErrors.shift()!;
+        if (err) throw err;
       }
+      this.updateMock(channels);
+      return Promise.resolve();
+    }
 
-      close(): void {
-        this.closeMock();
-      }
+    close(): void {
+      this.closeMock();
+    }
 
-      async read(): Promise<Frame> {
-        this.readMock();
-        if (this.responses.length === 0) throw new EOF();
-        const [frame, err] = this.responses.shift()!;
-        if (err) throw err;
-        return frame;
-      }
+    async read(): Promise<Frame> {
+      this.readMock();
+      if (this.responses.length === 0) throw new EOF();
+      const [frame, err] = this.responses.shift()!;
+      if (err) throw err;
+      return frame;
+    }
 
-      async next(): Promise<IteratorResult<Frame, any>> {
+    async next(): Promise<IteratorResult<Frame, any>> {
+      try {
         const fr = await this.read();
         return { done: false, value: fr };
+      } catch (err) {
+        if (EOF.matches(err)) return { done: true, value: undefined };
+        throw err;
       }
+    }
 
-      [Symbol.asyncIterator](): AsyncIterator<Frame, any, undefined> {
-        return this;
-      }
+    [Symbol.asyncIterator](): AsyncIterator<Frame, any, undefined> {
+      return this;
     }
+  }
 
+  describe("hardened", () => {
     it("should correctly call the underlying streamer methods", async () => {
       const streamer = new MockStreamer();
       const openMock = vi.fn();
-      const config = { channels: [1, 2, 3] };
+      const config = { channels: [1, 2, 3], useExperimentalCodec: false };
       const fr = new Frame({ 1: new Series([1]) });
       const hardened = await HardenedStreamer.open(
         async (cfg) => {
           openMock(cfg);
-          const cfg_ = parseStreamerConfig(cfg);
+          const cfg_ = streamerConfigZ.parse(cfg);
           streamer.responses = [[fr, null]];
           streamer.keys = cfg_.channels as channel.Key[];
           return streamer;
@@ -329,7 +335,10 @@ describe("Streamer", () => {
         { channels: [1, 2, 3] },
       );
       expect(hardened.keys).toEqual([1, 2, 3]);
-      expect(openMock).toHaveBeenCalledWith(config);
+      expect(openMock).toHaveBeenCalledWith({
+        ...config,
+        downsampleFactor: 1,
+      });
       await hardened.update([1, 2, 3]);
       expect(streamer.updateMock).toHaveBeenCalledWith([1, 2, 3]);
       const fr2 = await hardened.read();
@@ -465,4 +474,144 @@ describe("Streamer", () => {
       expect(openerMock).toHaveBeenCalledTimes(2);
     });
   });
+
+  describe("observable", () => {
+    it("should notify observers when frames are received", async () => {
+      const mockStreamer = new MockStreamer();
+      const frame1 = new Frame({ 1: new Series([1, 2, 3]) });
+      const frame2 = new Frame({ 1: new Series([4, 5, 6]) });
+
+      mockStreamer.responses = [
+        [frame1, null],
+        [frame2, null],
+      ];
+      mockStreamer.keys = [1];
+
+      const observable = new ObservableStreamer(mockStreamer);
+
+      const receivedFrames: Frame[] = [];
+      observable.onChange((frame) => {
+        receivedFrames.push(frame);
+      });
+
+      await expect.poll(() => receivedFrames.length).toBe(2);
+      expect(receivedFrames[0]).toEqual(frame1);
+      expect(receivedFrames[1]).toEqual(frame2);
+
+      await observable.close();
+      expect(mockStreamer.closeMock).toHaveBeenCalled();
+    });
+
+    test("should apply transform function to frames", async () => {
+      const mockStreamer = new MockStreamer();
+      const frame1 = new Frame({ 1: new Series([1, 2, 3]) });
+      const frame2 = new Frame({ 1: new Series([4, 5, 6]) });
+
+      mockStreamer.responses = [
+        [frame1, null],
+        [frame2, null],
+      ];
+      mockStreamer.keys = [1];
+
+      const transform = (frame: Frame): [number, true] | [null, false] => {
+        try {
+          const data = Array.from(frame.get(1));
+          const firstValue = data[0] as number;
+          return [firstValue, true];
+        } catch {
+          return [null, false];
+        }
+      };
+
+      const observable = new ObservableStreamer(mockStreamer, transform);
+
+      const receivedValues: number[] = [];
+      observable.onChange((value) => {
+        if (value !== null) receivedValues.push(value);
+      });
+
+      await expect.poll(() => receivedValues.length).toBe(2);
+      expect(receivedValues[0]).toBe(1);
+      expect(receivedValues[1]).toBe(4);
+
+      await observable.close();
+    });
+
+    test("should handle multiple observers", async () => {
+      const mockStreamer = new MockStreamer();
+      const frame1 = new Frame({ 1: new Series([10, 20]) });
+
+      mockStreamer.responses = [[frame1, null]];
+      mockStreamer.keys = [1];
+
+      const observable = new ObservableStreamer(mockStreamer);
+
+      const observer1Results: Frame[] = [];
+      const observer2Results: Frame[] = [];
+
+      observable.onChange((frame) => {
+        observer1Results.push(frame);
+      });
+
+      observable.onChange((frame) => {
+        observer2Results.push(frame);
+      });
+
+      await expect.poll(() => observer1Results.length).toBe(1);
+      expect(observer2Results).toHaveLength(1);
+      expect(observer1Results[0]).toEqual(frame1);
+      expect(observer2Results[0]).toEqual(frame1);
+
+      await observable.close();
+    });
+
+    test("should update channels on underlying streamer", async () => {
+      const mockStreamer = new MockStreamer();
+      mockStreamer.keys = [1, 2];
+
+      const observable = new ObservableStreamer(mockStreamer);
+
+      await observable.update([3, 4, 5]);
+
+      expect(mockStreamer.updateMock).toHaveBeenCalledWith([3, 4, 5]);
+
+      await observable.close();
+    });
+
+    test("should handle empty frame stream gracefully", async () => {
+      const mockStreamer = new MockStreamer();
+      mockStreamer.keys = [1];
+
+      const observable = new ObservableStreamer(mockStreamer);
+
+      const receivedFrames: Frame[] = [];
+      observable.onChange((frame) => {
+        receivedFrames.push(frame);
+      });
+
+      await expect.poll(() => receivedFrames.length).toBe(0);
+      expect(receivedFrames).toHaveLength(0);
+
+      await observable.close();
+    });
+
+    test("should properly close and cleanup resources", async () => {
+      const mockStreamer = new MockStreamer();
+      const frame1 = new Frame({ 1: new Series([1]) });
+
+      mockStreamer.responses = [[frame1, null]];
+      mockStreamer.keys = [1];
+
+      const observable = new ObservableStreamer(mockStreamer);
+
+      const receivedFrames: Frame[] = [];
+      observable.onChange((frame) => {
+        receivedFrames.push(frame);
+      });
+
+      await observable.close();
+
+      expect(mockStreamer.closeMock).toHaveBeenCalled();
+    });
+  });
 });

package/src/framer/streamer.ts

@@ -9,14 +9,14 @@
 
 import { EOF, type Stream, type WebSocketClient } from "@synnaxlabs/freighter";
 import { breaker, observe, TimeSpan } from "@synnaxlabs/x";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { type channel } from "@/channel";
+import { paramsZ } from "@/channel/payload";
 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() });
 
@@ -36,17 +36,21 @@ export interface StreamerResponse extends z.infer<typeof resZ> {}
 
 const ENDPOINT = "/frame/stream";
 
-/**
- * Configuration options for creating a new streamer.
- */
-export interface StreamerConfig {
+const intermediateStreamerConfigZ = z.object({
   /** The channels to stream data from. Can be channel keys, names, or payloads. */
-  channels: channel.Params;
+  channels: paramsZ,
   /** 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;
-}
+  downsampleFactor: z.number().optional().default(1),
+  /** Whether to use the experimental codec for streaming. Defaults to true. */
+  useExperimentalCodec: z.boolean().optional().default(false),
+});
+
+export const streamerConfigZ = intermediateStreamerConfigZ.or(
+  paramsZ.transform((channels) => intermediateStreamerConfigZ.parse({ channels })),
+);
+
+export type StreamerConfig = z.input<typeof streamerConfigZ>;
+type ParsedStreamerConfig = z.output<typeof streamerConfigZ>;
 
 /**
  * A streamer is used to stream frames of telemetry in real-time from a Synnax cluster.
@@ -85,25 +89,9 @@ export interface Streamer extends AsyncIterator<Frame>, AsyncIterable<Frame> {
  * A function that opens a streamer.
  */
 export interface StreamOpener {
-  (config: StreamerConfig | channel.Params): Promise<Streamer>;
+  (config: StreamerConfig): 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
@@ -113,7 +101,7 @@ export const parseStreamerConfig = (
 export const createStreamOpener =
   (retriever: channel.Retriever, client: WebSocketClient): StreamOpener =>
   async (config) => {
-    const cfg = parseStreamerConfig(config);
+    const cfg = streamerConfigZ.parse(config);
     const adapter = await ReadAdapter.open(retriever, cfg.channels);
     if (cfg.useExperimentalCodec)
       client = client.withCodec(new WSStreamerCodec(adapter.codec));
@@ -168,7 +156,8 @@ class CoreStreamer implements Streamer {
   }
 
   async update(channels: channel.Params): Promise<void> {
-    await this.adapter.update(channels);
+    const hasChanged = await this.adapter.update(channels);
+    if (!hasChanged) return;
     this.stream.send({
       keys: this.adapter.keys,
       downsampleFactor: this.downsampleFactor,
@@ -193,15 +182,15 @@ export class HardenedStreamer implements Streamer {
   private wrapped_: Streamer | null = null;
   private readonly breaker: breaker.Breaker;
   private readonly opener: StreamOpener;
-  private readonly config: StreamerConfig;
+  private readonly config: ParsedStreamerConfig;
 
   private constructor(
     opener: StreamOpener,
-    config: StreamerConfig | channel.Params,
+    config: StreamerConfig,
     breakerConfig: breaker.Config = {},
   ) {
     this.opener = opener;
-    this.config = parseStreamerConfig(config);
+    this.config = streamerConfigZ.parse(config);
     const {
       maxRetries = 5000,
       baseInterval = TimeSpan.seconds(1),
@@ -218,12 +207,11 @@ export class HardenedStreamer implements Streamer {
    */
   static async open(
     opener: StreamOpener,
-    config: StreamerConfig | channel.Params,
+    config: StreamerConfig,
     breakerConfig?: breaker.Config,
   ): Promise<HardenedStreamer> {
     const h = new HardenedStreamer(opener, config, breakerConfig);
     await h.runStreamer();
-
     return h;
   }
 
@@ -248,7 +236,7 @@ export class HardenedStreamer implements Streamer {
   }
 
   async update(channels: channel.Params): Promise<void> {
-    this.config.channels = channels;
+    this.config.channels = paramsZ.parse(channels);
     try {
       await this.wrapped.update(channels);
     } catch {
@@ -314,6 +302,10 @@ export class ObservableStreamer<V = Frame>
     this.closePromise = this.stream();
   }
 
+  async update(channels: channel.Params): Promise<void> {
+    await this.streamer.update(channels);
+  }
+
   async close(): Promise<void> {
     this.streamer.close();
     await this.closePromise;

package/src/framer/writer.spec.ts

@@ -12,12 +12,13 @@ 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/channels";
+import { createTestClient } from "@/testutil/client";
 import { secondsLinspace } from "@/testutil/telem";
 import { randomSeries } from "@/util/telem";
 
-const client = newClient();
+const client = createTestClient();
+
 describe("Writer", () => {
   describe("Writer", () => {
     test("basic write", async () => {
@@ -34,7 +35,7 @@ describe("Writer", () => {
       } finally {
         await writer.close();
       }
-      expect(true).toBeTruthy();
+      expect(true).toBe(true);
     });
 
     test("write to unknown channel key", async () => {
@@ -87,7 +88,7 @@ describe("Writer", () => {
       } finally {
         await writer.close();
       }
-      expect(true).toBeTruthy();
+      expect(true).toBe(true);
 
       const f = await client.read(
         new TimeRange(TimeStamp.seconds(1), TimeStamp.seconds(11)),
@@ -113,7 +114,7 @@ describe("Writer", () => {
       } finally {
         await writer.close();
       }
-      expect(true).toBeTruthy();
+      expect(true).toBe(true);
     });
 
     test("write with auto commit and a set interval", async () => {
@@ -133,7 +134,7 @@ describe("Writer", () => {
       } finally {
         await writer.close();
       }
-      expect(true).toBeTruthy();
+      expect(true).toBe(true);
     });
 
     test("write with auto-commit off and incorrect data length validation error", async () => {