@synnaxlabs/x 0.54.2 → 0.55.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.54.2",
+  "version": "0.55.0",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/ts",
@@ -14,21 +14,21 @@
   ],
   "dependencies": {
     "async-mutex": "^0.5.0",
-    "nanoid": "^5.1.7",
+    "nanoid": "^5.1.9",
     "uuid": "^13.0.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@types/node": "^25.5.0",
-    "@vitest/coverage-v8": "^4.1.2",
-    "eslint": "^10.1.0",
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "eslint": "^10.2.1",
     "madge": "^8.0.0",
-    "typescript": "^6.0.2",
-    "vite": "^8.0.3",
-    "vitest": "^4.1.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.8",
+    "vitest": "^4.1.4",
+    "@synnaxlabs/eslint-config": "^0.0.0",
     "@synnaxlabs/tsconfig": "^0.0.0",
-    "@synnaxlabs/vite-plugin": "^0.0.0",
-    "@synnaxlabs/eslint-config": "^0.0.0"
+    "@synnaxlabs/vite-plugin": "^0.0.0"
   },
   "main": "dist/x.cjs",
   "module": "dist/x.js",

package/src/strings/strings.spec.ts

@@ -103,3 +103,22 @@ describe("trimPrefix", () => {
   it("should handle numbers in prefix", () =>
     expect(strings.trimPrefix("123abc", "123")).toBe("abc"));
 });
+
+describe("escapeHTML", () => {
+  it("should escape ampersands", () =>
+    expect(strings.escapeHTML("a&b")).toBe("a&b"));
+
+  it("should escape angle brackets", () =>
+    expect(strings.escapeHTML("<div>")).toBe("&lt;div&gt;"));
+
+  it("should escape quotes", () =>
+    expect(strings.escapeHTML(`"it's"`)).toBe("&quot;it&#39;s&quot;"));
+
+  it("should return the original string when no special characters", () =>
+    expect(strings.escapeHTML("hello")).toBe("hello"));
+
+  it("should escape all special characters together", () =>
+    expect(strings.escapeHTML(`<a href="x">&`)).toBe(
+      "&lt;a href=&quot;x&quot;&gt;&amp;",
+    ));
+});

package/src/strings/strings.ts

@@ -108,3 +108,19 @@ export const trimPrefix = (str: string, prefix: string): string => {
   if (str.startsWith(prefix)) return str.slice(prefix.length);
   return str;
 };
+
+/**
+ * Escapes HTML special characters in a string to prevent XSS and ensure
+ * correct rendering in HTML contexts.
+ *
+ * @param s - The string to escape.
+ * @returns The escaped string with &, <, >, ", and ' replaced by their
+ * HTML entity equivalents.
+ */
+export const escapeHTML = (s: string): string =>
+  s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");

package/src/telem/clockSkew.spec.ts

@@ -0,0 +1,58 @@
+// Copyright 2026 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 { describe, expect, it } from "vitest";
+
+import { ClockSkewCalculator, TimeSpan, TimeStamp } from "@/telem";
+
+describe("ClockSkewCalculator", () => {
+  it("should correctly calculate clock skew from a single measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 3s, local midpoint is 5s, so skew is 2s
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(true);
+    expect(calc.exceeds(TimeSpan.seconds(3))).toBe(false);
+  });
+
+  it("should report zero skew when times match perfectly", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint matches local midpoint at 5s
+    calc.end(TimeStamp.seconds(5));
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+
+  it("should return the most recent measurement", () => {
+    let mockTime = TimeStamp.seconds(0);
+    const calc = new ClockSkewCalculator(() => mockTime);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    calc.end(TimeStamp.seconds(3));
+    expect(calc.skew).toEqual(TimeSpan.seconds(2));
+    mockTime = TimeStamp.seconds(0);
+    calc.start();
+    mockTime = TimeStamp.seconds(10);
+    // Remote midpoint is 7s, local midpoint is 5s, so skew is -2s
+    calc.end(TimeStamp.seconds(7));
+    expect(calc.skew).toEqual(TimeSpan.seconds(-2));
+  });
+
+  it("should return zero skew when no measurements taken", () => {
+    const calc = new ClockSkewCalculator();
+    expect(calc.skew).toEqual(TimeSpan.ZERO);
+    expect(calc.exceeds(TimeSpan.seconds(1))).toBe(false);
+  });
+});

