@synnaxlabs/client 0.47.0 → 0.48.0

package/src/connection.spec.ts

@@ -0,0 +1,145 @@
+// Copyright 2025 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 { describe, expect, it } from "vitest";
+import { z } from "zod";
+
+import { checkConnection, newConnectionChecker } from "@/client";
+import { TEST_CLIENT_PARAMS } from "@/testutil/client";
+
+describe("checkConnection", () => {
+  it("should check connection to the server", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(state.status).toEqual("connected");
+    expect(z.uuid().safeParse(state.clusterKey).success).toBe(true);
+  });
+
+  it("should include client version in the connection check", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(state.clientVersion).toBeDefined();
+    expect(state.clientServerCompatible).toBe(true);
+  });
+
+  it("should support custom name parameter", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "test-client",
+    });
+    expect(state.status).toEqual("connected");
+  });
+
+  it("should handle connection failure to invalid host", async () => {
+    const state = await checkConnection({
+      host: "invalid-host-that-does-not-exist",
+      port: 9999,
+      secure: false,
+      retry: {
+        maxRetries: 0, // Disable retries for faster test
+      },
+    });
+    expect(state.status).toEqual("failed");
+  });
+
+  it("should handle connection failure to invalid port", async () => {
+    const state = await checkConnection({
+      host: TEST_CLIENT_PARAMS.host,
+      port: 9999, // Wrong port
+      secure: false,
+      retry: {
+        maxRetries: 0, // Disable retries for faster test
+      },
+    });
+    expect(state.status).toEqual("failed");
+  });
+});
+
+describe("newConnectionChecker", () => {
+  it("should create a connection checker", () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    expect(checker).toBeDefined();
+  });
+
+  it("should create a checker that can check connection", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    const state = await checker.check();
+    expect(state.status).toEqual("connected");
+    expect(z.uuid().safeParse(state.clusterKey).success).toBe(true);
+  });
+
+  it("should support custom name parameter", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "custom-checker-name",
+    });
+    const state = await checker.check();
+    expect(state.status).toEqual("connected");
+  });
+
+  it("should support secure connection parameter", () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: true,
+    });
+    expect(checker).toBeDefined();
+  });
+
+  it("should create multiple independent checkers", async () => {
+    const checker1 = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "checker-1",
+    });
+    const checker2 = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+      name: "checker-2",
+    });
+
+    const state1 = await checker1.check();
+    const state2 = await checker2.check();
+
+    expect(state1.status).toEqual("connected");
+    expect(state2.status).toEqual("connected");
+    expect(checker1).not.toBe(checker2); // Different instances
+  });
+
+  it("should handle version compatibility checking", async () => {
+    const checker = newConnectionChecker({
+      host: TEST_CLIENT_PARAMS.host,
+      port: TEST_CLIENT_PARAMS.port,
+      secure: false,
+    });
+    const state = await checker.check();
+    expect(state.clientVersion).toBeDefined();
+    expect(state.clientServerCompatible).toBe(true);
+  });
+});

package/src/framer/adapter.spec.ts

@@ -213,9 +213,10 @@ describe("WriteFrameAdapter", () => {
   });
 });
 
