@synnaxlabs/x 0.14.1 → 0.15.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@synnaxlabs/x",
   "private": false,
-  "version": "0.14.1",
+  "version": "0.15.0",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/go",
@@ -27,9 +27,9 @@
     "eslint": "^8.55.0",
     "vite": "^5.1.2",
     "vitest": "^1.2.2",
+    "@synnaxlabs/vite-plugin": "0.0.1",
     "eslint-config-synnaxlabs": "0.0.1",
-    "@synnaxlabs/tsconfig": "0.0.2",
-    "@synnaxlabs/vite-plugin": "0.0.1"
+    "@synnaxlabs/tsconfig": "0.0.2"
   },
   "main": "dist/x.cjs",
   "module": "dist/x.js",

package/src/telem/generate.ts

@@ -7,9 +7,9 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { DataType, DataTypeT, NativeTypedArray } from "@/telem/telem";
+import { DataType, type DataTypeT, type TypedArray } from "@/telem/telem";
 
-export const randomSeries = (length: number, dataType: DataTypeT): NativeTypedArray => {
+export const randomSeries = (length: number, dataType: DataTypeT): TypedArray => {
   // generate random bytes of the correct length
   const bytes = new Uint8Array(length * new DataType(dataType).density.valueOf());
   for (let i = 0; i < bytes.byteLength; i++) {

package/src/telem/series.spec.ts

@@ -11,13 +11,37 @@ import { describe, expect, test, it } from "vitest";
 import { z } from "zod";
 
 import { MockGLBufferController } from "@/mock/MockGLBufferController";
-import { Series } from "@/telem/series";
-import { DataType, Rate, Size, TimeRange, TimeStamp } from "@/telem/telem";
+import { Series, isCrudeSeries, MultiSeries } from "@/telem/series";
+import { DataType, Rate, Size, TimeRange, TimeSpan, TimeStamp } from "@/telem/telem";
 
 describe("Series", () => {
   describe("construction", () => {
-    test("valid from native", () => {
-      const a = new Series({ data: new Float32Array([1, 2, 3]) });
+    const IS_CRUDE_SERIES_SPEC: Array<[unknown, boolean]> = [
+      [{}, false],
+      [{ constructor: {} }, false],
+      [1, true],
+      [[1, 2, 3], true],
+      [["a", "b", "c"], true],
+      [new Float32Array([12]), true],
+    ];
+    IS_CRUDE_SERIES_SPEC.forEach(([value, expected]) => {
+      it(`should return ${expected} for ${JSON.stringify(value)}`, () => {
+        expect(isCrudeSeries(value)).toEqual(expected);
+      });
+    });
+
+    test("from another series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        timeRange: new TimeRange(TimeStamp.seconds(5), TimeStamp.seconds(20)),
+      });
+      const b = new Series(a);
+      expect(b.buffer).toBe(a.buffer);
+      expect(b.timeRange).toBe(a.timeRange);
+    });
+
+    test("valid from typed array", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
       expect(a.dataType.toString()).toBe(DataType.FLOAT32.toString());
       expect(a.length).toEqual(3);
       expect(a.byteLength).toEqual(Size.bytes(12));
@@ -39,6 +63,74 @@ describe("Series", () => {
       }).toThrow();
     });
 
+    test("valid from js array", () => {
+      const a = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      expect(a.dataType.toString()).toBe(DataType.FLOAT32.toString());
+      expect(a.length).toEqual(3);
+      expect(a.byteLength).toEqual(Size.bytes(12));
+      expect(a.byteCapacity).toEqual(Size.bytes(12));
+      expect(a.capacity).toEqual(3);
+    });
+
+    it("should assume float64 when JS numbers are passed as data", () => {
+      const s = new Series({ data: [1, 2, 3] });
+      expect(s.dataType.equals(DataType.FLOAT64));
+    });
+
+    it("should assume float64 when a single number is passed in", () => {
+      const s = new Series(1);
+      expect(s.dataType.equals(DataType.FLOAT64)).toBeTruthy();
+    });
+
+    it("should assume string when JS strings are passed as data", () => {
+      const s = new Series({ data: ["apple", "banana", "carrot"] });
+      expect(s.dataType.equals(DataType.STRING));
+      expect(s.length).toEqual(3);
+    });
+
+    it("should assume string when a single string is passed as data", () => {
+      const s = new Series("abc");
+      expect(s.dataType.equals(DataType.STRING)).toBeTruthy();
+      expect(s.length).toEqual(1);
+    });
+
+    it("should assume JSON when JS objects are passed as data", () => {
+      const s = new Series({ data: [{ a: 1, b: "apple" }] });
+      expect(s.dataType.equals(DataType.JSON));
+      expect(s.length).toEqual(1);
+    });
+
+    it("should correctly interpret a bigint as an int64", () => {
+      const s = new Series(1n);
+      expect(s.dataType.equals(DataType.INT64)).toBeTruthy();
+      expect(s.length).toEqual(1);
+    });
+
+    it("should correctly interpret a TimeStamp object as a data type of timestamp", () => {
+      const s = new Series(TimeStamp.now());
+      expect(s.dataType).toEqual(DataType.TIMESTAMP);
+    });
+
+    it("should correctly interpret an array of TimeStamps as a data type of timestamp", () => {
+      const s = new Series([TimeStamp.now(), TimeStamp.now().add(TimeSpan.seconds(1))]);
+      expect(s.dataType).toEqual(DataType.TIMESTAMP);
+    });
+
+    it("should correctly interpret a Date object as a data type of timestamp", () => {
+      const s = new Series(new Date());
+      expect(s.dataType).toEqual(DataType.TIMESTAMP);
+    });
+
+    it("should encode objects as JSON", () => {
+      const a = new Series({ data: [{ a: 1, b: "apple" }], dataType: DataType.JSON });
+      expect(a.dataType.toString()).toBe(DataType.JSON.toString());
+    });
+
+    it("should correctly separate strings", () => {
+      const a = new Series({ data: ["apple"], dataType: DataType.STRING });
+      expect(a.dataType.toString()).toBe(DataType.STRING.toString());
+    });
+
     test("from buffer with data type provided", () => {
       const a = new Series({ data: new ArrayBuffer(4), dataType: DataType.FLOAT32 });
       expect(a.dataType.toString()).toBe(DataType.FLOAT32.toString());
@@ -103,6 +195,48 @@ describe("Series", () => {
         series.at(3, true);
       }).toThrow();
     });
+    it("should return the correct value for a string series", () => {
+      const series = new Series({
+        data: ["apple", "banana", "carrot"],
+        dataType: DataType.STRING,
+      });
+      expect(series.at(0)).toEqual("apple");
+      expect(series.at(1)).toEqual("banana");
+      expect(series.at(2)).toEqual("carrot");
+      expect(series.at(-1)).toEqual("carrot");
+    });
+    it("should return the correct value for a JSON series", () => {
+      const series = new Series({
+        data: [
+          { a: 1, b: "apple" },
+          { a: 2, b: "banana" },
+        ],
+        dataType: DataType.JSON,
+      });
+      expect(series.at(0)).toEqual({ a: 1, b: "apple" });
+      expect(series.at(1)).toEqual({ a: 2, b: "banana" });
+    });
+    it("should throw an error if the index is out of bounds for a string series", () => {
+      const series = new Series({
+        data: ["apple", "banana", "carrot"],
+        dataType: DataType.STRING,
+      });
+      expect(() => {
+        series.at(3, true);
+      }).toThrow();
+    });
+    it("should throw an error if the index is out of bounds for a JSON series", () => {
+      const series = new Series({
+        data: [
+          { a: 1, b: "apple" },
+          { a: 2, b: "banana" },
+        ],
+        dataType: DataType.JSON,
+      });
+      expect(() => {
+        series.at(2, true);
+      }).toThrow();
+    });
   });
 
   describe("slice", () => {
@@ -135,6 +269,11 @@ describe("Series", () => {
       expect(series.max).toEqual(3);
       expect(series.min).toEqual(1);
     });
+    it("should throw an error if that data type is not numeric", () => {
+      const series = new Series({ data: ["a", "b", "c"] });
+      expect(() => series.max == null).toThrow();
+      expect(() => series.min == null).toThrow();
+    });
   });
 
   describe("conversion", () => {
@@ -364,4 +503,109 @@ describe("Series", () => {
       expect(series.binarySearch(6)).toEqual(5);
     });
   });
+
+  describe("array construction", () => {
+    it("should correctly a JS array from a series", () => {
+      const s = new Series([1, 2, 3]);
+      const arr = Array.from(s);
+      expect(arr).toEqual([1, 2, 3]);
+    });
+    it("should correctly construct a js array from a string series", () => {
+      const s = new Series(["apple", "banana", "carrot"]);
+      const arr = Array.from(s);
+      expect(arr).toEqual(["apple", "banana", "carrot"]);
+    });
+    it("should correctly construct a JS array from a JSON series", () => {
+      const s = new Series([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+        { a: 3, b: "carrot" },
+      ]);
+      const arr = Array.from(s);
+      expect(arr).toEqual([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+        { a: 3, b: "carrot" },
+      ]);
+    });
+  });
+});
+
+describe("MultiSeries", () => {
+  describe("length", () => {
+    it("should correctly return the length of the multi-series", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      expect(multi.length).toEqual(6);
+    });
+  });
+  describe("at", () => {
+    it("should correctly return the value at a particular index", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      expect(multi.at(0)).toEqual(1);
+      expect(multi.at(1)).toEqual(2);
+      expect(multi.at(2)).toEqual(3);
+      expect(multi.at(3)).toEqual(4);
+      expect(multi.at(4)).toEqual(5);
+      expect(multi.at(5)).toEqual(6);
+    });
+    it("should correctly return a value via negative indexing", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      expect(multi.at(-1)).toEqual(6);
+      expect(multi.at(-2)).toEqual(5);
+      expect(multi.at(-3)).toEqual(4);
+      expect(multi.at(-4)).toEqual(3);
+      expect(multi.at(-5)).toEqual(2);
+      expect(multi.at(-6)).toEqual(1);
+    });
+  });
+
+  describe("array construction", () => {
+    it("should correctly construct a JS array from a multi-series", () => {
+      const a = new Series(new Float32Array([1, 2, 3]));
+      const b = new Series(new Float32Array([4, 5, 6]));
+      const multi = new MultiSeries([a, b]);
+      const arr = Array.from(multi);
+      expect(arr).toEqual([1, 2, 3, 4, 5, 6]);
+    });
+    it("should correctly construct a JS array from a multi-series of strings", () => {
+      const a = new Series(["apple", "banana", "carrot"]);
+      const b = new Series(["dog", "elephant", "fox"]);
+      const multi = new MultiSeries([a, b]);
+      const arr = Array.from(multi);
+      expect(arr).toEqual(["apple", "banana", "carrot", "dog", "elephant", "fox"]);
+    });
+    it("should correctly construct a JS array from a multi-series of JSON", () => {
+      const a = new Series([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+        { a: 3, b: "carrot" },
+      ]);
+      const b = new Series([
+        { a: 4, b: "dog" },
+        { a: 5, b: "elephant" },
+        { a: 6, b: "fox" },
+      ]);
+      const multi = new MultiSeries([a, b]);
+      const arr = Array.from(multi);
+      expect(arr).toEqual([
+        { a: 1, b: "apple" },
+        { a: 2, b: "banana" },
+        { a: 3, b: "carrot" },
+        { a: 4, b: "dog" },
+        { a: 5, b: "elephant" },
+        { a: 6, b: "fox" },
+      ]);
+    });
+    it("should correctly construct a JS array from a multi-series with no series", () => {
+      const multi = new MultiSeries([]);
+      const arr = Array.from(multi);
+      expect(arr).toEqual([]);
+    });
+  });
 });