@synnaxlabs/x 0.41.0 → 0.42.1

package/src/binary/codec.spec.ts

@@ -0,0 +1,370 @@
+// 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 { binary } from "@/binary";
+import { JSON_CODEC, MSGPACK_CODEC } from "@/binary/codec";
+
+const sampleSchema = z.object({
+  channelKey: z.string(),
+  timeStamp: z.number(),
+  value: z.unknown(),
+});
+
+[JSON_CODEC, MSGPACK_CODEC].forEach((codec) => {
+  describe(`encoder ${codec.contentType}`, () => {
+    it("should correctly encode and decode items", () => {
+      const sample = {
+        channelKey: "test",
+        timeStamp: 123,
+        value: [1, 2, 3],
+      };
+      const encoded = codec.encode(sample);
+      expect(codec.decode(encoded, sampleSchema)).toEqual(sample);
+    });
+  });
+});
+
+describe("JSON", () => {
+  it("should correctly convert keys to snake case", () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      value: new Array([1, 2, 3]),
+    };
+    const encoded = binary.JSON_CODEC.encodeString(sample);
+    const parse = JSON.parse(encoded);
+    expect(parse.channel_key).toEqual("test");
+  });
+  it("should correctly decode keys from snake case", () => {
+    const sample = {
+      channel_key: "test",
+      time_stamp: 123,
+      value: new Array([1, 2, 3]),
+    };
+    const encoded = JSON.stringify(sample);
+    const decoded = binary.JSON_CODEC.decodeString(encoded, sampleSchema);
+    expect(decoded.channelKey).toEqual("test");
+  });
+});
+
+describe("CSV", () => {
+  it("should correctly decode CSV data with valid input", () => {
+    const sample = `
+      channelKey,timeStamp,value
+      test,123,5
+      test2,124,6
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      channelKey: ["test", "test2"],
+      timeStamp: [123, 124],
+      value: [5, 6],
+    });
+  });
+
+  it("should handle empty CSV data", () => {
+    const sample = `
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({});
+  });
+
+  it("should handle CSV with only headers", () => {
+    const sample = `
+      channelKey,timeStamp,value
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      channelKey: [],
+      timeStamp: [],
+      value: [],
+    });
+  });
+
+  it("should handle CSV with missing values", () => {
+    const sample = `
+      channelKey,timeStamp,value
+      test,123,
+      test2,124,6
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      channelKey: ["test", "test2"],
+      timeStamp: [123, 124],
+      value: [6],
+    });
+  });
+
+  it("should handle CSV with extra values", () => {
+    const sample = `
+      channelKey,timeStamp,value
+      test,123,5,extra
+      test2,124,6
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      channelKey: ["test", "test2"],
+      timeStamp: [123, 124],
+      value: [5, 6],
+    });
+  });
+
+  it("should handle CSV with different types of values", () => {
+    const sample = `
+      key,number,string
+      test,123,"hello"
+      test2,456,"world"
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      key: ["test", "test2"],
+      number: [123, 456],
+      string: ["hello", "world"],
+    });
+  });
+
+  it("should handle CSV with spaces around values", () => {
+    const sample = `
+      key, number , string
+      test , 123 , "hello"
+      test2 , 456 , "world"
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      key: ["test", "test2"],
+      number: [123, 456],
+      string: ["hello", "world"],
+    });
+  });
+
+  it("should handle CSV with empty rows", () => {
+    const sample = `
+      key,number,string
+      test,123,"hello"
+      ,
+      test2,456,"world"
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      key: ["test", "test2"],
+      number: [123, 456],
+      string: ["hello", "world"],
+    });
+  });
+
+  it("should handle CSV with single column", () => {
+    const sample = `
+      key
+      test
+      test2
+      `;
+    const decoded = binary.CSV_CODEC.decodeString(sample);
+    expect(decoded).toEqual({
+      key: ["test", "test2"],
+    });
+  });
+
+  it("should correctly encode array of objects to CSV", () => {
+    const sampleData = [
+      { name: "John", age: 30, city: "New York" },
+      { name: "Alice", age: 25, city: "Boston" },
+      { name: "Bob", age: 40, city: "Chicago" },
+    ];
+
+    const encoded = binary.CSV_CODEC.encodeString(sampleData);
+    expect(encoded).toBe(
+      'name,age,city\n"John",30,"New York"\n"Alice",25,"Boston"\n"Bob",40,"Chicago"',
+    );
+  });
+
+  it("should handle objects with missing values", () => {
+    const sampleData = [
+      { name: "John", age: 30, city: "New York" },
+      { name: "Alice", age: 25 },
+      { name: "Bob", city: "Chicago" },
+    ];
+
+    const encoded = binary.CSV_CODEC.encodeString(sampleData);
+    expect(encoded).toBe(
+      'name,age,city\n"John",30,"New York"\n"Alice",25,""\n"Bob","","Chicago"',
+    );
+  });
+
+  it("should handle objects with null and undefined values", () => {
+    const sampleData = [
+      { name: "John", age: null, city: undefined },
+      { name: "Alice", age: 25, city: null },
+    ];
+
+    const encoded = binary.CSV_CODEC.encodeString(sampleData);
+    expect(encoded).toBe('name,age,city\n"John","",""\n"Alice",25,""');
+  });
+
+  it("should handle different data types in objects", () => {
+    const sampleData = [
+      { name: "John", active: true, score: 98.5 },
+      { name: "Alice", active: false, score: 92.3 },
+    ];
+
+    const encoded = binary.CSV_CODEC.encodeString(sampleData);
+    expect(encoded).toBe('name,active,score\n"John",true,98.5\n"Alice",false,92.3');
+  });
+
+  it("should throw error when encoding empty array", () => {
+    const sampleData: any[] = [];
+
+    expect(() => {
+      binary.CSV_CODEC.encodeString(sampleData);
+    }).toThrow("Payload must be an array of objects");
+  });
+
+  it("should throw error when encoding non-array data", () => {
+    const sampleData = { name: "John", age: 30 };
+
+    expect(() => {
+      binary.CSV_CODEC.encodeString(sampleData);
+    }).toThrow("Payload must be an array of objects");
+  });
+
+  it("should round-trip encode and decode CSV data", () => {
+    const sampleData = [
+      { name: "John", age: 30, city: "New York" },
+      { name: "Alice", age: 25, city: "Boston" },
+    ];
+
+    const encoded = binary.CSV_CODEC.encode(sampleData);
+    const decoded = binary.CSV_CODEC.decode(encoded);
+
+    expect(decoded).toEqual({
+      name: ["John", "Alice"],
+      age: [30, 25],
+      city: ["New York", "Boston"],
+    });
+  });
+});
+
+describe("MsgPack", () => {
+  it("should correctly convert keys to snake case", () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      value: [1, 2, 3],
+    };
+    const encoded = binary.MSGPACK_CODEC.encode(sample);
+    const decoded = binary.MSGPACK_CODEC.decode(encoded);
+    expect(decoded).toEqual(sample);
+  });
+
+  it("should correctly validate with schema", () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      value: [1, 2, 3],
+    };
+    const encoded = binary.MSGPACK_CODEC.encode(sample);
+    const decoded = binary.MSGPACK_CODEC.decode(encoded, sampleSchema);
+    expect(decoded).toEqual(sample);
+  });
+
+  it("should handle complex nested objects", () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      nestedObject: {
+        innerKey: "value",
+        numberArray: [1, 2, 3],
+        deepNesting: {
+          anotherKey: true,
+        },
+      },
+    };
+    const encoded = binary.MSGPACK_CODEC.encode(sample);
+    const decoded = binary.MSGPACK_CODEC.decode(encoded);
+    expect(decoded).toEqual(sample);
+  });
+
+  it("should handle binary data", () => {
+    const binaryData = new Uint8Array([1, 2, 3, 4, 5]);
+    const sample = {
+      channelKey: "binary-test",
+      timeStamp: 456,
+      value: binaryData,
+    };
+    const encoded = binary.MSGPACK_CODEC.encode(sample);
+    const decoded = binary.MSGPACK_CODEC.decode<typeof sampleSchema>(encoded);
+
+    // Check that the structure is preserved
+    expect(decoded.channelKey).toEqual(sample.channelKey);
+    expect(decoded.timeStamp).toEqual(sample.timeStamp);
+
+    // Verify that binary data is handled properly
+    // Note: The exact format might depend on msgpack implementation
+    expect(
+      Array.isArray(decoded.value) || ArrayBuffer.isView(decoded.value),
+    ).toBeTruthy();
+  });
+
+  class CustomValueEncoder {
+    readonly encodeValue = true;
+
+    value = "cat";
+  }
+
+  it("should correctly encode and decode custom value", () => {
+    const sample = {
+      channelKey: "test",
+      timeStamp: 123,
+      value: new CustomValueEncoder(),
+    };
+    const encoded = binary.MSGPACK_CODEC.encode(sample);
+    const decoded = binary.MSGPACK_CODEC.decode(encoded, sampleSchema);
+    expect(decoded).toEqual({ ...sample, value: "cat" });
+  });
+});
+
+describe("TextCodec", () => {
+  it("should correctly encode and decode text", () => {
+    const sampleText = "Hello, world!";
+    const encoded = binary.TEXT_CODEC.encode(sampleText);
+    const decoded = binary.TEXT_CODEC.decode(encoded);
+    expect(decoded).toEqual(sampleText);
+  });
+
+  it("should handle empty strings", () => {
+    const sampleText = "";
+    const encoded = binary.TEXT_CODEC.encode(sampleText);
+    const decoded = binary.TEXT_CODEC.decode(encoded);
+    expect(decoded).toEqual(sampleText);
+  });
+
+  it("should validate text with schema", () => {
+    const textSchema = z.string();
+    const sampleText = "Validation test";
+    const encoded = binary.TEXT_CODEC.encode(sampleText);
+    const decoded = binary.TEXT_CODEC.decode(encoded, textSchema);
+    expect(decoded).toEqual(sampleText);
+  });
+
+  it("should handle special characters", () => {
+    const sampleText = "Special characters: äöü!@#$%^&*()_+";
+    const encoded = binary.TEXT_CODEC.encode(sampleText);
+    const decoded = binary.TEXT_CODEC.decode(encoded);
+    expect(decoded).toEqual(sampleText);
+  });
+
+  it("should handle multi-line text", () => {
+    const sampleText = "Line 1\nLine 2\nLine 3";
+    const encoded = binary.TEXT_CODEC.encode(sampleText);
+    const decoded = binary.TEXT_CODEC.decode(encoded);
+    expect(decoded).toEqual(sampleText);
+  });
+});

