@synnaxlabs/x 0.11.0 → 0.12.0

package/package.json

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

package/src/deep/memo.ts

@@ -1,3 +1,12 @@
+// Copyright 2024 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 { equal } from "@/deep/equal"
 
 
@@ -12,4 +21,4 @@ export const memo = <F extends (...args: any[]) => any>(func: F): F => {
         return result
     })
     return v as F;
-}
+}

package/src/shallowCopy.ts

@@ -1,6 +1,15 @@
 
+// Copyright 2024 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.
+
 export const shallowCopy = <T extends unknown>(obj: T): T => {
     if (Array.isArray(obj)) return [...obj] as T;
     if (typeof obj === "object" && obj !== null) return { ...obj } as T;
     return obj;
-}
+}

package/src/telem/series.spec.ts

@@ -21,8 +21,8 @@ describe("Series", () => {
       expect(a.dataType.toString()).toBe(DataType.FLOAT32.toString());
       expect(a.length).toEqual(3);
       expect(a.byteLength).toEqual(Size.bytes(12));
-      expect(a.byteCap).toEqual(Size.bytes(12));
-      expect(a.cap).toEqual(3);
+      expect(a.byteCapacity).toEqual(Size.bytes(12));
+      expect(a.capacity).toEqual(3);
       const b = new Series({ data: new BigInt64Array([BigInt(1)]) });
       expect(b.dataType.toString()).toBe(DataType.INT64.toString());
       const c = new Series({
@@ -55,15 +55,15 @@ describe("Series", () => {
 
     describe("allocation", () => {
       it("should allocate a lazy array", () => {
-        const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
-        expect(series.byteCap).toEqual(Size.bytes(40));
-        expect(series.cap).toEqual(10);
+        const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+        expect(series.byteCapacity).toEqual(Size.bytes(40));
+        expect(series.capacity).toEqual(10);
         expect(series.length).toEqual(0);
         expect(series.byteLength).toEqual(Size.bytes(0));
       });
       it("should throw an error when attempting to allocate an array of lenght 0", () => {
         expect(() => {
-          Series.alloc({ length: 0, dataType: DataType.FLOAT32 });
+          Series.alloc({ capacity: 0, dataType: DataType.FLOAT32 });
         }).toThrow();
       });
     });
@@ -87,8 +87,26 @@ describe("Series", () => {
       });
       expect(series.at(3)).toBeUndefined();
     });
+    it("should allow the index to be negative", () => {
+      const series = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.at(-1)).toEqual(3);
+    });
+    it("should throw an error when the index is out of bounds and require is set to true", () => {
+      const series = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(() => {
+        series.at(3, true);
+      }).toThrow();
+    });
   });
 
+
+
   describe("slice", () => {
     it("should slice a lazy array", () => {
       const a = new Series({
@@ -100,14 +118,14 @@ describe("Series", () => {
       expect(b.data).toEqual(new Float32Array([2]));
       expect(b.length).toEqual(1);
       expect(b.byteLength).toEqual(Size.bytes(4));
-      expect(b.byteCap).toEqual(Size.bytes(4));
-      expect(b.cap).toEqual(1);
+      expect(b.byteCapacity).toEqual(Size.bytes(4));
+      expect(b.capacity).toEqual(1);
     });
   });
 
   describe("min and max", () => {
     it("should return a min and max of zero on an allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       expect(series.max).toEqual(-Infinity);
       expect(series.min).toEqual(Infinity);
     });
@@ -154,8 +172,8 @@ describe("Series", () => {
 
   describe("writing", () => {
     it("should correctly write to an allocated lazy array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
-      expect(series.byteCap).toEqual(Size.bytes(40));
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+      expect(series.byteCapacity).toEqual(Size.bytes(40));
       expect(series.length).toEqual(0);
       const writeOne = new Series({ data: new Float32Array([1]) });
       expect(series.write(writeOne)).toEqual(1);
@@ -165,7 +183,7 @@ describe("Series", () => {
       expect(series.length).toEqual(3);
     });
     it("should recompute cached max and min correctly", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       series.enrich();
       const writeTwo = new Series({ data: new Float32Array([2, 3]) });
       series.write(writeTwo);
@@ -174,7 +192,7 @@ describe("Series", () => {
     });
     it("should correctly adjust the sample offset of a written array", () => {
       const series = Series.alloc({
-        length: 2,
+        capacity: 2,
         dataType: DataType.FLOAT32,
         timeRange: TimeRange.ZERO,
         sampleOffset: -3,
@@ -200,7 +218,7 @@ describe("Series", () => {
       expect(ts.timeRange).toEqual(
         new TimeRange(TimeStamp.seconds(1), TimeStamp.seconds(6)),
       );
-      expect(ts.cap).toEqual(5);
+      expect(ts.capacity).toEqual(5);
       expect(ts.length).toEqual(5);
       expect(ts.dataType.toString()).toEqual(DataType.TIMESTAMP.toString());
       expect(ts.data).toEqual(
@@ -233,7 +251,7 @@ describe("Series", () => {
       expect(buf).toEqual(new Float32Array([1, 2, 3]));
     });
     it("should correctly update a buffer when writing to an allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       const controller = new MockGLBufferController();
       series.updateGLBuffer(controller);
       expect(controller.createBufferMock).toHaveBeenCalledTimes(1);
@@ -249,7 +267,7 @@ describe("Series", () => {
       expect(controller.bufferDataMock).toHaveBeenCalledTimes(1);
       expect(controller.bufferSubDataMock).toHaveBeenCalledTimes(1);
       buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
       expect(new Float32Array(buf)[0]).toEqual(1);
       const writeTwo = new Series({ data: new Float32Array([2, 3]) });
       series.write(writeTwo);
@@ -257,7 +275,7 @@ describe("Series", () => {
       expect(controller.bufferDataMock).not.toHaveBeenCalledTimes(2);
       expect(controller.bufferSubDataMock).toHaveBeenCalledTimes(2);
       buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
       expect(new Float32Array(buf)[0]).toEqual(1);
       expect(new Float32Array(buf)[1]).toEqual(2);
       expect(new Float32Array(buf)[2]).toEqual(3);
@@ -286,7 +304,7 @@ describe("Series", () => {
       series.acquire(controller);
       expect(controller.createBufferMock).toHaveBeenCalledTimes(2);
       const buf = controller.buffers[series.glBuffer as number];
-      expect(buf.byteLength).toEqual(series.byteCap.valueOf());
+      expect(buf.byteLength).toEqual(series.byteCapacity.valueOf());
     });
   });
 
@@ -341,7 +359,7 @@ describe("Series", () => {
 
   describe("binarySearch", () => {
     it("should correctly binary search a pre-allocated array", () => {
-      const series = Series.alloc({ length: 10, dataType: DataType.FLOAT32 });
+      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       const writeOne = new Series({ data: new Float32Array([1, 2, 3, 4, 5]) });
       series.write(writeOne);
       expect(series.binarySearch(3)).toEqual(2);

package/src/telem/series.ts

@@ -62,7 +62,7 @@ export interface SeriesProps extends BaseSeriesProps {
 }
 
 export interface SeriesAllocProps extends BaseSeriesProps {
-  length: number;
+  capacity: number;
   dataType: CrudeDataType;
 }
 
@@ -106,7 +106,7 @@ export class Series {
   /** Tracks the number of entities currently using this array. */
   private _refCount: number = 0;
 
-  static alloc({ length, dataType, ...props }: SeriesAllocProps): Series {
+  static alloc({ capacity: length, dataType, ...props }: SeriesAllocProps): Series {
     if (length === 0)
       throw new Error("[Series] - cannot allocate an array of length 0");
     const data = new new DataType(dataType).Array(length);
@@ -188,13 +188,21 @@ export class Series {
       throw new Error("cannot release an array with a negative reference count");
   }
 
+  /**
+   * Writes the given series to this series. If the series being written exceeds the 
+   * remaining of series being written to, only the portion that fits will be written. 
+   * @param other the series to write to this series. The data type of the series written
+   * must be the same as the data type of the series being written to.
+   * @returns the number of samples written. If the entire series fits, this value is
+   * equal to the length of the series being written.
+   */
   write(other: Series): number {
     if (!other.dataType.equals(this.dataType))
       throw new Error("buffer must be of the same type as this array");
 
     // We've filled the entire underlying buffer
     if (this.writePos === FULL_BUFFER) return 0;
-    const available = this.cap - this.writePos;
+    const available = this.capacity - this.writePos;
 
     const toWrite = available < other.length ? other.slice(0, available) : other;
     this.underlyingData.set(toWrite.data as any, this.writePos);
@@ -256,19 +264,19 @@ export class Series {
     return this._timeRange!;
   }
 
-  /** @returns the capacity of the underlying buffer in bytes. */
-  get byteCap(): Size {
+  /** @returns the capacity of the series in bytes. */
+  get byteCapacity(): Size {
     return new Size(this.buffer.byteLength);
   }
 
-  /** @returns the capacity of the underlying buffer in samples. */
-  get cap(): number {
-    return this.dataType.density.length(this.byteCap);
+  /** @returns the capacity of the series in samples. */
+  get capacity(): number {
+    return this.dataType.density.length(this.byteCapacity);
   }
 
-  /** @returns the length of the underlying buffer in samples. */
+  /** @returns the length of the series in bytes. */
   get byteLength(): Size {
-    if (this.writePos === FULL_BUFFER) return this.byteCap;
+    if (this.writePos === FULL_BUFFER) return this.byteCapacity;
     return this.dataType.density.size(this.writePos);
   }
 
@@ -371,9 +379,17 @@ export class Series {
     return addSamples(this.max, -this.min);
   }
 
-  at(index: number): SampleValue {
+  at(index: number, required: true): SampleValue;
+
+  at(index: number, required?: false): SampleValue | undefined;
+
+  at(index: number, required?: boolean): SampleValue | undefined {
+    if (index < 0) index = this.length + index;
     const v = this.data[index];
-    if (v == null) return undefined as any;
+    if (v == null) {
+      if (required) throw new Error(`[series] - no value at index ${index}`);
+      return undefined;
+    }
     return addSamples(v, this.sampleOffset);
   }
 
@@ -388,7 +404,7 @@ export class Series {
     const cf = compare.newF(value);
     while (left <= right) {
       const mid = Math.floor((left + right) / 2);
-      const cmp = cf(this.at(mid), value);
+      const cmp = cf(this.at(mid, true), value);
       if (cmp === 0) return mid;
       if (cmp < 0) left = mid + 1;
       else right = mid - 1;
@@ -414,7 +430,7 @@ export class Series {
     // This means we only need to buffer part of the array.
     if (this.writePos !== FULL_BUFFER) {
       if (prevBuffer === 0) {
-        gl.bufferData(gl.ARRAY_BUFFER, this.byteCap.valueOf(), gl.STATIC_DRAW);
+        gl.bufferData(gl.ARRAY_BUFFER, this.byteCapacity.valueOf(), gl.STATIC_DRAW);
       }
       const byteOffset = this.dataType.density.size(prevBuffer).valueOf();
       const slice = this.underlyingData.slice(this.gl.prevBuffer, this.writePos);