-describe("ReadAdapter", () => {
+describe("ReadFrameAdapter", () => {
   let timeCh: channel.Channel;
   let dataCh: channel.Channel;
+  let extraCh: channel.Channel;
   let adapter: ReadAdapter;
 
   beforeAll(async () => {
@@ -229,6 +230,11 @@ describe("ReadAdapter", () => {
       dataType: DataType.FLOAT32,
       index: timeCh.key,
     });
+    extraCh = await client.channels.create({
+      name: `read-extra-${Math.random()}-${TimeStamp.now().toString()}`,
+      dataType: DataType.FLOAT64,
+      index: timeCh.key,
+    });
 
     adapter = await ReadAdapter.open(client.channels.retriever, [
       timeCh.key,
@@ -236,6 +242,338 @@ describe("ReadAdapter", () => {
     ]);
   });
 
+  describe("adapt", () => {
+    describe("with keys (no conversion)", () => {
+      describe("hot path - exact channel match", () => {
+        it("should return frame unchanged when all channels match", () => {
+          // HOT PATH: Frame has exactly the channels registered with adapter
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [dataCh.key]: new Series([1.5]),
+          });
+
+          const result = adapter.adapt(inputFrame);
+
+          // Frame should be returned unchanged (zero allocations)
+          expect(result).toBe(inputFrame); // Same object reference
+          expect(result.columns).toHaveLength(2);
+          expect(result.has(timeCh.key)).toBe(true);
+          expect(result.has(dataCh.key)).toBe(true);
+          expect(result.get(timeCh.key).at(0)).toEqual(ts);
+          expect(result.get(dataCh.key).at(0)).toEqual(1.5);
+        });
+
+        it("should preserve series data types in hot path", () => {
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series({ data: [ts], dataType: DataType.TIMESTAMP }),
+            [dataCh.key]: new Series({ data: [1.5], dataType: DataType.FLOAT32 }),
+          });
+
+          const result = adapter.adapt(inputFrame);
+
+          // Data types should be preserved
+          expect(result.get(timeCh.key).dataType).toEqual(DataType.TIMESTAMP);
+          expect(result.get(dataCh.key).dataType).toEqual(DataType.FLOAT32);
+        });
+      });
+
+      describe("cold path - filtering needed", () => {
+        it("should filter out extra channels in key mode", () => {
+          // COLD PATH: Frame has extra channels not in adapter
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [dataCh.key]: new Series([1.5]),
+            [extraCh.key]: new Series([999.0]), // Extra channel
+          });
+
+          const result = adapter.adapt(inputFrame);
+
+          // Should filter out extraCh
+          expect(result).not.toBe(inputFrame); // Different object (filtered)
+          expect(result.columns).toHaveLength(2);
+          expect(result.has(timeCh.key)).toBe(true);
+          expect(result.has(dataCh.key)).toBe(true);
+          expect(result.has(extraCh.key)).toBe(false);
+        });
+
+        it("should handle partial matches in key mode", () => {
+          // Frame has some matching and some extra channels
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [extraCh.key]: new Series([999.0]),
+          });
+
+          const result = adapter.adapt(inputFrame);
+
+          expect(result.columns).toHaveLength(1);
+          expect(result.has(timeCh.key)).toBe(true);
+          expect(result.has(extraCh.key)).toBe(false);
+        });
+
+        it("should return empty frame when no channels match in key mode", () => {
+          const inputFrame = new Frame({
+            [extraCh.key]: new Series([999.0]),
+          });
+
+          const result = adapter.adapt(inputFrame);
+
+          expect(result.columns).toHaveLength(0);
+          expect(result.series).toHaveLength(0);
+        });
+      });
+    });
+
+    describe("with names (conversion)", () => {
+      let nameAdapter: ReadAdapter;
+
+      beforeAll(async () => {
+        // Create adapter with channel names (triggers key-to-name mapping)
+        nameAdapter = await ReadAdapter.open(client.channels.retriever, [
+          timeCh.name,
+          dataCh.name,
+        ]);
+      });
+
+      describe("hot path - exact match, only convert", () => {
+        it("should convert channel keys to names when all channels match", () => {
+          // HOT PATH: Frame has exactly the channels in adapter
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [dataCh.key]: new Series([2.5]),
+          });
+
+          const result = nameAdapter.adapt(inputFrame);
+
+          // Output should have names instead of keys (one allocation for conversion)
+          expect(result.columns).toHaveLength(2);
+          expect(result.has(timeCh.name)).toBe(true);
+          expect(result.has(dataCh.name)).toBe(true);
+          expect(result.get(timeCh.name).at(0)).toEqual(ts);
+          expect(result.get(dataCh.name).at(0)).toEqual(2.5);
+        });
+
+        it("should handle multiple values in hot path", () => {
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts, ts + 1000n]),
+            [dataCh.key]: new Series([1.0, 2.0]),
+          });
+
+          const result = nameAdapter.adapt(inputFrame);
+
+          expect(result.columns).toHaveLength(2);
+          expect(result.get(timeCh.name)).toHaveLength(2);
+          expect(result.get(dataCh.name)).toHaveLength(2);
+          expect(result.get(timeCh.name).at(0)).toEqual(ts);
+          expect(result.get(timeCh.name).at(1)).toEqual(ts + 1000n);
+          expect(result.get(dataCh.name).at(0)).toEqual(1.0);
+          expect(result.get(dataCh.name).at(1)).toEqual(2.0);
+        });
+
+        it("should preserve data types during name conversion", () => {
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series({ data: [ts], dataType: DataType.TIMESTAMP }),
+            [dataCh.key]: new Series({ data: [3.5], dataType: DataType.FLOAT32 }),
+          });
+
+          const result = nameAdapter.adapt(inputFrame);
+
+          expect(result.get(timeCh.name).dataType).toEqual(DataType.TIMESTAMP);
+          expect(result.get(dataCh.name).dataType).toEqual(DataType.FLOAT32);
+        });
+      });
+
+      describe("cold path - filter and convert", () => {
+        it("should filter out extra channels while converting", async () => {
+          // COLD PATH: Frame has extra channels that need filtering
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [dataCh.key]: new Series([1.5]),
+            [extraCh.key]: new Series([999.0]), // Extra channel
+          });
+
+          const result = nameAdapter.adapt(inputFrame);
+
+          // Should filter extraCh and convert remaining keys to names
+          expect(result.columns).toHaveLength(2);
+          expect(result.has(timeCh.name)).toBe(true);
+          expect(result.has(dataCh.name)).toBe(true);
+          expect(result.has(extraCh.key)).toBe(false);
+        });
+
+        it("should handle partial matches while converting", async () => {
+          const filterAdapter = await ReadAdapter.open(client.channels.retriever, [
+            timeCh.name,
+          ]);
+
+          const ts = TimeStamp.now().valueOf();
+          const inputFrame = new Frame({
+            [timeCh.key]: new Series([ts]),
+            [extraCh.key]: new Series([999.0]),
+          });
+
+          const result = filterAdapter.adapt(inputFrame);
+
+          expect(result.columns).toHaveLength(1);
+          expect(result.has(timeCh.name)).toBe(true);
+          expect(result.has(extraCh.key)).toBe(false);
+          expect(result.get(timeCh.name).at(0)).toEqual(ts);
+        });
+
+        it("should return empty frame when no channels match", async () => {
+          const filterAdapter = await ReadAdapter.open(client.channels.retriever, [
+            timeCh.name,
+          ]);
+
+          const inputFrame = new Frame({
+            [extraCh.key]: new Series([999.0]),
+          });
+
+          const result = filterAdapter.adapt(inputFrame);
+
+          expect(result.columns).toHaveLength(0);
+          expect(result.series).toHaveLength(0);
+        });
+      });
+    });
+
+    describe("edge cases", () => {
+      it("should handle empty frames", () => {
+        const inputFrame = new Frame({});
+
+        const result = adapter.adapt(inputFrame);
+
+        expect(result.columns).toHaveLength(0);
+        expect(result.series).toHaveLength(0);
+      });
+
+      it("should handle frames with empty series", () => {
+        const inputFrame = new Frame({
+          [timeCh.key]: new Series({ data: [], dataType: DataType.TIMESTAMP }),
+          [dataCh.key]: new Series({ data: [], dataType: DataType.FLOAT32 }),
+        });
+
+        const result = adapter.adapt(inputFrame);
+
+        expect(result.columns).toHaveLength(2);
+        expect(result.get(timeCh.key)).toHaveLength(0);
+        expect(result.get(dataCh.key)).toHaveLength(0);
+      });
+    });
+
+    describe("data integrity", () => {
+      it("should preserve series values across multiple data types", async () => {
+        const int64Ch = await client.channels.create({
+          name: `read-int64-${Math.random()}-${TimeStamp.now().toString()}`,
+          dataType: DataType.INT64,
+          index: timeCh.key,
+        });
+
+        const testAdapter = await ReadAdapter.open(client.channels.retriever, [
+          timeCh.key,
+          dataCh.key,
+          int64Ch.key,
+        ]);
+
+        const ts = TimeStamp.now().valueOf();
+        const inputFrame = new Frame({
+          [timeCh.key]: new Series([ts, ts + 1000n]),
+          [dataCh.key]: new Series([1.5, 2.5]),
+          [int64Ch.key]: new Series([100n, 200n]),
+        });
+
+        const result = testAdapter.adapt(inputFrame);
+
+        // Verify all values preserved
+        expect(result.get(timeCh.key).at(0)).toEqual(ts);
+        expect(result.get(timeCh.key).at(1)).toEqual(ts + 1000n);
+        expect(result.get(dataCh.key).at(0)).toEqual(1.5);
+        expect(result.get(dataCh.key).at(1)).toEqual(2.5);
+        expect(result.get(int64Ch.key).at(0)).toEqual(100n);
+        expect(result.get(int64Ch.key).at(1)).toEqual(200n);
+      });
+
+      it("should preserve series lengths after filtering", () => {
+        const ts = TimeStamp.now().valueOf();
+        const inputFrame = new Frame({
+          [timeCh.key]: new Series([ts, ts + 1000n, ts + 2000n]),
+          [dataCh.key]: new Series([1.0, 2.0, 3.0]),
+          [extraCh.key]: new Series([999.0, 888.0, 777.0]),
+        });
+
+        const result = adapter.adapt(inputFrame);
+
+        // Lengths should be preserved for included channels
+        expect(result.get(timeCh.key)).toHaveLength(3);
+        expect(result.get(dataCh.key)).toHaveLength(3);
+      });
+
+      it("should preserve series order", () => {
+        const ts = TimeStamp.now().valueOf();
+        // Create frame with explicit column order
+        const inputFrame = new Frame(
+          [dataCh.key, timeCh.key],
+          [new Series([1.0, 2.0, 3.0]), new Series([ts, ts + 1000n, ts + 2000n])],
+        );
+
+        const result = adapter.adapt(inputFrame);
+
+        // Order should be preserved (dataCh first, then timeCh)
+        expect(result.columns[0]).toEqual(dataCh.key);
+        expect(result.columns[1]).toEqual(timeCh.key);
+      });
+    });
+
+    describe("state management", () => {
+      it("should handle multiple sequential updates correctly", async () => {
+        // Start with NAME mode to enable filtering
+        const newAdapter = await ReadAdapter.open(client.channels.retriever, [
+          timeCh.name,
+        ]);
+
+        // Initial state: only timeCh registered
+        const ts = TimeStamp.now().valueOf();
+        const inputFrame = new Frame({
+          [timeCh.key]: new Series([ts]),
+          [dataCh.key]: new Series([1.5]),
+        });
+
+        // Should filter out dataCh and convert timeCh key to name
+        let result = newAdapter.adapt(inputFrame);
+        expect(result.columns).toHaveLength(1);
+        expect(result.has(timeCh.name)).toBe(true);
+        expect(result.has(dataCh.name)).toBe(false);
+
+        // Update to include dataCh
+        await newAdapter.update([timeCh.name, dataCh.name]);
+
+        // Should now include both channels (converted to names)
+        result = newAdapter.adapt(inputFrame);
+        expect(result.columns).toHaveLength(2);
+        expect(result.has(timeCh.name)).toBe(true);
+        expect(result.has(dataCh.name)).toBe(true);
+      });
+    });
+
+    describe("codec integration", () => {
+      it("should update codec when channels change", async () => {
+        const codecAdapter = await ReadAdapter.open(client.channels.retriever, [
+          timeCh.key,
+        ]);
+        expect(codecAdapter.keys).toHaveLength(1);
+        await codecAdapter.update([timeCh.key, dataCh.key]);
+        expect(codecAdapter.keys).toHaveLength(2);
+      });
+    });
+  });
+
   describe("update", () => {
     it("should return false when updating with the same channels", async () => {
       const hasChanged = await adapter.update([timeCh.key, dataCh.key]);

package/src/framer/adapter.ts

@@ -17,13 +17,13 @@ import { type CrudeFrame, Frame } from "@/framer/frame";
 export class ReadAdapter {
   private adapter: Map<channel.Key, channel.Name> | null;
   retriever: channel.Retriever;
-  keys: channel.Key[];
+  keys: Set<channel.Key>;
   codec: Codec;
 
   private constructor(retriever: channel.Retriever) {
     this.retriever = retriever;
     this.adapter = null;
-    this.keys = [];
+    this.keys = new Set();
     this.codec = new Codec();
   }
 
@@ -40,7 +40,10 @@ export class ReadAdapter {
     const { variant, normalized } = channel.analyzeParams(channels);
     const fetched = await this.retriever.retrieve(normalized);
     const newKeys = fetched.map((c) => c.key);
-    if (compare.uniqueUnorderedPrimitiveArrays(this.keys, newKeys) === compare.EQUAL)
+    if (
+      compare.uniqueUnorderedPrimitiveArrays(Array.from(this.keys), newKeys) ===
+      compare.EQUAL
+    )
       return false;
     this.codec.update(
       newKeys,
@@ -48,7 +51,7 @@ export class ReadAdapter {
     );
     if (variant === "keys") {
       this.adapter = null;
-      this.keys = normalized as channel.Key[];
+      this.keys = new Set(normalized as channel.Key[]);
       return true;
     }
     const a = new Map<channel.Key, channel.Name>();
@@ -58,20 +61,27 @@ export class ReadAdapter {
       if (channel == null) throw new Error(`Channel ${name} not found`);
       a.set(channel.key, channel.name);
     });
-    this.keys = Array.from(this.adapter.keys());
+    this.keys = new Set(this.adapter.keys());
     return true;
   }
 
-  adapt(columnsOrData: Frame): Frame {
-    if (this.adapter == null) return columnsOrData;
+  adapt(frm: Frame): Frame {
+    if (this.adapter == null) {
+      let shouldFilter = false;
+      frm.forEach((k) => {
+        if (!this.keys.has(k as channel.Key)) shouldFilter = true;
+      });
+      if (shouldFilter) return frm.filter((k) => this.keys.has(k as channel.Key));
+      return frm;
+    }
     const a = this.adapter;
-    return columnsOrData.map((k, arr) => {
-      if (typeof k === "number") {
-        const name = a.get(k);
-        if (name == null) throw new Error(`Channel ${k} not found`);
-        return [name, arr];
+    return frm.mapFilter((col, arr) => {
+      if (typeof col === "number") {
+        const name = a.get(col);
+        if (name == null) return [col, arr, false];
+        return [name, arr, true];
       }
-      return [k, arr];
+      return [col, arr, true];
     });
   }
 }