package/src/binary/{encoder.ts → codec.ts}

@@ -7,7 +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 { type z, type ZodSchema } from "zod";
+import { decode, encode, ExtensionCodec } from "@msgpack/msgpack";
+import { type z } from "zod";
 
 import { caseconv } from "@/caseconv";
 import { isObject } from "@/identity";
@@ -26,7 +27,7 @@ export interface Codec {
    * @param payload - The payload to encode.
    * @returns An ArrayBuffer containing the encoded payload.
    */
-  encode: (payload: unknown) => ArrayBuffer;
+  encode: (payload: unknown) => Uint8Array;
 
   /**
    * Decodes the given binary representation into a type checked payload.
@@ -34,7 +35,10 @@ export interface Codec {
    * @param data - The data to decode.
    * @param schema - The schema to decode the data with.
    */
-  decode: <P>(data: Uint8Array | ArrayBuffer, schema?: ZodSchema<P>) => P;
+  decode: <P extends z.ZodTypeAny>(
+    data: Uint8Array | ArrayBuffer,
+    schema?: P,
+  ) => z.output<P>;
 }
 
 /** JSONCodec is a JSON implementation of Codec. */
@@ -48,8 +52,8 @@ export class JSONCodec implements Codec {
     this.encoder = new TextEncoder();
   }
 
