@synnaxlabs/x 0.43.0 → 0.44.1

package/src/telem/telem.ts

@@ -7,7 +7,7 @@
 // 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/v4";
+import { z } from "zod";
 
 import { math } from "@/math";
 import { primitive } from "@/primitive";
@@ -28,6 +28,12 @@ export type TimeStampStringFormat =
   | "shortDate"
   | "dateTime";
 
+const dateComponentsZ = z.union([
+  z.tuple([z.int()]),
+  z.tuple([z.int(), z.int().min(1).max(12)]),
+  z.tuple([z.int(), z.int().min(1).max(12), z.int().min(1).max(31)]),
+]);
+
 /**
  * A triple of numbers representing a date.
  *
@@ -35,7 +41,7 @@ export type TimeStampStringFormat =
  * @param month - The month.
  * @param day - The day.
  */
-export type DateComponents = [number?, number?, number?];
+export type DateComponents = z.infer<typeof dateComponentsZ>;
 
 const remainder = <T extends TimeStamp | TimeSpan>(
   value: T,
@@ -93,7 +99,7 @@ export class TimeStamp
       super(TimeStamp.parseDateTimeString(value, tzInfo).valueOf());
     else if (Array.isArray(value)) super(TimeStamp.parseDate(value));
     else {
-      let offset: bigint = BigInt(0);
+      let offset = 0n;
       if (value instanceof Number) value = value.valueOf();
       if (tzInfo === "local") offset = TimeStamp.utcOffset.valueOf();
       if (typeof value === "number")
@@ -265,7 +271,7 @@ export class TimeStamp
    * @returns True if the TimeStamp represents the unix epoch, false otherwise.
    */
   get isZero(): boolean {
-    return this.valueOf() === BigInt(0);
+    return this.valueOf() === 0n;
   }
 
   /**
@@ -644,12 +650,27 @@ export class TimeStamp
 
   /** A zod schema for validating timestamps */
   static readonly z = z.union([
+    z.instanceof(TimeStamp),
     z.object({ value: z.bigint() }).transform((v) => new TimeStamp(v.value)),
     z.string().transform((n) => new TimeStamp(BigInt(n))),
-    z.instanceof(Number).transform((n) => new TimeStamp(n)),
     z.number().transform((n) => new TimeStamp(n)),
-    z.instanceof(TimeStamp),
+    z.bigint().transform((n) => new TimeStamp(n)),
+    z.date().transform((d) => new TimeStamp(d)),
+    z.custom<TimeSpan>((v) => v instanceof TimeSpan).transform((v) => new TimeStamp(v)),
+    dateComponentsZ.transform((v) => new TimeStamp(v)),
   ]);
+
+  /**
+   * Sorts two timestamps.
+   *
+   * @param a - The first timestamp.
+   * @param b - The second timestamp.
+   * @returns A number indicating the order of the two timestamps (positive if a is
+   * greater than b, negative if a is less than b, and 0 if they are equal).
+   */
+  static sort(a: TimeStamp, b: TimeStamp): number {
+    return Number(a.valueOf() - b.valueOf());
+  }
 }
 
 /** TimeSpan represents a nanosecond precision duration. */
@@ -843,7 +864,7 @@ export class TimeSpan
    * @returns True if the TimeSpan represents a zero duration, false otherwise.
    */
   get isZero(): boolean {
-    return this.valueOf() === BigInt(0);
+    return this.valueOf() === 0n;
   }
 
   /**
@@ -977,7 +998,6 @@ export class TimeSpan
   static readonly z = z.union([
     z.object({ value: z.bigint() }).transform((v) => new TimeSpan(v.value)),
     z.string().transform((n) => new TimeSpan(BigInt(n))),
-    z.instanceof(Number).transform((n) => new TimeSpan(n)),
     z.number().transform((n) => new TimeSpan(n)),
     z.instanceof(TimeSpan),
   ]);
@@ -1076,7 +1096,6 @@ export class Rate
   /** A zod schema for validating and transforming rates */
   static readonly z = z.union([
     z.number().transform((n) => new Rate(n)),
-    z.instanceof(Number).transform((n) => new Rate(n)),
     z.instanceof(Rate),
   ]);
 }
