@synnaxlabs/x 0.41.0 → 0.42.1

package/src/telem/series.spec.ts

@@ -107,6 +107,13 @@ describe("Series", () => {
       expect(s.length).toEqual(3);
     });
 
+    it("should construct a series from an int32 array", () => {
+      const s = new Series(new Int32Array([1, 2, 3]));
+      expect(s.dataType.equals(DataType.INT32)).toBeTruthy();
+      expect(s.length).toEqual(3);
+      expect(Array.from(s)).toEqual([1, 2, 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();
@@ -762,6 +769,31 @@ describe("Series", () => {
     });
   });
 
+  describe("toString", () => {
+    interface Spec {
+      series: Series;
+      expected: string;
+    }
+    const SPECS: Spec[] = [
+      {
+        series: new Series({ data: [1, 2, 3, 4], dataType: "float64" }),
+        expected: "float64 4 [1,2,3,4]",
+      },
+      {
+        series: new Series({
+          data: Array.from({ length: 100 }, (_, i) => i),
+          dataType: "float32",
+        }),
+        expected: "float32 100 [0,1,2,3,4...95,96,97,98,99]",
+      },
+    ];
+    SPECS.forEach(({ series, expected }) => {
+      it(`should convert ${series.toString()} to a string`, () => {
+        expect(series.toString()).toEqual(expected);
+      });
+    });
+  });
+
   describe("sub", () => {
     it("should return a sub-series backed by the same buffer", () => {
       const arr = new Float32Array([1, 2, 3, 4, 5]);

package/src/telem/series.ts

@@ -158,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;
@@ -211,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;
@@ -287,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,
@@ -341,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");
   }
 
   /**
@@ -445,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);
@@ -509,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,
@@ -720,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,
     };
@@ -789,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),
@@ -804,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),
@@ -821,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> {
@@ -878,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;
@@ -888,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),
     };
   }
 
@@ -925,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++)
@@ -972,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 {
@@ -1055,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));
   }
@@ -1074,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();
     });
   });