-  encode(payload: unknown): ArrayBuffer {
-    return this.encoder.encode(this.encodeString(payload)).buffer as ArrayBuffer;
+  encode(payload: unknown): Uint8Array {
+    return this.encoder.encode(this.encodeString(payload));
   }
 
   decode<P extends z.ZodTypeAny>(
@@ -87,9 +91,9 @@ export class JSONCodec implements Codec {
 export class CSVCodec implements Codec {
   contentType = "text/csv";
 
-  encode(payload: unknown): ArrayBuffer {
+  encode(payload: unknown): Uint8Array {
     const csvString = this.encodeString(payload);
-    return new TextEncoder().encode(csvString).buffer as ArrayBuffer;
+    return new TextEncoder().encode(csvString);
   }
 
   decode<P extends z.ZodTypeAny>(
@@ -155,8 +159,8 @@ export class CSVCodec implements Codec {
 export class TextCodec implements Codec {
   contentType = "text/plain";
 
-  encode(payload: unknown): ArrayBuffer {
-    return new TextEncoder().encode(payload as string).buffer as ArrayBuffer;
+  encode(payload: unknown): Uint8Array {
+    return new TextEncoder().encode(payload as string);
   }
 
   decode<P extends z.ZodTypeAny>(
@@ -168,8 +172,48 @@ export class TextCodec implements Codec {
   }
 }
 
+const extensionCodec = new ExtensionCodec();
+
+extensionCodec.register({
+  type: 0,
+  encode: (value: unknown): Uint8Array | null => {
+    if (ArrayBuffer.isView(value)) {
+      const array = Array.from(value as Uint8Array);
+      return encode(array, { extensionCodec });
+    }
+    if (isObject(value) && "encode_value" in value) {
+      if (typeof value.value === "bigint")
+        return encode(value.value.toString(), { extensionCodec });
+      return encode(value.value, { extensionCodec });
+    }
+    if (typeof value === "bigint") return encode(value.toString(), { extensionCodec });
+    return null;
+  },
+  decode: (data: Uint8Array) => decode(data, { extensionCodec }),
+});
+
+export class MsgPackCodec implements Codec {
+  contentType = "application/msgpack";
+
+  encode(payload: unknown): Uint8Array {
+    const caseConverted = caseconv.camelToSnake(payload);
+    const d = encode(caseConverted, { extensionCodec });
+    return d.slice();
+  }
+
+  decode<P extends z.ZodTypeAny>(
+    data: Uint8Array | ArrayBuffer,
+    schema?: P,
+  ): z.output<P> {
+    const decoded = decode(data, { extensionCodec });
+    const unpacked = caseconv.snakeToCamel(decoded);
+    return schema != null ? schema.parse(unpacked) : (unpacked as z.output<P>);
+  }
+
+  static registerCustomType(): void {}
+}
+
 export const JSON_CODEC = new JSONCodec();
 export const CSV_CODEC = new CSVCodec();
 export const TEXT_CODEC = new TextCodec();
-
-export const ENCODERS: Codec[] = [JSON_CODEC];
+export const MSGPACK_CODEC = new MsgPackCodec();

package/src/binary/index.ts

@@ -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 binary from "@/binary/encoder";
+export * as binary from "@/binary/codec";

package/src/breaker/breaker.spec.ts

@@ -15,8 +15,8 @@ import { TimeSpan } from "@/telem";
 describe("breaker", () => {
   it("should allow first attempt without sleeping", async () => {
     const mockSleep = vi.fn();
-    const brk = breaker.create({ sleepFn: mockSleep });
-    const canRetry = await brk();
+    const brk = new breaker.Breaker({ sleepFn: mockSleep });
+    const canRetry = await brk.wait();
 
     expect(canRetry).toBe(true);
     expect(mockSleep).toHaveBeenCalled();
@@ -24,58 +24,49 @@ describe("breaker", () => {
 
   it("should retry specified number of times before failing", async () => {
     const mockSleep = vi.fn();
-    const brk = breaker.create({
+    const brk = new breaker.Breaker({
       maxRetries: 2,
-      interval: TimeSpan.milliseconds(1),
+      baseInterval: TimeSpan.milliseconds(1),
       sleepFn: mockSleep,
     });
 
     // First attempt
-    expect(await brk()).toBe(true);
+    expect(await brk.wait()).toBe(true);
     // Second attempt
-    expect(await brk()).toBe(true);
+    expect(await brk.wait()).toBe(true);
     // Third attempt (should fail)
-    expect(await brk()).toBe(false);
+    expect(await brk.wait()).toBe(false);
 
     expect(mockSleep).toHaveBeenCalledTimes(2);
   });
 
   it("should increase delay between retries according to scale", async () => {
     const mockSleep = vi.fn();
-    const brk = breaker.create({
-      interval: TimeSpan.seconds(1),
+    const brk = new breaker.Breaker({
+      baseInterval: TimeSpan.seconds(1),
       maxRetries: 3,
       scale: 2,
       sleepFn: mockSleep,
     });
 
-    await brk(); // First attempt - 1s
-    await brk(); // Second attempt - 1s * 2 = 2s;
-    await brk(); // Third attempt - 2s *2 = 4s;
+    await brk.wait(); // First attempt - 1s
+    await brk.wait(); // Second attempt - 1s * 2 = 2s;
+    await brk.wait(); // Third attempt - 2s *2 = 4s;
 
     expect(mockSleep).toHaveBeenNthCalledWith(1, TimeSpan.seconds(1));
     expect(mockSleep).toHaveBeenNthCalledWith(2, TimeSpan.seconds(2));
     expect(mockSleep).toHaveBeenNthCalledWith(3, TimeSpan.seconds(4));
   });
 
-  it("should use default values when no options provided", async () => {
-    const brk = breaker.create();
-    let attempts = 0;
-
-    while (await brk()) attempts++;
-
-    expect(attempts).toBe(5); // Default maxRetries is 5
-  });
-
   it("should use custom sleep function when provided", async () => {
     const customSleep = vi.fn();
-    const brk = breaker.create({
-      interval: TimeSpan.milliseconds(100),
+    const brk = new breaker.Breaker({
+      baseInterval: TimeSpan.milliseconds(100),
       sleepFn: customSleep,
     });
 
-    await brk();
-    await brk();
+    await brk.wait();
+    await brk.wait();
 
     expect(customSleep).toHaveBeenCalledTimes(2);
   });

package/src/breaker/breaker.ts

@@ -12,31 +12,48 @@ import { z } from "zod";
 import { sleep } from "@/sleep";
 import { type CrudeTimeSpan, TimeSpan } from "@/telem";
 
+export class Breaker {
+  private readonly config: Omit<Required<Config>, "baseInterval"> & {
+    baseInterval: TimeSpan;
+  };
+  private retries: number;
+  private interval: TimeSpan;
+
+  constructor(cfg?: Config) {
+    this.config = {
+      baseInterval: new TimeSpan(cfg?.baseInterval ?? TimeSpan.seconds(1)),
+      maxRetries: cfg?.maxRetries ?? 5,
+      scale: cfg?.scale ?? 1,
+      sleepFn: cfg?.sleepFn ?? sleep.sleep,
+    };
+    this.retries = 0;
+    this.interval = new TimeSpan(this.config.baseInterval);
+  }
+
+  async wait(): Promise<boolean> {
+    const { maxRetries, scale, sleepFn } = this.config;
+    if (this.retries >= maxRetries) return false;
+    await sleepFn(this.interval);
+    this.interval = this.interval.mult(scale);
+    this.retries++;
+    return true;
+  }
+
+  reset() {
+    this.retries = 0;
+    this.interval = this.config.baseInterval;
+  }
+}
+
 export const breakerConfig = z.object({
-  interval: TimeSpan.z.optional(),
+  baseInterval: TimeSpan.z.optional(),
   maxRetries: z.number().optional(),
   scale: z.number().optional(),
 });
 
-export interface Config extends Omit<z.infer<typeof breakerConfig>, "interval"> {
-  interval?: CrudeTimeSpan;
+export interface Config extends Omit<z.infer<typeof breakerConfig>, "baseInterval"> {
+  baseInterval?: CrudeTimeSpan;
   maxRetries?: number;
   scale?: number;
   sleepFn?: (duration: TimeSpan) => Promise<void>;
 }
-
-export const create = (options: Config = {}): (() => Promise<boolean>) => {
-  const sleepFn = options.sleepFn || sleep.sleep;
-  const maxRetries = options.maxRetries ?? 5;
-  const scale = options.scale ?? 1;
-  let retries = 0;
-  let interval = new TimeSpan(options.interval ?? TimeSpan.milliseconds(1));
-  return async () => {
-    // Change from arrow function to regular function to preserve 'this'
-    if (retries >= maxRetries) return false;
-    await sleepFn(interval);
-    interval = interval.mult(scale);
-    retries++;
-    return true;
-  };
-};