@@ -1133,7 +1152,6 @@ export class Density
   /** A zod schema for validating and transforming densities */
   static readonly z = z.union([
     z.number().transform((n) => new Density(n)),
-    z.instanceof(Number).transform((n) => new Density(n)),
     z.instanceof(Density),
   ]);
 }
@@ -1374,15 +1392,22 @@ export class TimeRange implements primitive.Stringer {
       .transform((v) => new TimeRange(v.start, v.end)),
     z.instanceof(TimeRange),
   ]);
-}
 
-export const sortTimeRange = (a: TimeRange, b: TimeRange): -1 | 0 | 1 => {
-  if (a.start.before(b.start)) return -1;
-  if (a.start.after(b.start)) return 1;
-  if (a.end.before(b.end)) return -1;
-  if (a.end.after(b.end)) return 1;
-  return 0;
-};
+  /**
+   * Sorts two time ranges. The range with the earlier start time is considered less than
+   * the range with the later start time. If the start times are equal, the range with the
+   * earlier end time is considered less than the range with the later end time.
+   *
+   * @param a - The first time range.
+   * @param b - The second time range.
+   * @returns A number indicating the order of the two time ranges. This number is
+   * positive if a is earlier than b, negative if a is later than b, and 0 if they are
+   * equal.
+   */
+  static sort(a: TimeRange, b: TimeRange): number {
+    return TimeStamp.sort(a.start, b.start) || TimeStamp.sort(a.end, b.end);
+  }
+}
 
 /** DataType is a string that represents a data type. */
 export class DataType
@@ -1664,7 +1689,9 @@ export class DataType
   ]);
 }
 
-/** The size of an element in bytes. */
+/**
+ * The Size of an element in bytes.
+ */
 export class Size
   extends primitive.ValueExtension<number>
   implements primitive.Stringer
@@ -1826,31 +1853,22 @@ export class Size
 
 export type CrudeTimeStamp =
   | bigint
-  | BigInt
   | TimeStamp
   | TimeSpan
   | number
   | Date
   | string
-  | DateComponents
-  | Number;
+  | DateComponents;
 export type TimeStampT = number;
-export type CrudeTimeSpan =
-  | bigint
-  | BigInt
-  | TimeSpan
-  | TimeStamp
-  | number
-  | Number
-  | Rate;
+export type CrudeTimeSpan = bigint | TimeSpan | TimeStamp | number | Rate;
 export type TimeSpanT = number;
-export type CrudeRate = Rate | number | Number;
+export type CrudeRate = Rate | number;
 export type RateT = number;
-export type CrudeDensity = Density | number | Number;
+export type CrudeDensity = Density | number;
 export type DensityT = number;
 export type CrudeDataType = DataType | string | TypedArray;
 export type DataTypeT = string;