package/src/telem/clockSkew.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 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 CrudeTimeSpan, TimeSpan, TimeStamp } from "@/telem/telem";
+
+/**
+ * Calculates and tracks clock skew between two systems using a midpoint
+ * synchronization algorithm. Useful for distributed systems where clock
+ * synchronization is critical.
+ */
+export class ClockSkewCalculator {
+  private readonly now: () => TimeStamp;
+  private localStartT: TimeStamp = new TimeStamp(0);
+  private lastSkew: TimeSpan = TimeSpan.ZERO;
+
+  constructor(now: () => TimeStamp = () => TimeStamp.now()) {
+    this.now = now;
+  }
+
+  start(): void {
+    this.localStartT = this.now();
+  }
+
+  end(remoteMidpointT: TimeStamp): void {
+    const localEndT = this.now();
+    const halfSpan = localEndT.span(this.localStartT).valueOf() / 2n;
+    const thisMidpointT = this.localStartT.add(halfSpan);
+    this.lastSkew = new TimeSpan(thisMidpointT.valueOf() - remoteMidpointT.valueOf());
+  }
+
+  get skew(): TimeSpan {
+    return this.lastSkew;
+  }
+
+  exceeds(threshold: CrudeTimeSpan): boolean {
+    const skewVal = this.skew.valueOf();
+    const abs = skewVal < 0n ? -skewVal : skewVal;
+    return abs > new TimeSpan(threshold).valueOf();
+  }
+}

package/src/telem/external.ts

@@ -7,6 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/telem/clockSkew";
 export { type GLBufferController } from "@/telem/gl";
 export * from "@/telem/series";
 export * from "@/telem/telem";

package/src/telem/series.spec.ts

