@synnaxlabs/x 0.40.0 → 0.42.0

package/src/telem/series.ts

@@ -126,6 +126,17 @@ const nullArrayZ = z
 
 const NEW_LINE = 10;
 
+type JSType = "string" | "number" | "bigint";
+
+const checkAsType = (jsType: JSType, dataType: DataType) => {
+  if (jsType === "string" && !dataType.isVariable)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to string`);
+  if (jsType === "number" && !dataType.isNumeric)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to number`);
+  if (jsType === "bigint" && !dataType.usesBigInt)
+    throw new Error(`cannot convert series of type ${dataType.toString()} to bigint`);
+};
+
 /**
  * Series is a strongly typed array of telemetry samples backed by an underlying binary
  * buffer.
@@ -147,7 +158,7 @@ export class Series<T extends TelemValue = TelemValue> {
   private readonly gl: GL;
   /** The underlying data. */
   private readonly _data: ArrayBuffer;
-  readonly _timeRange?: TimeRange;
+  readonly timeRange: TimeRange = TimeRange.ZERO;
   readonly alignment: bigint = 0n;
   /** A cached minimum value. */
   private _cachedMin?: math.Numeric;
@@ -200,7 +211,7 @@ export class Series<T extends TelemValue = TelemValue> {
       this.sampleOffset = data_.sampleOffset;
       this.gl = data_.gl;
       this._data = data_._data;
-      this._timeRange = data_._timeRange;
+      this.timeRange = data_.timeRange;
       this.alignment = data_.alignment;
       this._cachedMin = data_._cachedMin;
       this._cachedMax = data_._cachedMax;
@@ -276,7 +287,7 @@ export class Series<T extends TelemValue = TelemValue> {
     this.key = key;
     this.alignment = alignment;
     this.sampleOffset = sampleOffset ?? 0;
-    this._timeRange = timeRange;
+    this.timeRange = timeRange ?? TimeRange.ZERO;
     this.gl = {
       control: null,
       buffer: null,
@@ -330,11 +341,13 @@ export class Series<T extends TelemValue = TelemValue> {
   }
 
   release(): void {
+    if (this._refCount <= 0) {
+      console.warn("attempted to release a series with a negative reference count");
+      return;
+    }
     this._refCount--;
     if (this._refCount === 0 && this.gl.control != null)
       this.maybeGarbageCollectGLBuffer(this.gl.control);
-    else if (this._refCount < 0)
-      throw new Error("cannot release an array with a negative reference count");
   }
 
   /**
@@ -434,12 +447,6 @@ export class Series<T extends TelemValue = TelemValue> {
       .map((s) => schema.parse(binary.JSON_CODEC.decodeString(s)));
   }
 
-  /** @returns the time range of this array. */
-  get timeRange(): TimeRange {
-    if (this._timeRange == null) throw new Error("time range not set on series");
-    return this._timeRange;
-  }
-
   /** @returns the capacity of the series in bytes. */
   get byteCapacity(): Size {
     return new Size(this.underlyingData.byteLength);
@@ -498,7 +505,7 @@ export class Series<T extends TelemValue = TelemValue> {
     return new Series({
       data: data.buffer,
       dataType: target,
-      timeRange: this._timeRange,
+      timeRange: this.timeRange,
       sampleOffset,
       glBufferUsage: this.gl.bufferUsage,
       alignment: this.alignment,
@@ -696,28 +703,8 @@ export class Series<T extends TelemValue = TelemValue> {
   as(jsType: "bigint"): Series<bigint>;
 
   as<T extends TelemValue>(jsType: "string" | "number" | "bigint"): Series<T> {
-    if (jsType === "string") {
-      if (!this.dataType.equals(DataType.STRING))
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to string`,
-        );
-      return this as unknown as Series<T>;
-    }
-    if (jsType === "number") {
-      if (!this.dataType.isNumeric)
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to number`,
-        );
-      return this as unknown as Series<T>;
-    }
-    if (jsType === "bigint") {
-      if (!this.dataType.equals(DataType.INT64))
-        throw new Error(
-          `cannot convert series of type ${this.dataType.toString()} to bigint`,
-        );
-      return this as unknown as Series<T>;
-    }
-    throw new Error(`cannot convert series to ${jsType as string}`);
+    checkAsType(jsType, this.dataType);
+    return this as unknown as Series<T>;
   }
 
   get digest(): SeriesDigest {
@@ -729,7 +716,7 @@ export class Series<T extends TelemValue = TelemValue> {
         lower: alignmentDigest(this.alignmentBounds.lower),
         upper: alignmentDigest(this.alignmentBounds.upper),
       },
-      timeRange: this._timeRange?.toString(),
+      timeRange: this.timeRange?.toString(),
       length: this.length,
       capacity: this.capacity,
     };
@@ -798,7 +785,7 @@ export class Series<T extends TelemValue = TelemValue> {
     return new Series({
       data,
       dataType: this.dataType,
-      timeRange: this._timeRange,
+      timeRange: this.timeRange,
       sampleOffset: this.sampleOffset,
       glBufferUsage: this.gl.bufferUsage,
       alignment: this.alignment + BigInt(start),
@@ -813,7 +800,7 @@ export class Series<T extends TelemValue = TelemValue> {
     return new Series({
       data,
       dataType: this.dataType,
-      timeRange: this._timeRange,
+      timeRange: this.timeRange,
       sampleOffset: this.sampleOffset,
       glBufferUsage: this.gl.bufferUsage,
       alignment: this.alignment + BigInt(start),
@@ -830,6 +817,24 @@ export class Series<T extends TelemValue = TelemValue> {
       alignment,
     });
   }
+
+  toString(): string {
+    let data = `${this.dataType.toString()} ${this.length} [`;
+    if (this.length <= 10) data += Array.from(this).map((v) => v.toString());
+    else {
+      for (let i = 0; i < 5; i++) {
+        data += `${this.at(i)?.toString()}`;
+        if (i < 4) data += ",";
+      }
+      data += "...";
+      for (let i = -5; i < 0; i++) {
+        data += this.at(i)?.toString();
+        if (i < -1) data += ",";
+      }
+    }
+    data += "]";
+    return data;
+  }
 }
 
 class SubIterator<T> implements Iterator<T>, Iterable<T> {
@@ -887,6 +892,7 @@ class StringSeriesIterator implements Iterator<string> {
 
 class JSONSeriesIterator implements Iterator<unknown> {
   private readonly wrapped: Iterator<string>;
+  private static SCHEMA = z.record(z.string(), z.unknown());
 
   constructor(wrapped: Iterator<string>) {
     this.wrapped = wrapped;
@@ -897,7 +903,7 @@ class JSONSeriesIterator implements Iterator<unknown> {
     if (next.done === true) return { done: true, value: undefined };
     return {
       done: false,
-      value: binary.JSON_CODEC.decodeString(next.value),
+      value: binary.JSON_CODEC.decodeString(next.value, JSONSeriesIterator.SCHEMA),
     };
   }
 
@@ -934,7 +940,7 @@ class FixedSeriesIterator implements Iterator<math.Numeric> {
 export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<T> {
   readonly series: Array<Series<T>>;
 
-  constructor(series: Array<Series<T>>) {
+  constructor(series: Array<Series<T>> = []) {
     if (series.length !== 0) {
       const type = series[0].dataType;
       for (let i = 1; i < series.length; i++)
@@ -950,11 +956,8 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
 
   as(jsType: "bigint"): MultiSeries<bigint>;
 
-  as<T extends TelemValue>(dataType: CrudeDataType): MultiSeries<T> {
-    if (!new DataType(dataType).equals(this.dataType))
-      throw new Error(
-        `cannot convert series of type ${this.dataType.toString()} to ${dataType.toString()}`,
-      );
+  as<T extends TelemValue>(jsType: "string" | "number" | "bigint"): MultiSeries<T> {
+    checkAsType(jsType, this.dataType);
     return this as unknown as MultiSeries<T>;
   }
 
@@ -984,8 +987,12 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
     );
   }
 
-  push(series: Series<T>): void {
-    this.series.push(series);
+  push(series: Series<T>): void;
+  push(series: MultiSeries<T>): void;
+
+  push(series: Series<T> | MultiSeries<T>): void {
+    if ("isSynnaxSeries" in series && series.isSynnaxSeries) this.series.push(series);
+    else this.series.push(...(series as MultiSeries<T>).series);
   }
 
   get length(): number {
@@ -1067,6 +1074,14 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
     return new MultiSubIterator(this, startIdx, startIdx + span);
   }
 
+  updateGLBuffer(gl: GLBufferController): void {
+    this.series.forEach((s) => s.updateGLBuffer(gl));
+  }
+
+  get bounds(): bounds.Bounds {
+    return bounds.max(this.series.map((s) => s.bounds));
+  }
+
   get byteLength(): Size {
     return new Size(this.series.reduce((a, b) => a + b.byteLength.valueOf(), 0));
   }
@@ -1086,6 +1101,14 @@ export class MultiSeries<T extends TelemValue = TelemValue> implements Iterable<
     return bounds.traverse(b, start, dist);
   }
 
+  acquire(): void {
+    this.series.forEach((s) => s.acquire());
+  }
+
+  release(): void {
+    this.series.forEach((s) => s.release());
+  }
+
   distance(start: bigint, end: bigint): bigint {
     const b = this.series.map((s) => s.alignmentBounds);
     return bounds.distance(b, start, end);

package/src/telem/telem.spec.ts

@@ -19,6 +19,7 @@ import {
   TimeRange,
   TimeSpan,
   TimeStamp,
+  type TimeStampStringFormat,
 } from "@/telem";
 
 describe("TimeStamp", () => {
@@ -177,19 +178,159 @@ describe("TimeStamp", () => {
     expect(ts.sub(TimeSpan.microseconds()).equals(new TimeStamp(0))).toBeTruthy();
   });
 
-  test("stringification", () => {
+  describe("fString", () => {
     const ts = new TimeStamp([2022, 12, 15], "UTC")
       .add(TimeSpan.hours(12))
       .add(TimeSpan.minutes(20))
       .add(TimeSpan.milliseconds(12));
-    expect(ts.fString("ISO", "UTC")).toEqual("2022-12-15T12:20:00.012Z");
-    expect(ts.fString("time", "UTC")).toEqual("12:20:00");
-    expect(ts.fString("date", "UTC")).toEqual("Dec 15");
-    if (!TimeStamp.utcOffset.equals(0)) {
-      expect(ts.fString("ISO", "local")).not.toEqual("2022-12-15T12:20:00.012Z");
-      expect(ts.fString("time", "local")).not.toEqual("12:20:00");
-    }
+
+    const FORMAT_TESTS: [TimeStampStringFormat, string][] = [
+      ["ISO", "2022-12-15T12:20:00.012Z"],
+      ["ISODate", "2022-12-15"],
+      ["ISOTime", "12:20:00.012"],
+      ["time", "12:20:00"],
+      ["preciseTime", "12:20:00.012"],
+      ["date", "Dec 15"],
+      ["preciseDate", "Dec 15 12:20:00.012"],
+      ["dateTime", "Dec 15 12:20:00"],
+    ];
+
+    FORMAT_TESTS.forEach(([format, expected]) => {
+      test(`should format timestamp as ${format}`, () => {
+        expect(ts.fString(format, "UTC")).toEqual(expected);
+      });
+    });
   });
+
+  describe("unit getters", () => {
+    test("hour", () => {
+      expect(TimeStamp.hours(1).add(TimeSpan.minutes(30)).hour).toEqual(1);
+    });
+    test("hours", () => {
+      expect(TimeStamp.hours(1).add(TimeSpan.minutes(30)).hours).toEqual(1.5);
+    });
+    test("minute", () => {
+      expect(TimeStamp.minutes(1).add(TimeStamp.seconds(20)).minute).toEqual(1);
+    });
+    test("minutes", () => {
+      expect(TimeStamp.minutes(1).add(TimeStamp.seconds(30)).minutes).toEqual(1.5);
+    });
+    test("second", () => {
+      expect(TimeStamp.seconds(1).add(TimeStamp.milliseconds(20)).second).toEqual(1);
+    });
+    test("seconds", () => {
+      expect(TimeStamp.seconds(1).add(TimeStamp.milliseconds(500)).seconds).toEqual(
+        1.5,
+      );
+    });
+    test("millisecond", () => {
+      expect(
+        TimeStamp.milliseconds(1).add(TimeStamp.microseconds(20)).millisecond,
+      ).toEqual(1);
+    });
+    test("milliseconds", () => {
+      expect(
+        TimeStamp.milliseconds(1).add(TimeStamp.microseconds(500)).milliseconds,
+      ).toEqual(1.5);
+    });
+    test("microseconds", () => {
+      expect(
+        TimeStamp.microseconds(500).add(TimeSpan.nanoseconds(20)).microseconds,
+      ).toEqual(500.02);
+    });
+    test("nanoseconds", () => {
+      expect(
+        TimeStamp.microseconds(1).add(TimeSpan.nanoseconds(30)).nanoseconds,
+      ).toEqual(1030);
+    });
+    test("year", () => {
+      expect(new TimeStamp([2022, 12, 15]).year).toEqual(2022);
+    });
+    test("month", () => {
+      expect(new TimeStamp([2022, 12, 15]).month).toEqual(11);
+    });
+    test("day", () => {
+      expect(new TimeStamp([2022, 12, 15]).day).toEqual(15);
+    });
+  });
+
+  describe("unit setters", () => {
+    test("setYear", () => {
+      const ts = new TimeStamp([2022, 12, 15]);
+      const updated = ts.setYear(2023);
+      expect(updated.year).toEqual(2023);
+      expect(updated.month).toEqual(ts.month); // Other components should remain unchanged
+      expect(updated.day).toEqual(ts.day);
+    });
+
+    test("setMonth", () => {
+      const ts = new TimeStamp([2022, 12, 15]);
+      const updated = ts.setMonth(5); // June (0-indexed)
+      expect(updated.month).toEqual(5);
+      expect(updated.year).toEqual(ts.year); // Other components should remain unchanged
+      expect(updated.day).toEqual(ts.day);
+    });
+
+    test("setDay", () => {
+      const ts = new TimeStamp([2022, 12, 15]);
+      const updated = ts.setDay(20);
+      expect(updated.day).toEqual(20);
+      expect(updated.year).toEqual(ts.year);
+      expect(updated.month).toEqual(ts.month);
+    });
+
+    test("setHour", () => {
+      const ts = new TimeStamp([2022, 12, 15]).add(TimeSpan.hours(10));
+      const updated = ts.setHour(15);
+      expect(updated.hour).toEqual(15);
+      expect(updated.year).toEqual(ts.year);
+      expect(updated.month).toEqual(ts.month);
+      expect(updated.day).toEqual(ts.day);
+    });
+
+    test("setMinute", () => {
+      const ts = new TimeStamp([2022, 12, 15])
+        .add(TimeSpan.hours(10))
+        .add(TimeSpan.minutes(30));
+      const updated = ts.setMinute(45);
+      expect(updated.minute).toEqual(45);
+      expect(updated.hour).toEqual(ts.hour);
+      expect(updated.year).toEqual(ts.year);
+      expect(updated.month).toEqual(ts.month);
+      expect(updated.day).toEqual(ts.day);
+    });
+
+    test("setSecond", () => {
+      const ts = new TimeStamp([2022, 12, 15])
+        .add(TimeSpan.hours(10))
+        .add(TimeSpan.minutes(30))
+        .add(TimeSpan.seconds(20));
+      const updated = ts.setSecond(45);
+      expect(updated.second).toEqual(45);
+      expect(updated.minute).toEqual(ts.minute); // Other components should remain unchanged
+      expect(updated.hour).toEqual(ts.hour);
+      expect(updated.year).toEqual(ts.year);
+      expect(updated.month).toEqual(ts.month);
+      expect(updated.day).toEqual(ts.day);
+    });
+
+    test("setMillisecond", () => {
+      const ts = new TimeStamp([2022, 12, 15])
+        .add(TimeSpan.hours(10))
+        .add(TimeSpan.minutes(30))
+        .add(TimeSpan.seconds(20))
+        .add(TimeSpan.milliseconds(100));
+      const updated = ts.setMillisecond(500);
+      expect(updated.millisecond).toEqual(500);
+      expect(updated.second).toEqual(ts.second); // Other components should remain unchanged
+      expect(updated.minute).toEqual(ts.minute);
+      expect(updated.hour).toEqual(ts.hour);
+      expect(updated.year).toEqual(ts.year);
+      expect(updated.month).toEqual(ts.month);
+      expect(updated.day).toEqual(ts.day);
+    });
+  });
+
   describe("remainder", () => {
     test("day", () => {
       const expectedRemainder = TimeStamp.hours(12)
@@ -463,8 +604,8 @@ describe("TimeRange", () => {
         TimeSpan.seconds(1),
         TimeSpan.seconds(4).add(TimeSpan.milliseconds(500)),
       );
-      expect(tr.roughlyEquals(one, TimeSpan.seconds(1))).toBeTruthy();
-      expect(tr.roughlyEquals(one, TimeSpan.seconds(0))).toBeFalsy();
+      expect(tr.equals(one, TimeSpan.seconds(1))).toBeTruthy();
+      expect(tr.equals(one, TimeSpan.seconds(0))).toBeFalsy();
     });
   });