@synnaxlabs/x 0.52.5 → 0.53.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.52.5",
+  "version": "0.53.1",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/ts",
@@ -27,8 +27,8 @@
     "vite": "^7.3.1",
     "vitest": "^3.2.4",
     "@synnaxlabs/eslint-config": "^0.0.0",
-    "@synnaxlabs/tsconfig": "^0.0.0",
-    "@synnaxlabs/vite-plugin": "^0.0.0"
+    "@synnaxlabs/vite-plugin": "^0.0.0",
+    "@synnaxlabs/tsconfig": "^0.0.0"
   },
   "main": "dist/x.cjs",
   "module": "dist/x.js",

package/src/index.ts

@@ -23,6 +23,7 @@ export * from "@/destructor";
 export * from "@/errors";
 export * from "@/id";
 export * from "@/instance";
+export * from "@/json";
 export * from "@/kv";
 export * from "@/label";
 export * from "@/link";

package/src/json/index.ts

@@ -0,0 +1,10 @@
+// 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.
+
+export * as json from "@/json/json";

package/src/json/json.spec.ts

@@ -0,0 +1,96 @@
+// 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 { json } from "@/json";
+
+describe("json", () => {
+  describe("pointerZ", () => {
+    it("should accept an empty string", () => {
+      expect(json.pointerZ.parse("")).toBe("");
+    });
+
+    it("should accept a simple pointer", () => {
+      expect(json.pointerZ.parse("/foo")).toBe("/foo");
+    });
+
+    it("should accept a nested pointer", () => {
+      expect(json.pointerZ.parse("/foo/bar/baz")).toBe("/foo/bar/baz");
+    });
+
+    it("should accept a pointer with array indices", () => {
+      expect(json.pointerZ.parse("/items/0/name")).toBe("/items/0/name");
+    });
+
+    it("should accept a pointer with escaped tilde", () => {
+      expect(json.pointerZ.parse("/a~0b")).toBe("/a~0b");
+    });
+
+    it("should accept a pointer with escaped slash", () => {
+      expect(json.pointerZ.parse("/a~1b")).toBe("/a~1b");
+    });
+
+    it("should reject a pointer that does not start with /", () => {
+      expect(json.pointerZ.safeParse("foo").success).toBe(false);
+    });
+
+    it("should reject a pointer with a bare tilde", () => {
+      expect(json.pointerZ.safeParse("/a~b").success).toBe(false);
+    });
+  });
+
+  describe("primitiveZ", () => {
+    it("should accept a string", () => {
+      expect(json.primitiveZ.parse("hello")).toBe("hello");
+    });
+
+    it("should accept a number", () => {
+      expect(json.primitiveZ.parse(42)).toBe(42);
+    });
+
+    it("should accept a boolean", () => {
+      expect(json.primitiveZ.parse(true)).toBe(true);
+    });
+
+    it("should accept null", () => {
+      expect(json.primitiveZ.parse(null)).toBeNull();
+    });
+
+    it("should reject an object", () => {
+      expect(json.primitiveZ.safeParse({}).success).toBe(false);
+    });
+
+    it("should reject an array", () => {
+      expect(json.primitiveZ.safeParse([]).success).toBe(false);
+    });
+  });
+
+  describe("primitiveTypeZ", () => {
+    it("should accept 'string'", () => {
+      expect(json.primitiveTypeZ.parse("string")).toBe("string");
+    });
+
+    it("should accept 'number'", () => {
+      expect(json.primitiveTypeZ.parse("number")).toBe("number");
+    });
+
+    it("should accept 'boolean'", () => {
+      expect(json.primitiveTypeZ.parse("boolean")).toBe("boolean");
+    });
+
+    it("should accept 'null'", () => {
+      expect(json.primitiveTypeZ.parse("null")).toBe("null");
+    });
+
+    it("should reject an invalid type name", () => {
+      expect(json.primitiveTypeZ.safeParse("object").success).toBe(false);
+    });
+  });
+});

package/src/json/json.ts

@@ -0,0 +1,32 @@
+// 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 { z } from "zod";
+
+/** Validates an RFC 6901 JSON Pointer string (e.g. "/foo/bar/0"). */
+export const pointerZ = z
+  .string()
+  .regex(/^(?:$|(?:\/(?:[^~/]|~0|~1)*)+)$/, "must be a valid JSON pointer (RFC 6901)");
+
+/** A JSON primitive value: string, number, boolean, or null. */
+export const primitiveZ = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+
+export type Primitive = z.infer<typeof primitiveZ>;
+
+/** The type name of a JSON primitive: "string", "number", "boolean", or "null". */
+export const primitiveTypeZ = z.enum(["string", "number", "boolean", "null"]);
+
+export type PrimitiveType = z.infer<typeof primitiveTypeZ>;
+
+export const ZERO_PRIMITIVES = {
+  string: "",
+  number: 0,
+  boolean: false,
+  null: null,
+} as const satisfies Record<PrimitiveType, Primitive>;