@@ -141,7 +141,7 @@ describe("Series", () => {
       const s = new Series({ data: [{ a: 1, b: "apple" }] });
       expect(s.dataType.equals(DataType.JSON));
       expect(s.length).toEqual(1);
-      expect(s.data.at(-1)).toEqual(10);
+      expect(s.at(0)).toEqual({ a: 1, b: "apple" });
     });
 
     it("should correctly interpret a bigint as an int64", () => {
@@ -214,8 +214,8 @@ describe("Series", () => {
 
     it("should convert encoded keys to snake_case", () => {
       const a = new Series({ data: [{ aB: 1, bC: "apple" }], dataType: DataType.JSON });
-      const strContent = new TextDecoder().decode(a.data);
-      expect(strContent).toBe('{"a_b":1,"b_c":"apple"}\n');
+      expect(a.length).toEqual(1);
+      expect(a.at(0)).toEqual({ aB: 1, bC: "apple" });
     });
 
     it("should throw an error when an empty JS array is provided and no data type is provided", () => {
@@ -502,7 +502,7 @@ describe("Series", () => {
     });
 
     it("should recompute the length of a variable density array", () => {
-      const series = Series.alloc({ capacity: 12, dataType: DataType.STRING });
+      const series = Series.alloc({ capacity: 18, dataType: DataType.STRING });
       expect(series.length).toEqual(0);
       const writeOne = new Series({ data: ["apple"] });
       expect(series.write(writeOne)).toEqual(1);
@@ -689,6 +689,54 @@ describe("Series", () => {
         { a: 3, b: "carrot" },
       ]);
     });
+
+    it("should handle a single JSON value", () => {
+      const s = new Series([{ key: "val" }]);
+      expect(s.length).toEqual(1);
+      expect(s.at(0)).toEqual({ key: "val" });
+    });
+
+    it("should handle empty JSON objects", () => {
+      const s = new Series([{}, {}, {}]);
+      expect(s.length).toEqual(3);
+      expect(s.at(0)).toEqual({});
+      expect(s.at(2)).toEqual({});
+    });
+
+    it("should support negative indexing", () => {
+      const s = new Series([{ a: 1 }, { a: 2 }, { a: 3 }]);
+      expect(s.at(-1)).toEqual({ a: 3 });
+      expect(s.at(-2)).toEqual({ a: 2 });
+    });
+
+    it("should handle an empty JSON series", () => {
+      const s = new Series({ data: new ArrayBuffer(0), dataType: DataType.JSON });
+      expect(s.length).toEqual(0);
+      expect(Array.from(s)).toEqual([]);
+    });
+  });
+
+  describe("bytes series", () => {
+    it("should handle an empty bytes series", () => {
+      const s = new Series({ data: new ArrayBuffer(0), dataType: DataType.BYTES });
+      expect(s.length).toEqual(0);
+      expect(Array.from(s)).toEqual([]);
+    });
+
+    it("should correctly compute the length of a bytes series from a length-prefixed buffer", () => {
+      const payload1 = new Uint8Array([1, 2, 3]);
+      const payload2 = new Uint8Array([4, 5]);
+      const totalBytes = 4 + payload1.byteLength + 4 + payload2.byteLength;
+      const buf = new ArrayBuffer(totalBytes);
+      const view = new DataView(buf);
+      const bytes = new Uint8Array(buf);
+      view.setUint32(0, payload1.byteLength, true);
+      bytes.set(payload1, 4);
+      view.setUint32(4 + payload1.byteLength, payload2.byteLength, true);
+      bytes.set(payload2, 4 + payload1.byteLength + 4);
+      const s = new Series({ data: buf, dataType: DataType.BYTES });
+      expect(s.length).toEqual(2);
+    });
   });
 
   describe("binarySearch", () => {

package/src/telem/series.ts

@@ -114,7 +114,7 @@ const nullArrayZ = z
   .union([z.null(), z.undefined()])
   .transform(() => new Uint8Array().buffer);
 
-const NEW_LINE = 10;
+const UINT32_SIZE = 4;
 
 type JSType = "string" | "number" | "bigint";
 
@@ -358,12 +358,42 @@ export class Series<T extends TelemValue = TelemValue>
         data_ = data_.map((v) => new TimeStamp(v as CrudeTimeStamp).valueOf());
       if (this.dataType.equals(DataType.STRING)) {
         this.cachedLength = data_.length;
-        this._data = new TextEncoder().encode(`${data_.join("\n")}\n`).buffer;
+        const encoded = (data_ as string[]).map((s) => new TextEncoder().encode(s));
+        const totalBytes = encoded.reduce(
+          (acc, e) => acc + UINT32_SIZE + e.byteLength,
+          0,
+        );
+        const buf = new ArrayBuffer(totalBytes);
+        const view = new DataView(buf);
+        const bytes = new Uint8Array(buf);
+        let offset = 0;
+        for (const e of encoded) {
+          view.setUint32(offset, e.byteLength, true);
+          offset += UINT32_SIZE;
+          bytes.set(e, offset);
+          offset += e.byteLength;
+        }
+        this._data = buf;
       } else if (this.dataType.equals(DataType.JSON)) {
         this.cachedLength = data_.length;
-        this._data = new TextEncoder().encode(
-          `${data_.map((d) => binary.JSON_CODEC.encodeString(d)).join("\n")}\n`,
-        ).buffer;
+        const encoded = data_.map((d) =>
+          new TextEncoder().encode(binary.JSON_CODEC.encodeString(d)),
+        );
+        const totalBytes = encoded.reduce(
+          (acc, e) => acc + UINT32_SIZE + e.byteLength,
+          0,
+        );
+        const buf = new ArrayBuffer(totalBytes);
+        const view = new DataView(buf);
+        const bytes = new Uint8Array(buf);
+        let offset = 0;
+        for (const e of encoded) {
+          view.setUint32(offset, e.byteLength, true);
+          offset += UINT32_SIZE;
+          bytes.set(e, offset);
+          offset += e.byteLength;
+        }
+        this._data = buf;
       } else if (this.dataType.usesBigInt && typeof first === "number")
         this._data = new this.dataType.Array(
           data_.map((v) => BigInt(Math.round(v as number))),
@@ -456,14 +486,25 @@ export class Series<T extends TelemValue = TelemValue>
   private writeVariable(other: Series): number {
     if (this.writePos === FULL_BUFFER) return 0;
     const available = this.byteCapacity.valueOf() - this.writePos;
-    const toWrite = other.subBytes(0, available);
-    this.writeToUnderlyingData(toWrite);
-    this.writePos += toWrite.byteLength.valueOf();
-    if (this.cachedLength != null) {
-      this.cachedLength += toWrite.length;
-      this.calculateCachedLength();
+    const otherBuf = other.buffer;
+    const otherByteLen = other.byteLength.valueOf();
+    const view = new DataView(otherBuf);
+    let offset = 0;
+    let samplesWritten = 0;
+    while (offset + UINT32_SIZE <= otherByteLen) {
+      const sampleLen = view.getUint32(offset, true);
+      const recordSize = UINT32_SIZE + sampleLen;
+      if (offset + recordSize > available) break;
+      offset += recordSize;
+      samplesWritten++;
     }
-    return toWrite.length;
+    if (offset === 0) return 0;
+    const toWrite = other.subBytes(0, offset);
+    this.writeToUnderlyingData(toWrite);
+    this.writePos += offset;
+    this.cachedLength = (this.cachedLength ?? 0) + samplesWritten;
+    this._cachedIndexes = undefined;
+    return samplesWritten;
   }
 
   private writeFixed(other: Series): number {
@@ -511,8 +552,21 @@ export class Series<T extends TelemValue = TelemValue>
    * @returns An array of string representations of the series values.
    */
   toStrings(): string[] {
-    if (this.dataType.isVariable)
-      return new TextDecoder().decode(this.underlyingData).split("\n").slice(0, -1);
+    if (this.dataType.isVariable) {
+      const result: string[] = [];
+      const buf = this.buffer;
+      const byteLen = this.byteLength.valueOf();
+      const view = new DataView(buf);
+      const decoder = new TextDecoder();
+      let offset = 0;
+      while (offset + UINT32_SIZE <= byteLen) {
+        const len = view.getUint32(offset, true);
+        offset += UINT32_SIZE;
+        result.push(decoder.decode(new Uint8Array(buf, offset, len)));
+        offset += len;
+      }
+      return result;
+    }
     return Array.from(this).map((d) => d.toString());
   }
 
@@ -560,7 +614,7 @@ export class Series<T extends TelemValue = TelemValue>
 
   /**
    * Returns the number of samples in this array.
-   * For variable length data types, this is calculated by counting newlines.
+   * For variable length data types, this is calculated by scanning uint32 length prefixes.
    * @returns The number of samples in the series.
    */
   get length(): number {
@@ -575,12 +629,18 @@ export class Series<T extends TelemValue = TelemValue>
     if (!this.dataType.isVariable)
       throw new Error("cannot calculate length of a non-variable length data type");
     let cl = 0;
-    const ci: number[] = [0];
-    this.data.forEach((v, i) => {
-      if (v !== NEW_LINE) return;
+    const ci: number[] = [];
+    const buf = this.buffer;
+    const byteLen = this.byteLength.valueOf();
+    const view = new DataView(buf);
+    let offset = 0;
+    while (offset + UINT32_SIZE <= byteLen) {
+      const len = view.getUint32(offset, true);
+      offset += UINT32_SIZE;
+      ci.push(offset);
+      offset += len;
       cl++;
-      ci.push(i + 1);
-    });
+    }
     this._cachedIndexes = ci;
     this.cachedLength = cl;
     return cl;
@@ -742,28 +802,40 @@ export class Series<T extends TelemValue = TelemValue>
 
   private atVariable(index: number, required: boolean): T | undefined {
     let start = 0;
-    let end = 0;
+    let len = 0;
+    const buf = this.buffer;
+    const view = new DataView(buf);
     if (this._cachedIndexes != null) {
+      if (index < 0) index = this._cachedIndexes.length + index;
+      if (index < 0 || index >= this._cachedIndexes.length) {
+        if (required) throw new Error(`[series] - no value at index ${index}`);
+        return undefined;
+      }
       start = this._cachedIndexes[index];
-      end = this._cachedIndexes[index + 1] - 1;
+      len = view.getUint32(start - UINT32_SIZE, true);
     } else {
       if (index < 0) index = this.length + index;
-      for (let i = 0; i < this.data.length; i++)
-        if (this.data[i] === NEW_LINE) {
-          if (index === 0) {
-            end = i;
-            break;
-          }
-          start = i + 1;
-          index--;
+      const byteLen = this.byteLength.valueOf();
+      let offset = 0;
+      let found = false;
+      while (offset + UINT32_SIZE <= byteLen) {
+        const sampleLen = view.getUint32(offset, true);
+        offset += UINT32_SIZE;
+        if (index === 0) {
+          start = offset;
+          len = sampleLen;
+          found = true;
+          break;
         }
-      if (end === 0) end = this.data.length;
-      if (start >= end || index > 0) {
+        offset += sampleLen;
+        index--;
+      }
+      if (!found) {
         if (required) throw new Error(`[series] - no value at index ${index}`);
         return undefined;
       }
     }
-    const slice = this.data.slice(start, end);
+    const slice = new Uint8Array(buf, start, len);
     if (this.dataType.equals(DataType.STRING))
       return new TextDecoder().decode(slice) as T;
     return caseconv.snakeToCamel(JSON.parse(new TextDecoder().decode(slice))) as T;
@@ -1069,8 +1141,9 @@ class SubIterator<T> implements Iterator<T> {
 
 class StringSeriesIterator implements Iterator<string> {
   private readonly series: Series;
-  private index: number;
+  private byteOffset: number;
   private readonly decoder: TextDecoder;
+  private readonly view: DataView;
 
   constructor(series: Series) {
     if (!series.dataType.isVariable)
@@ -1078,18 +1151,21 @@ class StringSeriesIterator implements Iterator<string> {
         "cannot create a variable series iterator for a non-variable series",
       );
     this.series = series;
-    this.index = 0;
+    this.byteOffset = 0;
     this.decoder = new TextDecoder();
+    this.view = new DataView(series.buffer);
   }
 
   next(): IteratorResult<string> {
-    const start = this.index;
-    const data = this.series.data;
-    while (this.index < data.length && data[this.index] !== NEW_LINE) this.index++;
-    const end = this.index;
-    if (start === end) return { done: true, value: undefined };
-    this.index++;
-    const s = this.decoder.decode(this.series.buffer.slice(start, end));
+    const byteLen = this.series.byteLength.valueOf();
+    if (this.byteOffset + UINT32_SIZE > byteLen)
+      return { done: true, value: undefined };
+    const len = this.view.getUint32(this.byteOffset, true);
+    this.byteOffset += UINT32_SIZE;
+    const s = this.decoder.decode(
+      new Uint8Array(this.series.buffer, this.byteOffset, len),
+    );
+    this.byteOffset += len;
     return { done: false, value: s };
   }
 }

package/src/telem/telem.spec.ts

@@ -1057,6 +1057,25 @@ describe("TimeSpan", () => {
       expect(result.valueOf()).toBe(700n);
     });
 
+    test("abs of positive value", () => {
+      const ts = new TimeSpan(1000);
+      expect(ts.abs().valueOf()).toBe(1000n);
+    });
+
+    test("abs of negative value", () => {
+      const ts = new TimeSpan(-500);
+      expect(ts.abs().valueOf()).toBe(500n);
+    });
+
+    test("abs of zero", () => {
+      expect(TimeSpan.ZERO.abs().valueOf()).toBe(0n);
+    });
+
+    test("abs returns TimeSpan instance", () => {
+      const ts = new TimeSpan(-1000);
+      expect(ts.abs()).toBeInstanceOf(TimeSpan);
+    });
+
     test("mult", () => {
       const ts = new TimeSpan(1000);
       const result = ts.mult(2);

package/src/telem/telem.ts

@@ -1190,6 +1190,11 @@ export class TimeSpan
     return new TimeSpan(this.valueOf() - new TimeSpan(other).valueOf());
   }
 
+  abs(): TimeSpan {
+    const v = this.valueOf();
+    return new TimeSpan(v < 0n ? -v : v);
+  }
+
   /**
    * Creates a TimeSpan representing the given number of nanoseconds.
    *
@@ -2014,14 +2019,14 @@ export class DataType
   static readonly TIMESTAMP = new DataType("timestamp");
   /** Represents a UUID data type. */
   static readonly UUID = new DataType("uuid");
-  /** Represents a string data type. Strings have an unknown density, and are separate
-   * by a newline character. */
+  /** Represents a string data type. Strings have an unknown density and are encoded
+   * as uint32-length-prefixed samples. */
   static readonly STRING = new DataType("string");
-  /** Represents a JSON data type. JSON has an unknown density, and is separated by a
-   * newline character. */
+  /** Represents a JSON data type. JSON has an unknown density and is encoded as
+   * uint32-length-prefixed samples. */
   static readonly JSON = new DataType("json");
   /** Represents a bytes data type for arbitrary byte arrays. Bytes have an unknown
-   * density, and are separated by a newline character. */
+   * density and are encoded as uint32-length-prefixed samples. */
   static readonly BYTES = new DataType("bytes");
 
   private static readonly ARRAY_CONSTRUCTORS: Map<string, TypedArrayConstructor> =