@synnaxlabs/x 0.42.1 → 0.43.0

package/src/telem/series.spec.ts

@@ -8,11 +8,18 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it, test } from "vitest";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 import { MockGLBufferController } from "@/mock/MockGLBufferController";
-import { isCrudeSeries, MultiSeries, Series } from "@/telem/series";
-import { DataType, Rate, Size, TimeRange, TimeSpan, TimeStamp } from "@/telem/telem";
+import { type CrudeSeries, isCrudeSeries, MultiSeries, Series } from "@/telem/series";
+import {
+  type CrudeDataType,
+  DataType,
+  Size,
+  TimeRange,
+  TimeSpan,
+  TimeStamp,
+} from "@/telem/telem";
 
 describe("Series", () => {
   describe("construction", () => {
@@ -201,6 +208,22 @@ describe("Series", () => {
       expect(strContent).toBe('{"a_b":1,"b_c":"apple"}\n');
     });
 
+    it("should throw an error when an empty JS array is provided and no data type is provided", () => {
+      expect(() => {
+        new Series({ data: [] });
+      }).toThrow(
+        "cannot infer data type from a zero length JS array when constructing a Series. Please provide a data type.",
+      );
+    });
+
+    it("should throw an error when constructing a series from a symbol", () => {
+      expect(() => {
+        new Series({ data: [Symbol("123")] });
+      }).toThrow(
+        "cannot infer data type of symbol when constructing a Series from a JS array",
+      );
+    });
+
     it("should decode keys from snake_case to camelCase", () => {
       const a = new Series({
         data: [{ a_b: 1, b_c: "apple" }],
@@ -353,23 +376,47 @@ describe("Series", () => {
   });
 
   describe("min and max", () => {
-    it("should return a min and max of zero on an allocated array", () => {
-      const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
-      expect(series.max).toEqual(-Infinity);
-      expect(series.min).toEqual(Infinity);
+    describe("numbers", () => {
+      it("should return a min and max of zero on an allocated array", () => {
+        const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+        expect(series.max).toEqual(-Infinity);
+        expect(series.min).toEqual(Infinity);
+      });
+      it("should correctly calculate the min and max of a lazy array", () => {
+        const series = new Series({
+          data: new Float32Array([1, 2, 3]),
+          dataType: DataType.FLOAT32,
+        });
+        expect(series.max).toEqual(3);
+        expect(series.min).toEqual(1);
+      });
     });
-    it("should correctly calculate the min and max of a lazy array", () => {
-      const series = new Series({
-        data: new Float32Array([1, 2, 3]),
-        dataType: DataType.FLOAT32,
+    describe("bigints", () => {
+      it("should return a min and max of zero on an allocated array", () => {
+        const series = Series.alloc({ capacity: 10, dataType: DataType.INT64 });
+        expect(series.max).toEqual(-Infinity);
+        expect(series.min).toEqual(Infinity);
+      });
+      it("should correctly calculate the min and max of a lazy array", () => {
+        const series = new Series({
+          data: new BigInt64Array([1n, 2n, 3n]),
+          dataType: DataType.INT64,
+        });
+        expect(series.max).toEqual(3n);
+        expect(series.min).toEqual(1n);
       });
-      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();
+      const series = new Series({
+        data: ["a", "b", "c"],
+        dataType: DataType.STRING,
+      });
+      expect(() => series.min).toThrow(
+        "cannot calculate minimum on a variable length data type",
+      );
+      expect(() => series.max).toThrow(
+        "cannot calculate maximum on a variable length data type",
+      );
     });
   });
 
@@ -404,7 +451,7 @@ describe("Series", () => {
     });
   });
 
-  describe("writing", () => {
+  describe("write", () => {
     it("should correctly write to an allocated lazy array", () => {
       const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       expect(series.byteCapacity).toEqual(Size.bytes(40));
@@ -419,11 +466,27 @@ describe("Series", () => {
 
     it("should recompute cached max and min correctly", () => {
       const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
-      series.enrich();
-      const writeTwo = new Series({ data: new Float32Array([2, 3]) });
-      series.write(writeTwo);
+      expect(series.max).toEqual(-Infinity);
+      expect(series.min).toEqual(Infinity);
+      const writeOne = new Series({ data: new Float32Array([2, 3]) });
+      series.write(writeOne);
       expect(series.max).toEqual(3);
       expect(series.min).toEqual(2);
+      const writeTwo = new Series({ data: new Float32Array([4, 5]) });
+      series.write(writeTwo);
+      expect(series.max).toEqual(5);
+      expect(series.min).toEqual(2);
+    });
+
+    it("should recompute the length of a variable density array", () => {
+      const series = Series.alloc({ capacity: 12, dataType: DataType.STRING });
+      expect(series.length).toEqual(0);
+      const writeOne = new Series({ data: ["apple"] });
+      expect(series.write(writeOne)).toEqual(1);
+      expect(series.length).toEqual(1);
+      const writeTwo = new Series({ data: ["apple"] });
+      expect(series.write(writeTwo)).toEqual(1);
+      expect(series.length).toEqual(2);
     });
 
     it("should correctly adjust the sample offset of a written array", () => {
@@ -448,27 +511,6 @@ describe("Series", () => {
     });
   });
 
-  describe("createTimeStamps", () => {
-    it("should correctly create timestamps", () => {
-      const ts = Series.createTimestamps(5, Rate.hz(1), TimeStamp.seconds(1));
-      expect(ts.timeRange).toEqual(
-        new TimeRange(TimeStamp.seconds(1), TimeStamp.seconds(6)),
-      );
-      expect(ts.capacity).toEqual(5);
-      expect(ts.length).toEqual(5);
-      expect(ts.dataType.toString()).toEqual(DataType.TIMESTAMP.toString());
-      expect(ts.data).toEqual(
-        new BigInt64Array([
-          BigInt(TimeStamp.seconds(1).valueOf()),
-          BigInt(TimeStamp.seconds(2).valueOf()),
-          BigInt(TimeStamp.seconds(3).valueOf()),
-          BigInt(TimeStamp.seconds(4).valueOf()),
-          BigInt(TimeStamp.seconds(5).valueOf()),
-        ]),
-      );
-    });
-  });
-
   describe("webgl buffering", () => {
     it("should correctly buffer a new lazy array", () => {
       const series = new Series({
@@ -486,6 +528,7 @@ describe("Series", () => {
       expect(buf.byteLength).toEqual(12);
       expect(buf).toEqual(new Float32Array([1, 2, 3]).buffer);
     });
+
     it("should correctly update a buffer when writing to an allocated array", () => {
       const series = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
       const controller = new MockGLBufferController();
@@ -560,35 +603,12 @@ describe("Series", () => {
 
   describe("string series", () => {
     it("should correctly encode and decode a string series", () => {
-      const s = Series.fromStrings(["apple", "banana", "carrot"]);
+      const s = new Series(["apple", "banana", "carrot"]);
       expect(s.dataType.toString()).toEqual(DataType.STRING.toString());
       const outStrings = s.toStrings();
       expect(outStrings).toEqual(["apple", "banana", "carrot"]);
     });
 
-    it("should throw an error if the series is not of type string", () => {
-      const s = new Series({ data: new Float32Array([1, 2, 3]) });
-      expect(() => {
-        s.toStrings();
-      }).toThrow();
-    });
-
-    it("should not throw an error if the series is of type UUID", () => {
-      const s = new Series({
-        data: new Uint8Array([1, 2, 3]),
-        dataType: DataType.UUID,
-      });
-      expect(() => {
-        s.toStrings();
-      }).not.toThrow();
-    });
-
-    it("should return an array of length 0 if the series is empty", () => {
-      const s = new Series({ data: new Float32Array([]), dataType: DataType.STRING });
-      const outStrings = s.toStrings();
-      expect(outStrings).toEqual([]);
-    });
-
     it("should allow allocation of a particular byte capacity", () => {
       const s = Series.alloc({ capacity: 10, dataType: DataType.STRING });
       expect(s.byteCapacity).toEqual(Size.bytes(10));
@@ -634,7 +654,7 @@ describe("Series", () => {
         a: z.number(),
         b: z.string(),
       });
-      const s = Series.fromJSON<z.output<typeof schema>>([
+      const s = new Series([
         { a: 1, b: "apple" },
         { a: 2, b: "banana" },
         { a: 3, b: "carrot" },
@@ -737,6 +757,106 @@ describe("Series", () => {
     });
   });
 
+  describe("toStrings", () => {
+    interface Spec {
+      name: string;
+      values: CrudeSeries;
+      expected: string[];
+      dataType?: CrudeDataType;
+    }
+    const SPECS: Spec[] = [
+      {
+        name: "string",
+        values: ["apple", "banana", "carrot"],
+        expected: ["apple", "banana", "carrot"],
+      },
+      {
+        name: "json",
+        values: [
+          { a: 1, b: "apple" },
+          { a: 2, b: "banana" },
+          { a: 3, b: "carrot" },
+        ],
+        expected: [
+          '{"a":1,"b":"apple"}',
+          '{"a":2,"b":"banana"}',
+          '{"a":3,"b":"carrot"}',
+        ],
+        dataType: "json",
+      },
+      {
+        name: "number",
+        values: [1, 2, 3],
+        expected: ["1", "2", "3"],
+      },
+      {
+        name: "bigint",
+        values: [BigInt(1), BigInt(2), BigInt(3)],
+        expected: ["1", "2", "3"],
+      },
+    ];
+    SPECS.forEach(({ name, values, expected }) => {
+      it(`should correctly convert a ${name} series to strings`, () => {
+        const s = new Series({ data: values });
+        expect(s.toStrings()).toEqual(expected);
+      });
+    });
+
+    it("should return an series of length 0 if the series is empty", () => {
+      const s = new Series({ data: new Float32Array([]), dataType: DataType.STRING });
+      const outStrings = s.toStrings();
+      expect(outStrings).toEqual([]);
+    });
+  });
+
+  describe("toUUIDs", () => {
+    it("should convert a UUID series to an array of UUID strings", () => {
+      // Valid UUID v4 bytes (version 4, variant 1)
+      const bytes = new Uint8Array([
+        // First UUID: 123e4567-e89b-4xxx-yxxx-426614174000 (version 4, variant 1)
+        0x12, 0x3e, 0x45, 0x67, 0xe8, 0x9b, 0x40, 0xd3, 0x80, 0x56, 0x42, 0x66, 0x14,
+        0x17, 0x40, 0x00,
+        // Second UUID: 7f3e4567-e89b-4xxx-yxxx-426614174000 (version 4, variant 1)
+        0x7f, 0x3e, 0x45, 0x67, 0xe8, 0x9b, 0x40, 0xd3, 0x80, 0x56, 0x42, 0x66, 0x14,
+        0x17, 0x40, 0x00,
+      ]);
+      const series = new Series({ data: bytes, dataType: DataType.UUID });
+      const uuids = series.toUUIDs();
+      expect(uuids).toHaveLength(2);
+      expect(uuids[0]).toBe("123e4567-e89b-40d3-8056-426614174000");
+      expect(uuids[1]).toBe("7f3e4567-e89b-40d3-8056-426614174000");
+    });
+
+    it("should throw an error when converting non-UUID series", () => {
+      const series = new Series({ data: [1, 2, 3], dataType: DataType.INT32 });
+      expect(() => series.toUUIDs()).toThrow("cannot convert non-uuid series to uuids");
+    });
+
+    it("should handle empty UUID series", () => {
+      const series = new Series({ data: new Uint8Array(), dataType: DataType.UUID });
+      const uuids = series.toUUIDs();
+      expect(uuids).toHaveLength(0);
+    });
+
+    it("should handle series with nil UUID", () => {
+      // Nil UUID: 00000000-0000-0000-0000-000000000000
+      const bytes = new Uint8Array(16).fill(0);
+      const series = new Series({ data: bytes, dataType: DataType.UUID });
+      const uuids = series.toUUIDs();
+      expect(uuids).toHaveLength(1);
+      expect(uuids[0]).toBe("00000000-0000-0000-0000-000000000000");
+    });
+
+    it("should handle series with max UUID", () => {
+      // Max UUID: ffffffff-ffff-ffff-ffff-ffffffffffff
+      const bytes = new Uint8Array(16).fill(0xff);
+      const series = new Series({ data: bytes, dataType: DataType.UUID });
+      const uuids = series.toUUIDs();
+      expect(uuids).toHaveLength(1);
+      expect(uuids[0]).toBe("ffffffff-ffff-ffff-ffff-ffffffffffff");
+    });
+  });
+
   describe("digest", () => {
     it("should return a digest of information about the series", () => {
       const digest = new Series({
@@ -777,14 +897,14 @@ describe("Series", () => {
     const SPECS: Spec[] = [
       {
         series: new Series({ data: [1, 2, 3, 4], dataType: "float64" }),
-        expected: "float64 4 [1,2,3,4]",
+        expected: "Series(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]",
+        expected: "Series(float32 100 [0,1,2,3,4,...,95,96,97,98,99])",
       },
     ];
     SPECS.forEach(({ series, expected }) => {
@@ -837,6 +957,122 @@ describe("Series", () => {
       expect(iter.next().done).toBeTruthy();
     });
   });
+
+  describe("bounds", () => {
+    it("should return the bounds of the series", () => {
+      const series = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.bounds).toEqual({ lower: 1, upper: 3 });
+    });
+
+    it("should handle negative numbers", () => {
+      const series = new Series({
+        data: new Float32Array([-3, -2, -1]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.bounds).toEqual({ lower: -3, upper: -1 });
+    });
+
+    it("should handle empty series", () => {
+      const series = new Series({
+        data: new Float32Array([]),
+        dataType: DataType.FLOAT32,
+      });
+      expect(series.bounds).toEqual({ lower: Infinity, upper: -Infinity });
+    });
+  });
+
+  describe("reAlign", () => {
+    it("should create a new series with the specified alignment", () => {
+      const original = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.alignment).toBe(10n);
+      expect(realigned.alignmentBounds).toEqual({ lower: 10n, upper: 13n });
+      expect(realigned.data).toEqual(original.data);
+    });
+
+    it("should preserve data when realigning", () => {
+      const original = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.at(0)).toBe(1);
+      expect(realigned.at(1)).toBe(2);
+      expect(realigned.at(2)).toBe(3);
+    });
+
+    it("should update alignment bounds correctly", () => {
+      const original = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.alignmentBounds).toEqual({ lower: 10n, upper: 13n });
+    });
+
+    it("should handle atAlignment with new alignment", () => {
+      const original = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.atAlignment(10n)).toBe(1);
+      expect(realigned.atAlignment(11n)).toBe(2);
+      expect(realigned.atAlignment(12n)).toBe(3);
+    });
+
+    it("should handle bigint series", () => {
+      const original = new Series({
+        data: new BigInt64Array([1n, 2n, 3n]),
+        dataType: DataType.INT64,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.alignment).toBe(10n);
+      expect(realigned.alignmentBounds).toEqual({ lower: 10n, upper: 13n });
+      expect(realigned.at(0)).toBe(1n);
+      expect(realigned.at(1)).toBe(2n);
+      expect(realigned.at(2)).toBe(3n);
+    });
+
+    it("should handle variable length data types", () => {
+      const original = new Series({
+        data: ["a", "b", "c"],
+        dataType: DataType.STRING,
+        alignment: 0n,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.alignment).toBe(10n);
+      expect(realigned.alignmentBounds).toEqual({ lower: 10n, upper: 13n });
+      expect(realigned.at(0)).toBe("a");
+      expect(realigned.at(1)).toBe("b");
+      expect(realigned.at(2)).toBe("c");
+    });
+
+    it("should preserve sample offset", () => {
+      const original = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        alignment: 0n,
+        sampleOffset: 10,
+      });
+      const realigned = original.reAlign(10n);
+      expect(realigned.sampleOffset).toBe(10);
+      expect(realigned.at(0)).toBe(11);
+      expect(realigned.at(1)).toBe(12);
+      expect(realigned.at(2)).toBe(13);
+    });
+  });
 });
 
 describe("MultiSeries", () => {
@@ -872,6 +1108,20 @@ describe("MultiSeries", () => {
       expect(multi.at(-5)).toEqual(2);
       expect(multi.at(-6)).toEqual(1);
     });
+
+    it("should return undefined if the index is not found", () => {
+      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(10)).toBeUndefined();
+    });
+
+    it("should throw an error if the index is not found and required is true", () => {
+      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(10, true)).toThrow();
+    });
   });
 
   describe("atAlignment", () => {
@@ -892,6 +1142,24 @@ describe("MultiSeries", () => {
       expect(multi.atAlignment(6n)).toEqual(5);
       expect(multi.atAlignment(7n)).toEqual(6);
     });
+
+    it("should return undefined if the alignment is not found", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        alignment: 1n,
+      });
+      const multi = new MultiSeries([a]);
+      expect(multi.atAlignment(45n)).toBeUndefined();
+    });
+
+    it("should throw if the alignment is not found and required is true", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        alignment: 1n,
+      });
+      const multi = new MultiSeries([a]);
+      expect(() => multi.atAlignment(45n, true)).toThrow();
+    });
   });
 
   describe("subIterator", () => {
@@ -1135,4 +1403,403 @@ describe("MultiSeries", () => {
       expect(() => multi.as("string")).toThrow();
     });
   });
+
+  describe("bounds", () => {
+    it("should return bounds of [Infinity, -Infinity] for an empty MultiSeries", () => {
+      const multiSeries = new MultiSeries();
+      expect(multiSeries.bounds).toEqual({ lower: Infinity, upper: -Infinity });
+    });
+
+    it("should correctly calculate bounds across multiple series", () => {
+      const series1 = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      const series2 = new Series({
+        data: new Float32Array([4, 5, 6]),
+        dataType: DataType.FLOAT32,
+      });
+      const multiSeries = new MultiSeries([series1, series2]);
+      expect(multiSeries.bounds).toEqual({ lower: 1, upper: 6 });
+    });
+
+    it("should handle negative numbers across series", () => {
+      const series1 = new Series({
+        data: new Float32Array([-5, -3, -1]),
+        dataType: DataType.FLOAT32,
+      });
+      const series2 = new Series({
+        data: new Float32Array([0, 2, 4]),
+        dataType: DataType.FLOAT32,
+      });
+      const multiSeries = new MultiSeries([series1, series2]);
+      expect(multiSeries.bounds).toEqual({ lower: -5, upper: 4 });
+    });
+
+    it("should handle sample offsets across series", () => {
+      const series1 = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+        sampleOffset: 10,
+      });
+      const series2 = new Series({
+        data: new Float32Array([4, 5, 6]),
+        dataType: DataType.FLOAT32,
+        sampleOffset: 20,
+      });
+      const multiSeries = new MultiSeries([series1, series2]);
+      expect(multiSeries.bounds).toEqual({ lower: 11, upper: 26 });
+    });
+
+    it("should handle bigint series", () => {
+      const series1 = new Series({
+        data: new BigInt64Array([1n, 2n, 3n]),
+        dataType: DataType.INT64,
+      });
+      const series2 = new Series({
+        data: new BigInt64Array([4n, 5n, 6n]),
+        dataType: DataType.INT64,
+      });
+      const multiSeries = new MultiSeries([series1, series2]);
+      expect(multiSeries.bounds).toEqual({ lower: 1, upper: 6 });
+    });
+
+    it("should throw an error for non-numeric data types", () => {
+      const series1 = new Series({
+        data: ["a", "b", "c"],
+        dataType: DataType.STRING,
+      });
+      const series2 = new Series({
+        data: ["d", "e", "f"],
+        dataType: DataType.STRING,
+      });
+      const multiSeries = new MultiSeries([series1, series2]);
+      expect(() => multiSeries.bounds).toThrow(
+        "cannot calculate minimum on a variable length data type",
+      );
+    });
+  });
+
+  describe("subAlignmentSpanIterator", () => {
+    it("should return an empty iterator when start is beyond bounds", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 3n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(10n, 5);
+      expect(Array.from(iter)).toEqual([]);
+    });
+
+    it("should return an empty iterator when start is at upper bound", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 3n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(6n, 5);
+      expect(Array.from(iter)).toEqual([]);
+    });
+
+    it("should iterate over samples within a single series", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 3n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(1n, 2);
+      expect(Array.from(iter)).toEqual([2, 3]);
+    });
+
+    it("should iterate over samples across multiple series", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 3n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(2n, 3);
+      expect(Array.from(iter)).toEqual([3, 4, 5]);
+    });
+
+    it("should handle span that exceeds available data", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 3n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(4n, 10);
+      expect(Array.from(iter)).toEqual([5, 6]);
+    });
+
+    it("should handle span that exceeds available data with non-continuous spans", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 0n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 500000000n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(4n, 10000000000);
+      expect(Array.from(iter)).toEqual([4, 5, 6]);
+    });
+
+    it("should handle empty series", () => {
+      const ms = new MultiSeries();
+      const iter = ms.subAlignmentSpanIterator(0n, 5);
+      expect(Array.from(iter)).toEqual([]);
+    });
+
+    it("should handle start alignment before first series", () => {
+      const s1 = new Series({ data: [1, 2, 3], alignment: 2n });
+      const s2 = new Series({ data: [4, 5, 6], alignment: 5n });
+      const ms = new MultiSeries([s1, s2]);
+      const iter = ms.subAlignmentSpanIterator(0n, 4);
+      expect(Array.from(iter)).toEqual([1, 2, 3, 4]);
+    });
+  });
+
+  describe("traverseAlignment", () => {
+    it("should traverse alignment across multiple series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        alignment: 1n,
+      });
+      const b = new Series({
+        data: new Float32Array([5, 6, 7]),
+        alignment: 5n,
+      });
+      const multi = new MultiSeries([a, b]);
+      expect(multi.traverseAlignment(1n, 2n)).toEqual(3n);
+      expect(multi.traverseAlignment(2n, 4n)).toEqual(7n);
+      expect(multi.traverseAlignment(5n, 2n)).toEqual(7n);
+    });
+
+    it("should handle empty multi-series", () => {
+      const multi = new MultiSeries();
+      expect(multi.traverseAlignment(1n, 2n)).toEqual(1n);
+    });
+  });
+
+  describe("acquire and release", () => {
+    it("should acquire and release all series in the multi-series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      const b = new Series({
+        data: new Float32Array([4, 5, 6]),
+        dataType: DataType.FLOAT32,
+      });
+      const multi = new MultiSeries([a, b]);
+      const controller = new MockGLBufferController();
+
+      multi.acquire(controller);
+      expect(a.refCount).toEqual(1);
+      expect(b.refCount).toEqual(1);
+      expect(controller.createBufferMock).toHaveBeenCalledTimes(2);
+
+      multi.release();
+      expect(a.refCount).toEqual(0);
+      expect(b.refCount).toEqual(0);
+      expect(controller.deleteBufferMock).toHaveBeenCalledTimes(2);
+    });
+
+    it("should handle empty multi-series", () => {
+      const multi = new MultiSeries();
+      const controller = new MockGLBufferController();
+      multi.acquire(controller);
+      multi.release();
+    });
+  });
+
+  describe("distance", () => {
+    it("should calculate distance between alignments across multiple series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        alignment: 1n,
+      });
+      const b = new Series({
+        data: new Float32Array([5, 6, 7]),
+        alignment: 5n,
+      });
+      const multi = new MultiSeries([a, b]);
+
+      expect(multi.distance(1n, 3n)).toEqual(2n);
+      expect(multi.distance(2n, 6n)).toEqual(3n);
+      expect(multi.distance(5n, 7n)).toEqual(2n);
+    });
+
+    it("should handle empty multi-series", () => {
+      const multi = new MultiSeries();
+      expect(multi.distance(1n, 2n)).toEqual(0n);
+    });
+
+    it("should handle zero distance", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        alignment: 1n,
+      });
+      const multi = new MultiSeries([a]);
+      expect(multi.distance(1n, 1n)).toEqual(0n);
+    });
+  });
+
+  describe("byteLength", () => {
+    it("should return the sum of byte lengths of all series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      const b = new Series({
+        data: new Float32Array([4, 5, 6]),
+        dataType: DataType.FLOAT32,
+      });
+      const multi = new MultiSeries([a, b]);
+      expect(multi.byteLength).toEqual(Size.bytes(24)); // 12 bytes per series (3 * 4 bytes)
+    });
+
+    it("should return 0 for empty multi-series", () => {
+      const multi = new MultiSeries();
+      expect(multi.byteLength).toEqual(Size.bytes(0));
+    });
+  });
+
+  describe("updateGLBuffer", () => {
+    it("should update GL buffers for all series", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      const b = new Series({
+        data: new Float32Array([4, 5, 6]),
+        dataType: DataType.FLOAT32,
+      });
+      const multi = new MultiSeries([a, b]);
+      const controller = new MockGLBufferController();
+
+      multi.updateGLBuffer(controller);
+
+      expect(controller.createBufferMock).toHaveBeenCalledTimes(2);
+      expect(controller.bindBufferMock).toHaveBeenCalledTimes(2);
+      expect(controller.bufferDataMock).toHaveBeenCalledTimes(2);
+    });
+
+    it("should handle empty multi-series", () => {
+      const multi = new MultiSeries();
+      const controller = new MockGLBufferController();
+
+      multi.updateGLBuffer(controller);
+
+      expect(controller.createBufferMock).not.toHaveBeenCalled();
+      expect(controller.bindBufferMock).not.toHaveBeenCalled();
+      expect(controller.bufferDataMock).not.toHaveBeenCalled();
+    });
+
+    it("should throw error for non-FLOAT32/UINT8 series", () => {
+      const a = new Series({
+        data: new BigInt64Array([BigInt(1), BigInt(2)]),
+        dataType: DataType.INT64,
+      });
+      const multi = new MultiSeries([a]);
+      const controller = new MockGLBufferController();
+
+      expect(() => multi.updateGLBuffer(controller)).toThrow(
+        "Only FLOAT32 and UINT8 arrays can be used in WebGL",
+      );
+    });
+
+    it("should handle series with different buffer states", () => {
+      const a = new Series({
+        data: new Float32Array([1, 2, 3]),
+        dataType: DataType.FLOAT32,
+      });
+      const b = Series.alloc({ capacity: 10, dataType: DataType.FLOAT32 });
+      const multi = new MultiSeries([a, b]);
+      const controller = new MockGLBufferController();
+
+      multi.updateGLBuffer(controller);
+
+      expect(controller.createBufferMock).toHaveBeenCalledTimes(2);
+      expect(controller.bindBufferMock).toHaveBeenCalledTimes(1);
+      expect(controller.bufferDataMock).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("push", () => {
+    it("should push a single Series to an empty MultiSeries", () => {
+      const series = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const multiSeries = new MultiSeries();
+      multiSeries.push(series);
+      expect(multiSeries.series.length).toBe(1);
+      expect(multiSeries.series[0]).toBe(series);
+    });
+
+    it("should push a single Series to a non-empty MultiSeries", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const series2 = new Series({ data: [4, 5, 6], dataType: DataType.FLOAT32 });
+      const multiSeries = new MultiSeries([series1]);
+      multiSeries.push(series2);
+      expect(multiSeries.series.length).toBe(2);
+      expect(multiSeries.series[0]).toBe(series1);
+      expect(multiSeries.series[1]).toBe(series2);
+    });
+
+    it("should push a MultiSeries to another MultiSeries", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const series2 = new Series({ data: [4, 5, 6], dataType: DataType.FLOAT32 });
+      const multiSeries1 = new MultiSeries([series1]);
+      const multiSeries2 = new MultiSeries([series2]);
+      multiSeries1.push(multiSeries2);
+      expect(multiSeries1.series.length).toBe(2);
+      expect(multiSeries1.series[0]).toBe(series1);
+      expect(multiSeries1.series[1]).toBe(series2);
+    });
+
+    it("should maintain data type consistency when pushing series", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const series2 = new Series({ data: [4, 5, 6], dataType: DataType.FLOAT32 });
+      const multiSeries = new MultiSeries([series1]);
+      multiSeries.push(series2);
+      expect(multiSeries.dataType).toEqual(DataType.FLOAT32);
+    });
+
+    it("should push an empty MultiSeries to a non-empty MultiSeries", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const multiSeries1 = new MultiSeries([series1]);
+      const multiSeries2 = new MultiSeries();
+      multiSeries1.push(multiSeries2);
+      expect(multiSeries1.series.length).toBe(1);
+    });
+
+    it("should push an empty MultiSeries to an empty MultiSeries", () => {
+      const multiSeries1 = new MultiSeries();
+      const multiSeries2 = new MultiSeries();
+      multiSeries1.push(multiSeries2);
+      expect(multiSeries1.series.length).toBe(0);
+    });
+
+    it("should update time range when pushing series", () => {
+      const timeRange1 = new TimeRange(1, 2);
+      const timeRange2 = new TimeRange(2, 3);
+      const series1 = new Series({
+        data: [1, 2, 3],
+        dataType: DataType.FLOAT32,
+        timeRange: timeRange1,
+      });
+      const series2 = new Series({
+        data: [4, 5, 6],
+        dataType: DataType.FLOAT32,
+        timeRange: timeRange2,
+      });
+      const multiSeries = new MultiSeries([series1]);
+      multiSeries.push(series2);
+      expect(multiSeries.timeRange.start.valueOf()).toBe(1n);
+      expect(multiSeries.timeRange.end.valueOf()).toBe(3n);
+    });
+
+    it("should throw an error when pushing a series with a different data type", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const series2 = new Series({ data: [4, 5, 6], dataType: DataType.INT64 });
+      const multiSeries = new MultiSeries([series1]);
+      expect(() => multiSeries.push(series2)).toThrow(
+        "cannot push a int64 series to a float32 multi-series",
+      );
+    });
+
+    it("should throw an error when pushing a multi-series with a different data type", () => {
+      const series1 = new Series({ data: [1, 2, 3], dataType: DataType.FLOAT32 });
+      const series2 = new Series({ data: [4, 5, 6], dataType: DataType.INT64 });
+      const multiSeries1 = new MultiSeries([series1]);
+      const multiSeries2 = new MultiSeries([series2]);
+      expect(() => multiSeries1.push(multiSeries2)).toThrow(
+        "cannot push a int64 series to a float32 multi-series",
+      );
+    });
+  });
 });