-export type CrudeSize = Size | number | Number;
+export type CrudeSize = Size | number;
 export type SizeT = number;
 export interface CrudeTimeRange {
   start: CrudeTimeStamp;
@@ -1919,11 +1937,11 @@ export const convertDataType = (
   target: DataType,
   value: math.Numeric,
   offset: math.Numeric = 0,
-): math.PrimitiveNumeric => {
+): math.Numeric => {
   if (source.usesBigInt && !target.usesBigInt) return Number(value) - Number(offset);
   if (!source.usesBigInt && target.usesBigInt)
     return BigInt(value.valueOf()) - BigInt(offset.valueOf());
-  return addSamples(value, -offset).valueOf();
+  return addSamples(value, -offset);
 };
 
 export const addSamples = (a: math.Numeric, b: math.Numeric): math.Numeric => {

package/src/testutil/testutil.spec.ts

@@ -0,0 +1,161 @@
+// Copyright 2025 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, vi } from "vitest";
+
+import { testutil } from "@/testutil";
+
+describe("testutil", () => {
+  describe("toString", () => {
+    it("should stringify regular values normally", () => {
+      expect(testutil.toString("hello")).toBe('"hello"');
+      expect(testutil.toString(123)).toBe("123");
+      expect(testutil.toString(true)).toBe("true");
+      expect(testutil.toString(null)).toBe("null");
+      expect(testutil.toString(undefined)).toBe(undefined);
+    });
+
+    it("should handle arrays", () => {
+      expect(testutil.toString([1, 2, 3])).toBe("[1,2,3]");
+      expect(testutil.toString(["a", "b", "c"])).toBe('["a","b","c"]');
+      expect(testutil.toString([])).toBe("[]");
+    });
+
+    it("should handle objects", () => {
+      expect(testutil.toString({ a: 1, b: 2 })).toBe('{"a":1,"b":2}');
+      expect(testutil.toString({ nested: { value: 42 } })).toBe(
+        '{"nested":{"value":42}}',
+      );
+      expect(testutil.toString({})).toBe("{}");
+    });
+
+    it("should convert bigint to string", () => {
+      const bigIntValue = BigInt(123456789012345678901234567890n);
+      expect(testutil.toString(bigIntValue)).toBe('"123456789012345678901234567890"');
+    });
+
+    it("should handle objects with bigint values", () => {
+      const obj = {
+        regular: 123,
+        big: BigInt(999999999999999999999n),
+        nested: {
+          value: BigInt(111111111111111111111n),
+        },
+      };
+      expect(testutil.toString(obj)).toBe(
+        '{"regular":123,"big":"999999999999999999999","nested":{"value":"111111111111111111111"}}',
+      );
+    });
+
+    it("should handle arrays with bigint values", () => {
+      const arr = [BigInt(1n), BigInt(2n), 3, BigInt(4n)];
+      expect(testutil.toString(arr)).toBe('["1","2",3,"4"]');
+    });
+
+    it("should handle mixed complex structures", () => {
+      const complex = {
+        id: BigInt(123n),
+        data: [1, BigInt(456n), { value: BigInt(789n) }],
+        metadata: {
+          count: 42,
+          total: BigInt(999999n),
+        },
+      };
+      expect(testutil.toString(complex)).toBe(
+        '{"id":"123","data":[1,"456",{"value":"789"}],"metadata":{"count":42,"total":"999999"}}',
+      );
+    });
+  });
+
+  describe("testutil.expectAlways", () => {
+    it("should call function multiple times over duration", async () => {
+      const fn = vi.fn();
+      await testutil.expectAlways(fn, 100, 20);
+      expect(fn).toHaveBeenCalledTimes(5);
+    });
+
+    it("should handle async functions", async () => {
+      let counter = 0;
+      const asyncFn = vi.fn(async () => {
+        counter++;
+        await new Promise((resolve) => setTimeout(resolve, 5));
+      });
+
+      await testutil.expectAlways(asyncFn, 60, 20);
+      expect(asyncFn).toHaveBeenCalled();
+      expect(counter).toBeGreaterThan(0);
+    });
+
+    it("should propagate errors from the function", async () => {
+      const errorFn = vi.fn(() => {
+        throw new Error("Test error");
+      });
+
+      await expect(testutil.expectAlways(errorFn, 50, 20)).rejects.toThrow(
+        "Test error",
+      );
+      expect(errorFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should propagate errors from async functions", async () => {
+      const asyncErrorFn = vi.fn(async () => {
+        throw new Error("Async test error");
+      });
+
+      await expect(testutil.expectAlways(asyncErrorFn, 50, 20)).rejects.toThrow(
+        "Async test error",
+      );
+      expect(asyncErrorFn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should use default values when not provided", async () => {
+      const fn = vi.fn();
+      await testutil.expectAlways(fn);
+      expect(fn.mock.calls.length).toBeGreaterThanOrEqual(10);
+    });
+
+    it("should respect custom interval", async () => {
+      const fn = vi.fn();
+      const start = Date.now();
+      await testutil.expectAlways(fn, 100, 30);
+      const elapsed = Date.now() - start;
+      expect(elapsed).toBeGreaterThanOrEqual(90);
+      expect(elapsed).toBeLessThan(150);
+      expect(fn).toHaveBeenCalledTimes(4);
+    });
+
+    it("should handle functions that pass after initial failures", async () => {
+      let callCount = 0;
+      const fn = vi.fn(() => {
+        callCount++;
+        if (callCount < 3) throw new Error("Not ready yet");
+      });
+
+      await expect(testutil.expectAlways(fn, 80, 20)).rejects.toThrow("Not ready yet");
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("should work with expectations inside the function", async () => {
+      let value = 0;
+      const incrementer = setInterval(() => value++, 10);
+
+      try {
+        await testutil.expectAlways(
+          () => {
+            expect(value).toBeGreaterThanOrEqual(0);
+          },
+          50,
+          10,
+        );
+      } finally {
+        clearInterval(incrementer);
+      }
+    });
+  });
+});

package/src/testutil/testutil.ts

@@ -12,3 +12,15 @@ export const toString = (value: unknown): string =>
     if (typeof value === "bigint") return value.toString();
     return value;
   });
+
+export const expectAlways = async (
+  fn: () => void | Promise<void>,
+  duration: number = 200,
+  interval: number = 20,
+) => {
+  const start = Date.now();
+  while (Date.now() - start < duration) {
+    await fn();
+    await new Promise((resolve) => setTimeout(resolve, interval));
+  }
+};

package/src/zod/external.ts

@@ -8,4 +8,5 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/zod/nullToUndefined";
+export * from "@/zod/toArray";
 export * from "@/zod/util";

package/src/zod/nullToUndefined.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it } from "vitest";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { zod } from "@/zod";
 

package/src/zod/nullToUndefined.ts

@@ -7,7 +7,7 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type z } from "zod/v4";
+import { type z } from "zod";
 
 export const nullToUndefined = <Input, Output>(
   schema: z.ZodType<Input, Output>,

package/src/zod/toArray.spec.ts

@@ -0,0 +1,182 @@
+// Copyright 2025 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 { z } from "zod";
+
+import { toArray } from "@/zod/toArray";
+
+describe("toArray", () => {
+  describe("with string schema", () => {
+    const schema = toArray(z.string());
+
+    it("should accept an array of strings", () => {
+      const result = schema.parse(["hello", "world"]);
+      expect(result).toEqual(["hello", "world"]);
+    });
+
+    it("should convert a single string to an array", () => {
+      const result = schema.parse("hello");
+      expect(result).toEqual(["hello"]);
+    });
+
+    it("should accept an empty array", () => {
+      const result = schema.parse([]);
+      expect(result).toEqual([]);
+    });
+
+    it("should throw for invalid types in array", () => {
+      expect(() => schema.parse([123, 456])).toThrow(z.ZodError);
+    });
+
+    it("should throw for invalid single value", () => {
+      expect(() => schema.parse(123)).toThrow(z.ZodError);
+    });
+  });
+
+  describe("with number schema", () => {
+    const schema = toArray(z.number());
+
+    it("should accept an array of numbers", () => {
+      const result = schema.parse([1, 2, 3]);
+      expect(result).toEqual([1, 2, 3]);
+    });
+
+    it("should convert a single number to an array", () => {
+      const result = schema.parse(42);
+      expect(result).toEqual([42]);
+    });
+
+    it("should handle zero", () => {
+      const result = schema.parse(0);
+      expect(result).toEqual([0]);
+    });
+
+    it("should handle negative numbers", () => {
+      const result = schema.parse(-5);
+      expect(result).toEqual([-5]);
+    });
+  });
+
+  describe("with object schema", () => {
+    const objSchema = z.object({
+      name: z.string(),
+      age: z.number(),
+    });
+    const schema = toArray(objSchema);
+
+    it("should accept an array of objects", () => {
+      const input = [
+        { name: "Alice", age: 30 },
+        { name: "Bob", age: 25 },
+      ];
+      const result = schema.parse(input);
+      expect(result).toEqual(input);
+    });
+
+    it("should convert a single object to an array", () => {
+      const input = { name: "Charlie", age: 35 };
+      const result = schema.parse(input);
+      expect(result).toEqual([input]);
+    });
+
+    it("should validate object properties", () => {
+      expect(() => schema.parse([{ name: "Dave", age: "invalid" }])).toThrow(
+        z.ZodError,
+      );
+    });
+  });
+
+  describe("with optional schema", () => {
+    const schema = toArray(z.string().optional());
+
+    it("should handle undefined in array", () => {
+      const result = schema.parse([undefined, "hello", undefined]);
+      expect(result).toEqual([undefined, "hello", undefined]);
+    });
+
+    it("should convert undefined to array with undefined", () => {
+      const result = schema.parse(undefined);
+      expect(result).toEqual([undefined]);
+    });
+  });
+
+  describe("with union schema", () => {
+    const schema = toArray(z.union([z.string(), z.number()]));
+
+    it("should accept mixed types in array", () => {
+      const result = schema.parse(["hello", 42, "world", 123]);
+      expect(result).toEqual(["hello", 42, "world", 123]);
+    });
+
+    it("should convert single string to array", () => {
+      const result = schema.parse("test");
+      expect(result).toEqual(["test"]);
+    });
+
+    it("should convert single number to array", () => {
+      const result = schema.parse(999);
+      expect(result).toEqual([999]);
+    });
+
+    it("should throw for invalid type", () => {
+      expect(() => schema.parse(true)).toThrow(z.ZodError);
+    });
+  });
+
+  describe("with nullable schema", () => {
+    const schema = toArray(z.string().nullable());
+
+    it("should handle null in array", () => {
+      const result = schema.parse([null, "hello", null]);
+      expect(result).toEqual([null, "hello", null]);
+    });
+
+    it("should convert null to array with null", () => {
+      const result = schema.parse(null);
+      expect(result).toEqual([null]);
+    });
+  });
+
+  describe("with transformed schema", () => {
+    const baseSchema = z.string().transform((val) => val.toUpperCase());
+    const schema = toArray(baseSchema);
+
+    it("should apply transformation to array elements", () => {
+      const result = schema.parse(["hello", "world"]);
+      expect(result).toEqual(["HELLO", "WORLD"]);
+    });
+
+    it("should apply transformation to single value", () => {
+      const result = schema.parse("hello");
+      expect(result).toEqual(["HELLO"]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle deeply nested arrays", () => {
+      const schema = toArray(toArray(z.number()));
+      const result = schema.parse([[1, 2], [3, 4]]);
+      expect(result).toEqual([[1, 2], [3, 4]]);
+    });
+
+    it("should convert single value to nested array", () => {
+      const schema = toArray(toArray(z.number()));
+      const result = schema.parse(5);
+      expect(result).toEqual([[5]]);
+    });
+
+    it("should return equal array when input is already an array", () => {
+      const schema = toArray(z.string());
+      const input = ["test"];
+      const result = schema.parse(input);
+      expect(result).toEqual(input);
+    });
+  });
+});

package/src/{status/types.ts → zod/toArray.ts}

@@ -7,16 +7,7 @@
 // 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/v4";
+import z from "zod";
 
-export const variantZ = z.enum([
-  "success",
-  "info",
-  "warning",
-  "error",
-  "loading",
-  "disabled",
-]);
-
-// Represents one of the possible variants of a status message.
-export type Variant = z.infer<typeof variantZ>;
+export const toArray = <T extends z.ZodType>(schema: T) =>
+  z.array(schema).or(schema.transform((v) => [v]));

package/src/zod/util.spec.ts

@@ -8,7 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { describe, expect, it, test } from "vitest";
-import { z } from "zod/v4";
+import { z } from "zod";
 
 import { zod } from "@/zod";
 
@@ -110,7 +110,7 @@ describe("zod", () => {
           });
         const v = zod.getFieldSchema(schema, "name");
         expect(v).toBeInstanceOf(z.ZodString);
-        expect(v.isOptional()).toBe(false);
+        expect(v.safeParse(undefined).success).toBe(false);
       });
     });
   });

package/src/zod/util.ts

@@ -7,10 +7,10 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-import { type z } from "zod/v4";
+import { type z } from "zod";
 
 import { deep } from "@/deep";
-import { type UnknownRecord } from "@/record";
+import { type record } from "@/record";
 
 export const getFieldSchemaPath = (path: string): string =>
   deep.transformPath(path, (part, index, parts) => {
@@ -29,7 +29,7 @@ const sourceTypeGetter = (obj: unknown, key: string): z.ZodAny | null => {
     const sourceType = (
       obj as { sourceType: () => z.ZodObject<z.ZodRawShape> }
     ).sourceType();
-    return (sourceType as unknown as UnknownRecord)[key] as z.ZodAny | null;
+    return (sourceType as unknown as record.Unknown)[key] as z.ZodAny | null;
   }
   return v;
 };