package/src/telem/series.ts

@@ -330,7 +330,7 @@ export class Series<T extends TelemValue = TelemValue>
       if (typeof first === "string") this.dataType = DataType.STRING;
       else if (typeof first === "number") this.dataType = DataType.FLOAT64;
       else if (typeof first === "bigint") this.dataType = DataType.INT64;
-      else if (typeof first === "boolean") this.dataType = DataType.BOOLEAN;
+      else if (typeof first === "boolean") this.dataType = DataType.UINT8;
       else if (
         first instanceof TimeStamp ||
         first instanceof Date ||

package/src/telem/telem.spec.ts

@@ -144,6 +144,26 @@ describe("TimeStamp", () => {
 
       expect(ts1.valueOf()).toEqual(ts2.valueOf());
     });
+
+    test("should round-trip across DST boundaries", () => {
+      // 2025-03-09 is US DST spring-forward, 2025-11-02 is US DST fall-back. These
+      // dates may have a different UTC offset than the current date, so we verify the
+      // round-trip works regardless of DST transitions.
+      const dstDates = [
+        "2025-03-09T12:00:00.000",
+        "2025-03-10T12:00:00.000",
+        "2025-11-02T12:00:00.000",
+        "2025-11-03T12:00:00.000",
+        "2025-06-15T12:00:00.000",
+        "2025-01-15T12:00:00.000",
+      ];
+      for (const input of dstDates) {
+        const ts1 = new TimeStamp(input, "local");
+        const output = ts1.toString("ISO", "local").slice(0, -1);
+        const ts2 = new TimeStamp(output, "local");
+        expect(ts1.valueOf()).toEqual(ts2.valueOf());
+      }
+    });
   });
 
   test("construct from date", () => {
@@ -1832,6 +1852,9 @@ describe("DataType", () => {
     it("should return false if the data type does not have a variable length", () => {
       expect(DataType.STRING.isVariable).toBe(true);
     });
+    it("should return true for BYTES", () => {
+      expect(DataType.BYTES.isVariable).toBe(true);
+    });
   });
 
   describe("construct", () => {
@@ -1877,7 +1900,6 @@ describe("DataType", () => {
       [DataType.INT32, DataType.FLOAT32, false],
       [DataType.INT32, DataType.FLOAT64, true],
       [DataType.INT32, DataType.STRING, false],
-      [DataType.INT32, DataType.BOOLEAN, false],
       [DataType.INT32, DataType.INT8, false],
       [DataType.INT64, DataType.INT32, false],
       [DataType.INT64, DataType.INT64, true],
@@ -1887,22 +1909,19 @@ describe("DataType", () => {
       [DataType.FLOAT64, DataType.FLOAT32, false],
       [DataType.FLOAT64, DataType.FLOAT64, true],
       [DataType.FLOAT64, DataType.STRING, false],
-      [DataType.FLOAT64, DataType.BOOLEAN, false],
       [DataType.FLOAT32, DataType.FLOAT64, true],
       [DataType.FLOAT32, DataType.FLOAT32, true],
       [DataType.FLOAT32, DataType.STRING, false],
-      [DataType.FLOAT32, DataType.BOOLEAN, false],
       [DataType.STRING, DataType.STRING, true],
       [DataType.STRING, DataType.INT32, false],
       [DataType.STRING, DataType.INT64, false],
       [DataType.STRING, DataType.FLOAT32, false],
       [DataType.STRING, DataType.FLOAT64, false],
-      [DataType.STRING, DataType.BOOLEAN, false],
       [DataType.STRING, DataType.INT8, false],
-      [DataType.BOOLEAN, DataType.BOOLEAN, true],
-      [DataType.BOOLEAN, DataType.INT32, false],
-      [DataType.BOOLEAN, DataType.INT64, false],
       [DataType.INT8, DataType.FLOAT32, true],
+      [DataType.BYTES, DataType.BYTES, true],
+      [DataType.BYTES, DataType.INT32, false],
+      [DataType.BYTES, DataType.STRING, false],
     ];
     TESTS.forEach(([from, to, expected]) =>
       it(`should return ${expected} when casting from ${from.toString()} to ${to.toString()}`, () => {
@@ -1923,7 +1942,7 @@ describe("DataType", () => {
         for (const to of numericTypes) expect(from.canCastTo(to)).toBe(true);
     });
     it("should return true for non-numeric data types ONLY if they are equal", () => {
-      const nonNumericTypes = [DataType.STRING, DataType.BOOLEAN];
+      const nonNumericTypes = [DataType.STRING, DataType.BYTES];
       for (const from of nonNumericTypes)
         for (const to of nonNumericTypes) expect(from.canCastTo(to)).toBe(from === to);
     });
@@ -1969,10 +1988,10 @@ describe("DataType", () => {
       { input: "float32", expected: "float32", short: "f32" },
       { input: "float64", expected: "float64", short: "f64" },
       { input: "string", expected: "string", short: "str" },
-      { input: "boolean", expected: "boolean", short: "bool" },
       { input: "timestamp", expected: "timestamp", short: "ts" },
       { input: "uuid", expected: "uuid", short: "uuid" },
       { input: "json", expected: "json", short: "json" },
+      { input: "bytes", expected: "bytes", short: "bytes" },
     ];
 
     testCases.forEach(({ input, expected, short }) => {

package/src/telem/telem.ts

@@ -192,7 +192,11 @@ export class TimeStamp
 
   private toISOString(tzInfo: TZInfo = "UTC"): string {
     if (tzInfo === "UTC") return this.date().toISOString();
-    return this.sub(TimeStamp.utcOffset).date().toISOString();
+    const d = this.date();
+    const offset = new TimeSpan(
+      BigInt(d.getTimezoneOffset()) * TimeStamp.MINUTE.valueOf(),
+    );
+    return this.sub(offset).date().toISOString();
   }
 
   private timeString(milliseconds: boolean = false, tzInfo: TZInfo = "UTC"): string {
@@ -1852,7 +1856,11 @@ export class DataType
    * @example DataType.INT32.isVariable // false
    */
   get isVariable(): boolean {
-    return this.equals(DataType.JSON) || this.equals(DataType.STRING);
+    return (
+      this.equals(DataType.JSON) ||
+      this.equals(DataType.STRING) ||
+      this.equals(DataType.BYTES)
+    );
   }
 
   /**
@@ -1985,8 +1993,6 @@ export class DataType
   static readonly UINT16 = new DataType("uint16");
   /** Represents a 8-bit unsigned integer value. */
   static readonly UINT8 = new DataType("uint8");
-  /** Represents a boolean value. Stored as a 8-bit unsigned integer. */
-  static readonly BOOLEAN = new DataType("boolean");
   /** Represents a 64-bit unix epoch. */
   static readonly TIMESTAMP = new DataType("timestamp");
   /** Represents a UUID data type. */
@@ -1997,6 +2003,9 @@ export class DataType
   /** Represents a JSON data type. JSON has an unknown density, and is separated by a
    * newline character. */
   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. */
+  static readonly BYTES = new DataType("bytes");
 
   private static readonly ARRAY_CONSTRUCTORS: Map<string, TypedArrayConstructor> =
     new Map<string, TypedArrayConstructor>([
@@ -2014,6 +2023,7 @@ export class DataType
       [DataType.STRING.toString(), Uint8Array],
       [DataType.JSON.toString(), Uint8Array],
       [DataType.UUID.toString(), Uint8Array],
+      [DataType.BYTES.toString(), Uint8Array],
     ]);
 
   private static readonly ARRAY_CONSTRUCTOR_DATA_TYPES: Map<string, DataType> = new Map<
@@ -2047,25 +2057,27 @@ export class DataType
     [DataType.STRING.toString(), Density.UNKNOWN],
     [DataType.JSON.toString(), Density.UNKNOWN],
     [DataType.UUID.toString(), Density.BIT128],
+    [DataType.BYTES.toString(), Density.UNKNOWN],
   ]);
 
   /** 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.UINT16,
+    DataType.UINT32,
+    DataType.UINT64,
+    DataType.INT8,
+    DataType.INT16,
+    DataType.INT32,
+    DataType.INT64,
+    DataType.FLOAT32,
+    DataType.FLOAT64,
     DataType.TIMESTAMP,
     DataType.UUID,
     DataType.STRING,
     DataType.JSON,
+    DataType.BYTES,
   ];
 
   private static readonly SHORT_STRINGS = new Map<string, string>([
@@ -2079,11 +2091,11 @@ export class DataType
     [DataType.INT64.toString(), "i64"],
     [DataType.FLOAT32.toString(), "f32"],
     [DataType.FLOAT64.toString(), "f64"],
-    [DataType.BOOLEAN.toString(), "bool"],
     [DataType.TIMESTAMP.toString(), "ts"],
     [DataType.UUID.toString(), "uuid"],
     [DataType.STRING.toString(), "str"],
     [DataType.JSON.toString(), "json"],
+    [DataType.BYTES.toString(), "bytes"],
   ]);
 
   static readonly BIG_INT_TYPES = [DataType.INT64, DataType.UINT64, DataType.TIMESTAMP];