@synnaxlabs/client 0.46.1 → 0.48.0

package/src/connection/connection.spec.ts

@@ -7,24 +7,24 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { URL } from "@synnaxlabs/x/url";
+import { URL } from "@synnaxlabs/x";
 import { describe, expect, it } from "vitest";
 import { z } from "zod";
 
 import { auth } from "@/auth";
 import { connection } from "@/connection";
-import { TEST_CLIENT_PROPS } from "@/testutil/client";
+import { TEST_CLIENT_PARAMS } from "@/testutil/client";
 import { Transport } from "@/transport";
 
 describe("connectivity", () => {
   it("should connect to the server", async () => {
     const transport = new Transport(
       new URL({
-        host: TEST_CLIENT_PROPS.host,
-        port: Number(TEST_CLIENT_PROPS.port),
+        host: TEST_CLIENT_PARAMS.host,
+        port: Number(TEST_CLIENT_PARAMS.port),
       }),
     );
-    const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+    const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
     transport.use(client.middleware());
     const connectivity = new connection.Checker(
       transport.unary,
@@ -39,11 +39,11 @@ describe("connectivity", () => {
     it("should pull the server and client versions", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -57,11 +57,11 @@ describe("connectivity", () => {
     it("should adjust state if the server is too old", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(
         transport.unary,
@@ -75,11 +75,11 @@ describe("connectivity", () => {
     it("should adjust state if the server is too new", async () => {
       const transport = new Transport(
         new URL({
-          host: TEST_CLIENT_PROPS.host,
-          port: Number(TEST_CLIENT_PROPS.port),
+          host: TEST_CLIENT_PARAMS.host,
+          port: Number(TEST_CLIENT_PARAMS.port),
         }),
       );
-      const client = new auth.Client(transport.unary, TEST_CLIENT_PROPS);
+      const client = new auth.Client(transport.unary, TEST_CLIENT_PARAMS);
       transport.use(client.middleware());
       const connectivity = new connection.Checker(transport.unary, undefined, "0.0.0");
       const state = await connectivity.check();

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/control/state.ts

@@ -7,9 +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 { control } from "@synnaxlabs/x";
-import { binary } from "@synnaxlabs/x/binary";
-import { type observe } from "@synnaxlabs/x/observe";
+import { binary, control, type observe } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { type channel } from "@/channel";

package/src/errors.ts

@@ -92,7 +92,7 @@ export class ControlError extends SynnaxError.sub("control") {}
 export class UnauthorizedError extends ControlError.sub("unauthorized") {}
 
 export class DisconnectedError extends SynnaxError.sub("disconnected") {
-  constructor(message: string = "Operation failed because no cluster is connected.") {
+  constructor(message: string = "Operation failed because no Core is connected.") {
     super(message);
   }
 }
@@ -161,7 +161,7 @@ export const errorsMiddleware: Middleware = async (ctx, next) => {
     return [
       res,
       new Unreachable({
-        message: `Cannot reach cluster at ${err.url.host}:${err.url.port}`,
+        message: `Cannot reach Core at ${err.url.host}:${err.url.port}`,
         url: err.url,
       }),
     ];

package/src/framer/adapter.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, Series, TimeStamp } from "@synnaxlabs/x/telem";
+import { DataType, Series, TimeStamp } from "@synnaxlabs/x";
 import { beforeAll, describe, expect, it } from "vitest";
 
 import { type channel } from "@/channel";
@@ -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]);