@synnaxlabs/x 0.8.0 → 0.10.0

package/src/telem/series.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 { date, type z } from "zod";
+import { nanoid } from "nanoid/non-secure";
+import { type z } from "zod";
 
 import { compare } from "@/compare";
 import { bounds } from "@/spatial";
@@ -39,20 +40,47 @@ interface GL {
 }
 
 export interface SeriesDigest {
+  key: string;
   dataType: string;
   sampleOffset: SampleValue;
-  alignment: number;
+  alignment: bounds.Bounds;
   timeRange?: string;
   length: number;
 }
 
+interface BaseSeriesProps {
+  dataType?: CrudeDataType;
+  timeRange?: TimeRange;
+  sampleOffset?: SampleValue;
+  glBufferUsage?: GLBufferUsage;
+  alignment?: number;
+  key?: string;
+}
+
+export interface SeriesProps extends BaseSeriesProps {
+  data: ArrayBuffer | NativeTypedArray;
+}
+
+export interface SeriesAllocProps extends BaseSeriesProps {
+  length: number;
+  dataType: CrudeDataType;
+}
+
 const FULL_BUFFER = -1;
 
+export interface SeriesMemInfo {
+  key: string;
+  length: number;
+  byteLength: Size;
+  glBuffer: boolean;
+}
+
 /**
  * Series is a strongly typed array of telemetry samples backed by an underlying binary
  * buffer.
  */
 export class Series {
+  key: string = "";
   /** The data type of the array */
   readonly dataType: DataType;
   /**
@@ -78,36 +106,26 @@ export class Series {
   /** Tracks the number of entities currently using this array. */
   private _refCount: number = 0;
 
-  static alloc(
-    length: number,
-    dataType: CrudeDataType,
-    timeRange?: TimeRange,
-    sampleOffset?: SampleValue,
-    glBufferUsage: GLBufferUsage = "static",
-    alignment: number = 0,
-  ): Series {
+  static alloc({ 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);
-    const arr = new Series(
-      data.buffer,
+    const arr = new Series({
+      data: data.buffer,
       dataType,
-      timeRange,
-      sampleOffset,
-      glBufferUsage,
-      alignment,
-    );
+      ...props,
+    });
     arr.writePos = 0;
     return arr;
   }
 
   static generateTimestamps(length: number, rate: Rate, start: TimeStamp): Series {
-    const tr = start.spanRange(rate.span(length));
+    const timeRange = start.spanRange(rate.span(length));
     const data = new BigInt64Array(length);
     for (let i = 0; i < length; i++) {
       data[i] = BigInt(start.add(rate.span(i)).valueOf());
     }
-    return new Series(data, DataType.TIMESTAMP, tr);
+    return new Series({ data, dataType: DataType.TIMESTAMP, timeRange });
   }
 
   get refCount(): number {
@@ -116,24 +134,25 @@ export class Series {
 
   static fromStrings(data: string[], timeRange?: TimeRange): Series {
     const buffer = new TextEncoder().encode(data.join("\n") + "\n");
-    return new Series(buffer, DataType.STRING, timeRange);
+    return new Series({ data: buffer, dataType: DataType.STRING, timeRange });
   }
 
   static fromJSON<T>(data: T[], timeRange?: TimeRange): Series {
     const buffer = new TextEncoder().encode(
       data.map((d) => JSON.stringify(d)).join("\n") + "\n",
     );
-    return new Series(buffer, DataType.JSON, timeRange);
-  }
-
-  constructor(
-    data: ArrayBuffer | NativeTypedArray,
-    dataType?: CrudeDataType,
-    timeRange?: TimeRange,
-    sampleOffset?: SampleValue,
-    glBufferUsage: GLBufferUsage = "static",
-    alignment: number = 0,
-  ) {
+    return new Series({ data: buffer, dataType: DataType.JSON, timeRange });
+  }
+
+  constructor({
+    data,
+    dataType,
+    timeRange,
+    sampleOffset = 0,
+    glBufferUsage = "static",
+    alignment = 0,
+    key = nanoid(),
+  }: SeriesProps) {
     if (dataType == null && !(data instanceof ArrayBuffer)) {
       this.dataType = new DataType(data);
     } else if (dataType != null) {
@@ -143,6 +162,7 @@ export class Series {
         "must provide a data type when constructing a Series from a buffer",
       );
     }
+    this.key = key;
     this.alignment = alignment;
     this.sampleOffset = sampleOffset ?? 0;
     this._data = data;
@@ -273,14 +293,14 @@ export class Series {
     for (let i = 0; i < this.length; i++) {
       data[i] = convertDataType(this.dataType, target, this.data[i], sampleOffset);
     }
-    return new Series(
-      data.buffer,
-      target,
-      this._timeRange,
+    return new Series({
+      data: data.buffer,
+      dataType: target,
+      timeRange: this._timeRange,
       sampleOffset,
-      this.gl.bufferUsage,
-      this.alignment,
-    );
+      glBufferUsage: this.gl.bufferUsage,
+      alignment: this.alignment,
+    });
   }
 
   private calcRawMax(): SampleValue {
@@ -383,7 +403,9 @@ export class Series {
     const { buffer, bufferUsage, prevBuffer } = this.gl;
 
     // If no buffer has been created yet, create one.
-    if (buffer == null) this.gl.buffer = gl.createBuffer();
+    if (buffer == null) {
+      this.gl.buffer = gl.createBuffer();
+    }
     // If the current write position is the same as the previous buffer, we're already
     // up date.
     if (this.writePos === prevBuffer) return;
@@ -413,14 +435,28 @@ export class Series {
 
   get digest(): SeriesDigest {
     return {
+      key: this.key,
       dataType: this.dataType.toString(),
       sampleOffset: this.sampleOffset,
-      alignment: this.alignment,
+      alignment: this.alignmentBounds,
       timeRange: this._timeRange?.toString(),
       length: this.length,
     };
   }
 
+  get memInfo(): SeriesMemInfo {
+    return {
+      key: this.key,
+      length: this.length,
+      byteLength: this.byteLength,
+      glBuffer: this.gl.buffer != null,
+    };
+  }
+
+  get alignmentBounds(): bounds.Bounds {
+    return bounds.construct(this.alignment, this.alignment + this.length);
+  }
+
   private maybeGarbageCollectGLBuffer(gl: GLBufferController): void {
     if (this.gl.buffer == null) return;
     gl.deleteBuffer(this.gl.buffer);
@@ -435,26 +471,27 @@ export class Series {
   }
 
   slice(start: number, end?: number): Series {
-    const d = this.data.slice(start, end);
-    return new Series(
-      d,
-      this.dataType,
-      TimeRange.ZERO,
-      this.sampleOffset,
-      this.gl.bufferUsage,
-      this.alignment + start,
-    );
+    if (start <= 0 && (end == null || end >= this.length)) return this;
+    const data = this.data.slice(start, end);
+    return new Series({
+      data,
+      dataType: this.dataType,
+      timeRange: this._timeRange,
+      sampleOffset: this.sampleOffset,
+      glBufferUsage: this.gl.bufferUsage,
+      alignment: this.alignment + start,
+    });
   }
 
   reAlign(alignment: number): Series {
-    return new Series(
-      this.buffer,
-      this.dataType,
-      TimeRange.ZERO,
-      this.sampleOffset,
-      "static",
+    return new Series({
+      data: this.buffer,
+      dataType: this.dataType,
+      timeRange: TimeRange.ZERO,
+      sampleOffset: this.sampleOffset,
+      glBufferUsage: "static",
       alignment,
-    );
+    });
   }
 }
 

package/src/telem/telem.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 { describe, expect, test } from "vitest";
+import { describe, expect, it, test } from "vitest";
 
 import { DataType, Density, Rate, Size, TimeRange, TimeSpan, TimeStamp } from "@/telem";
 
@@ -291,6 +291,22 @@ describe("TimeRange", () => {
     expect(tr.overlapsWith(two)).toBeFalsy();
     expect(two.overlapsWith(tr)).toBeFalsy();
   });
+  describe("boundBy", () => {
+    it("should bound the time range to the provided constraints", () => {
+      const tr = new TimeRange(TimeSpan.seconds(1), TimeSpan.seconds(4));
+      const bound = new TimeRange(TimeSpan.seconds(2), TimeSpan.seconds(3));
+      const bounded = tr.boundBy(bound);
+      const expected = new TimeRange(TimeSpan.seconds(2), TimeSpan.seconds(3));
+      expect(bounded.equals(expected)).toBeTruthy();
+    })
+    it("should bound the time range even if the start is after the end", () => {
+      const tr = new TimeRange(TimeSpan.seconds(4), TimeSpan.seconds(1));
+      const bound = new TimeRange(TimeSpan.seconds(2), TimeSpan.seconds(3));
+      const bounded = tr.boundBy(bound);
+      const expected = new TimeRange(TimeSpan.seconds(3), TimeSpan.seconds(2));
+      expect(bounded.equals(expected)).toBeTruthy();
+    })
+  });
 });
 
 describe("DataType", () => {

package/src/telem/telem.ts

@@ -898,6 +898,15 @@ export class TimeRange implements Stringer {
     return this.start.beforeEq(other) && this.end.after(other);
   }
 
+  boundBy(other: TimeRange): TimeRange {
+    const next = new TimeRange(this.start, this.end);
+    if (other.start.after(this.start)) next.start = other.start;
+    if (other.start.after(this.end)) next.end = other.start;
+    if (other.end.before(this.end)) next.end = other.end;
+    if (other.end.before(this.start)) next.start = other.end;
+    return next;
+  }
+
   /** The maximum possible time range. */
   static readonly MAX = new TimeRange(TimeStamp.MIN, TimeStamp.MAX);
 
@@ -1064,6 +1073,25 @@ export class DataType extends String implements Stringer {
     [DataType.UUID.toString(), Density.BIT128],
   ]);
 
+  /** All the data types. */
+  static readonly ALL = [
+    DataType.UNKNOWN,
+    DataType.FLOAT64,
+    DataType.FLOAT32,
+    DataType.INT64,
+    DataType.INT32,
+    DataType.INT16,
+    DataType.INT8,
+    DataType.UINT64,
+    DataType.UINT32,
+    DataType.UINT16,
+    DataType.UINT8,
+    DataType.TIMESTAMP,
+    DataType.UUID,
+    DataType.STRING,
+    DataType.JSON,
+  ];
+
   static readonly BIG_INT_TYPES = [DataType.INT64, DataType.UINT64, DataType.TIMESTAMP];
 
   /** A zod schema for a DataType. */

package/src/toArray.ts

@@ -9,3 +9,6 @@
 
 export const toArray = <T>(value: T | T[]): T[] =>
   Array.isArray(value) ? value : [value];
+
+export const nullToArr = <T>(value: T | T[] | null): T[] =>
+  Array.isArray(value) ? value : value === null ? [] : [value];

package/dist/deep/key.d.ts

@@ -1,30 +0,0 @@
-import { type Join } from '../join';
-type Prev = [
-    never,
-    0,
-    1,
-    2,
-    3,
-    4,
-    5,
-    6,
-    7,
-    8,
-    9,
-    10,
-    11,
-    12,
-    13,
-    14,
-    15,
-    16,
-    17,
-    18,
-    19,
-    20,
-    ...Array<0>
-];
-export type Key<T, D extends number = 5> = [D] extends [never] ? never : T extends object ? {
-    [K in keyof T]-?: K extends string | number ? `${K}` | Join<K, Key<T[K], Prev[D]>> : never;
-}[keyof T] : "";
-export {};

package/src/deep/key.ts

@@ -1,46 +0,0 @@
-// Copyright 2023 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 { type Join } from "@/join";
-
-type Prev = [
-  never,
-  0,
-  1,
-  2,
-  3,
-  4,
-  5,
-  6,
-  7,
-  8,
-  9,
-  10,
-  11,
-  12,
-  13,
-  14,
-  15,
-  16,
-  17,
-  18,
-  19,
-  20,
-  ...Array<0>,
-];
-
-export type Key<T, D extends number = 5> = [D] extends [never]
-  ? never
-  : T extends object
-  ? {
-      [K in keyof T]-?: K extends string | number
-        ? `${K}` | Join<K, Key<T[K], Prev[D]>>
-        : never;
-    }[keyof T]
-  : "";