@synnaxlabs/x 0.43.0 → 0.44.1

package/src/math/math.ts

@@ -7,27 +7,20 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-/** A primitive numeric value is either a number or a bigint. */
-export type PrimitiveNumeric = number | bigint;
-
-/** An extension of {@link PrimitiveNumeric} that includes the {@link BigInt} and {@link Number} classes. */
-export type Numeric = PrimitiveNumeric | Number | BigInt;
-
-const isBigInt = (n: Numeric): n is bigint | BigInt =>
-  typeof n === "bigint" || n instanceof BigInt;
+/** A numeric value is either a a number, or a bigint. */
+export type Numeric = number | bigint;
 
 /**
  * @returns the product of a and b, coercing b to the type of a if necessary. */
 export const sub = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() - BigInt(b.valueOf().valueOf())) as V;
-  return (a.valueOf() - Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a - BigInt(b)) as V;
+  return (a - Number(b)) as V;
 };
 
 /** @returns the sum of a and b, coercing b to the type of a if necessary. */
 export const add = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() + BigInt(b.valueOf().valueOf())) as V;
-  // @ts-expect-error - a is a number but typescript doesn't recognize that.
-  return (a + Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a + BigInt(b)) as V;
+  return ((a as unknown as number) + Number(b)) as V;
 };
 
 /** @returns true if a is close to b within epsilon. */
@@ -36,8 +29,8 @@ export const closeTo = (a: number, b: number, epsilon = 0.0001): boolean =>
 
 /** @returns true if a is equal to b, coercing b to the type of a if necessary. */
 export const equal = <V extends Numeric>(a: V, b: Numeric): boolean => {
-  if (isBigInt(a)) return a === BigInt(b.valueOf().valueOf());
-  return a === Number(b.valueOf());
+  if (typeof a === "bigint") return a === BigInt(b);
+  return a === Number(b);
 };
 
 /**
@@ -53,32 +46,31 @@ export const roundToNearestMagnitude = (num: number): number => {
 
 /** @returns the minimum of a and b, coercing b to the type of a if necessary. */
 export const min = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a))
-    return (a.valueOf() < BigInt(b.valueOf()) ? a : BigInt(b.valueOf())) as V;
-  return (a.valueOf() < Number(b.valueOf()) ? a : Number(b.valueOf())) as V;
+  if (a <= b) return a;
+  if (typeof a === "bigint") return (a <= b ? a : BigInt(b)) as V;
+  return (a <= b ? a : Number(b)) as V;
 };
 
 /** @returns the maximum of a and b, coercing b to the type of a if necessary. */
 export const max = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a))
-    return (a.valueOf() > BigInt(b.valueOf()) ? a : BigInt(b.valueOf())) as V;
-  return (a.valueOf() > Number(b.valueOf()) ? a : Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a >= b ? a : BigInt(b)) as V;
+  return (a >= b ? a : Number(b)) as V;
 };
 
 /** @returns the absolute value of a. */
 export const abs = <V extends Numeric>(a: V): V => {
-  if (isBigInt(a) || a instanceof BigInt) return (a.valueOf() < 0n ? -a : a) as V;
-  return (a.valueOf() < 0 ? -a : a) as V;
+  if (a < 0) return -a as V;
+  return a;
 };
 
 /** @returns the multiplication of a and b, coercing b to the type of a if necessary. */
 export const mult = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() * BigInt(b.valueOf())) as V;
-  return (a.valueOf() * Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a * BigInt(b)) as V;
+  return (a * Number(b)) as V;
 };
 
 /** @returns the division of a and b, coercing b to the type of a if necessary. */
 export const div = <V extends Numeric>(a: V, b: Numeric): V => {
-  if (isBigInt(a)) return (a.valueOf() / BigInt(b.valueOf())) as V;
-  return (a.valueOf() / Number(b.valueOf())) as V;
+  if (typeof a === "bigint") return (a / BigInt(b)) as V;
+  return (a / Number(b)) as V;
 };

package/src/migrate/migrate.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 { migrate } from "@/migrate";
 
@@ -59,7 +59,7 @@ const migrations: migrate.Migrations = {
 describe("compareSemVer", () => {
   it("should return true when the major version is higher", () => {
     expect(migrate.compareSemVer("1.0.0", "0.0.0")).toBeGreaterThan(0);
-    expect(migrate.semVerNewer("3.0.0", "0.3.0")).toBeTruthy();
+    expect(migrate.semVerNewer("3.0.0", "0.3.0")).toBe(true);
   });
   describe("only check major", () => {
     it("should return equal when the major versions are equal but the minor and patch are different", () => {

package/src/migrate/migrate.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 { compare } from "@/compare";
 import { type Optional } from "@/optional";
@@ -70,7 +70,7 @@ export const compareSemVer = ((
     if (aPatch > bPatch) return compare.GREATER_THAN;
   }
   return compare.EQUAL;
-}) satisfies compare.CompareF<SemVer>;
+}) satisfies compare.Comparator<SemVer>;
 
 /**
  * @returns true if the two semantic versions are equal.

package/src/notation/notation.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";
 
 export const NOTATIONS = ["standard", "scientific", "engineering"] as const;
 export const notationZ = z.enum(NOTATIONS);

package/src/optional.ts

@@ -8,7 +8,3 @@
 // included in the file licenses/APL.txt.
 
 export type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>;
-
-export type Required<T> = {
-  [P in keyof T]-?: T[P];
-};

package/src/primitive/primitive.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 { binary } from "@/binary";
 import { primitive } from "@/primitive";

package/src/record/index.ts

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

package/src/record/record.spec.ts

@@ -0,0 +1,319 @@
+// 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 { record } from "@/record";
+
+describe("record", () => {
+  describe("types", () => {
+    it("should allow string and number keys", () => {
+      // Test Key type
+      const stringKey: record.Key = "test";
+      const numberKey: record.Key = 123;
+
+      expect(typeof stringKey).toBe("string");
+      expect(typeof numberKey).toBe("number");
+    });
+
+    it("should allow unknown values", () => {
+      // Test Unknown type
+      const unknown: record.Unknown = {
+        string: "value",
+        number: 42,
+        boolean: true,
+        object: { nested: "value" },
+        array: [1, 2, 3],
+        null: null,
+        undefined,
+      };
+
+      expect(unknown.string).toBe("value");
+      expect(unknown.number).toBe(42);
+      expect(unknown.boolean).toBe(true);
+    });
+
+    it("should support Keyed interface", () => {
+      // Test Keyed interface
+      const keyedString: record.Keyed<string> = { key: "test" };
+      const keyedNumber: record.Keyed<number> = { key: 123 };
+
+      expect(keyedString.key).toBe("test");
+      expect(keyedNumber.key).toBe(123);
+    });
+
+    it("should support KeyedNamed interface", () => {
+      // Test KeyedNamed interface
+      const keyedNamed: record.KeyedNamed = { key: "test", name: "Test Item" };
+      const keyedNamedNumber: record.KeyedNamed<number> = {
+        key: 123,
+        name: "Number Item",
+      };
+
+      expect(keyedNamed.key).toBe("test");
+      expect(keyedNamed.name).toBe("Test Item");
+      expect(keyedNamedNumber.key).toBe(123);
+      expect(keyedNamedNumber.name).toBe("Number Item");
+    });
+  });
+
+  describe("unknownZ", () => {
+    it("should validate valid records", () => {
+      const validRecord = {
+        string: "value",
+        number: 42,
+        symbol: Symbol("test"),
+        nested: { key: "value" },
+        array: [1, 2, 3],
+      };
+
+      const result = record.unknownZ.safeParse(validRecord);
+      expect(result.success).toBe(true);
+    });
+
+    it("should not reject invalid keys", () => {
+      const invalidRecord = {
+        [Symbol("test")]: "value", // Symbol keys are not allowed in the schema
+      };
+
+      const result = record.unknownZ.safeParse(invalidRecord);
+      expect(result.success).toBe(true);
+    });
+
+    it("should accept empty objects", () => {
+      const emptyRecord = {};
+      const result = record.unknownZ.safeParse(emptyRecord);
+      expect(result.success).toBe(true);
+    });
+
+    it("should accept null and undefined values", () => {
+      const recordWithNulls = {
+        null: null,
+        undefined,
+        string: "value",
+      };
+
+      const result = record.unknownZ.safeParse(recordWithNulls);
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("entries", () => {
+    it("should return entries for a simple object", () => {
+      const obj = { a: 1, b: "test", c: true };
+      const result = record.entries(obj);
+
+      expect(result).toEqual([
+        ["a", 1],
+        ["b", "test"],
+        ["c", true],
+      ]);
+    });
+
+    it("should return entries for an object with number keys", () => {
+      const obj = { 1: "one", 2: "two", 3: "three" };
+      const result = record.entries(obj);
+
+      expect(result).toEqual([
+        ["1", "one"],
+        ["2", "two"],
+        ["3", "three"],
+      ]);
+    });
+
+    it("should return empty array for empty object", () => {
+      const obj = {};
+      const result = record.entries(obj);
+
+      expect(result).toEqual([]);
+    });
+
+    it("should preserve order of entries", () => {
+      const obj = { first: 1, second: 2, third: 3 };
+      const result = record.entries(obj);
+
+      expect(result[0]).toEqual(["first", 1]);
+      expect(result[1]).toEqual(["second", 2]);
+      expect(result[2]).toEqual(["third", 3]);
+    });
+
+    it("should handle objects with null and undefined values", () => {
+      const obj = { a: null, b: undefined, c: "value" };
+      const result = record.entries(obj);
+
+      expect(result).toEqual([
+        ["a", null],
+        ["b", undefined],
+        ["c", "value"],
+      ]);
+    });
+  });
+
+  describe("map", () => {
+    it("should map values using the provided function", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = record.map(obj, (value) => value * 2);
+
+      expect(result).toEqual({ a: 2, b: 4, c: 6 });
+    });
+
+    it("should pass both value and key to the mapping function", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = record.map(obj, (value, key) => `${key}:${value}`);
+
+      expect(result).toEqual({ a: "a:1", b: "b:2", c: "c:3" });
+    });
+
+    it("should handle different return types", () => {
+      const obj = { a: 1, b: 2, c: 3 };
+      const result = record.map(obj, (value) => value > 2);
+
+      expect(result).toEqual({ a: false, b: false, c: true });
+    });
+
+    it("should return empty object for empty input", () => {
+      const obj = {};
+      const result = record.map(obj, (value) => value);
+
+      expect(result).toEqual({});
+    });
+
+    it("should handle objects with mixed value types", () => {
+      const obj = { a: 1, b: "test", c: true, d: null };
+      const result = record.map(obj, (value) => typeof value);
+
+      expect(result).toEqual({
+        a: "number",
+        b: "string",
+        c: "boolean",
+        d: "object",
+      });
+    });
+
+    it("should preserve key types", () => {
+      const obj = { 1: "one", 2: "two" };
+      const result = record.map(obj, (value) => value.toUpperCase());
+
+      expect(result).toEqual({ 1: "ONE", 2: "TWO" });
+    });
+  });
+
+  describe("purgeUndefined", () => {
+    it("should remove undefined values", () => {
+      const obj = { a: 1, b: undefined, c: "test", d: undefined };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({ a: 1, c: "test" });
+    });
+
+    it("should not remove null values", () => {
+      const obj = { a: 1, b: null, c: "test", d: null };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({ a: 1, b: null, c: "test", d: null });
+    });
+
+    it("should preserve other falsy values", () => {
+      const obj = { a: 0, b: false, c: "", d: undefined, e: null };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({ a: 0, b: false, c: "", e: null });
+    });
+
+    it("should return empty object when all values are undefined", () => {
+      const obj = { a: undefined, b: undefined, c: undefined };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({});
+    });
+
+    it("should return same object when no null/undefined values", () => {
+      const obj = { a: 1, b: "test", c: true, d: 0, e: false };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual(obj);
+    });
+
+    it("should handle empty object", () => {
+      const obj = {};
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({});
+    });
+
+    it("should not purge undefined values in nested objects and arrays", () => {
+      const obj = {
+        a: 1,
+        b: undefined,
+        c: { nested: "value" },
+        d: null,
+        e: [1, 2, 3],
+      };
+      const result = record.purgeUndefined(obj);
+
+      expect(result).toEqual({
+        a: 1,
+        c: { nested: "value" },
+        e: [1, 2, 3],
+        d: null,
+      });
+    });
+
+    it("should create a copy of the object", () => {
+      const obj = { a: 1, b: "test" };
+      const result = record.purgeUndefined(obj);
+      expect(result).not.toBe(obj);
+    });
+  });
+
+  describe("integration", () => {
+    it("should work together: entries -> map -> deleteUndefined", () => {
+      const original = { a: 1, b: undefined, c: 3, d: null };
+
+      // Get entries
+      const entries = record.entries(original);
+      expect(entries).toEqual([
+        ["a", 1],
+        ["b", undefined],
+        ["c", 3],
+        ["d", null],
+      ]);
+
+      // Map to double values (keeping undefined/null)
+      const mapped = record.map(original, (value) =>
+        typeof value === "number" ? value * 2 : value,
+      );
+      expect(mapped).toEqual({ a: 2, b: undefined, c: 6, d: null });
+
+      // Remove undefined/null
+      const cleaned = record.purgeUndefined(mapped);
+      expect(cleaned).toEqual({ a: 2, c: 6, d: null });
+    });
+
+    it("should not purge undefined values in complex nested structures", () => {
+      const complex = {
+        id: 1,
+        name: "test",
+        metadata: undefined,
+        tags: null,
+        config: { enabled: true, timeout: undefined },
+        items: [1, 2, 3],
+      };
+
+      const result = record.purgeUndefined(complex);
+      expect(result).toEqual({
+        id: 1,
+        name: "test",
+        config: { enabled: true, timeout: undefined },
+        items: [1, 2, 3],
+        tags: null,
+      });
+    });
+  });
+});

package/src/record/record.ts

@@ -0,0 +1,118 @@
+// 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 { z } from "zod";
+
+/**
+ * Represents valid key types for record objects.
+ * Can be either a string or number.
+ */
+export type Key = string | number;
+
+/**
+ * Represents a record with unknown values and string/number keys.
+ * This is a generic type for objects where the value types are not known.
+ */
+export type Unknown = Record<Key, unknown>;
+
+/**
+ * Interface for objects that have a key property.
+ * @template K - The type of the key (must extend Key)
+ */
+export interface Keyed<K extends Key = Key> {
+  /** The key identifier for this object */
+  key: K;
+}
+
+/**
+ * Interface for objects that have both a key and a name property.
+ * @template K - The type of the key (defaults to string)
+ */
+export interface KeyedNamed<K extends Key = string> {
+  /** The key identifier for this object */
+  key: K;
+  /** The display name for this object */
+  name: string;
+}
+
+/**
+ * Zod schema for validating unknown records.
+ * Accepts objects with string, number, or symbol keys and unknown values.
+ */
+export const unknownZ = z.record(
+  z.union([z.number(), z.string(), z.symbol()]),
+  z.unknown(),
+);
+
+/**
+ * Type representing the entries of a record as an array of key-value tuples.
+ * @template T - The record type
+ */
+export type Entries<T> = Array<
+  {
+    [K in keyof T]: [K, T[K]];
+  }[keyof T]
+>;
+
+/**
+ * Converts a record object into an array of key-value tuples.
+ * This is a type-safe wrapper around Object.entries().
+ *
+ * @template T - The type of the input record
+ * @param obj - The record object to convert to entries
+ * @returns An array of [key, value] tuples
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: 1, b: "hello" };
+ * const entries = record.entries(obj);
+ * // Result: [["a", 1], ["b", "hello"]]
+ * ```
+ */
+export const entries = <T extends Record<Key, unknown>>(obj: T): Entries<T> =>
+  Object.entries(obj) as Entries<T>;
+
+/**
+ * Maps over the entries of a record, applying a transformation function to each value.
+ *
+ * @template T - The type of the input record
+ * @template U - The type of the output values
+ * @param obj - The record object to map over
+ * @param fn - A function that transforms each value. Receives the value and key as parameters.
+ * @returns A new record with the same keys but transformed values
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: 1, b: 2, c: 3 };
+ * const doubled = record.map(obj, (value, key) => value * 2);
+ * // Result: { a: 2, b: 4, c: 6 }
+ * ```
+ */
+export const map = <T extends Record<Key, unknown>, U>(
+  obj: T,
+  fn: (value: T[keyof T], key: keyof T) => U,
+): Record<Key, U> =>
+  Object.fromEntries(entries(obj).map(([key, value]) => [key, fn(value, key)]));
+
+/**
+ * Removes all properties with undefined or null values from a record.
+ *
+ * @template T - The type of the input record
+ * @param obj - The record object to purge
+ * @returns A new record with undefined/null values removed
+ *
+ * @example
+ * ```typescript
+ * const obj = { a: 1, b: undefined, c: null, d: "hello" };
+ * const purged = record.purgeUndefined(obj);
+ * // Result: { a: 1, d: "hello" }
+ * ```
+ */
+export const purgeUndefined = <T extends Record<Key, unknown>>(obj: T): T =>
+  Object.fromEntries(entries(obj).filter(([_, value]) => value !== undefined)) as T;

package/src/runtime/os.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";
 
 export const OPERATING_SYSTEMS = ["macOS", "Windows", "Linux"] as const;
 const LOWERCASE_OPERATING_SYSTEMS = ["macos", "windows", "linux"] as const;

package/src/spatial/base.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";
 
 export const numberCouple = z.tuple([z.number(), z.number()]);
 export const bigNumberCouple = z.tuple([z.bigint(), z.bigint()]);

package/src/spatial/box/box.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 type * as bounds from "@/spatial/bounds/bounds";
 import type * as dimensions from "@/spatial/dimensions/dimensions";
@@ -484,3 +484,8 @@ export const constructWithAlternateRoot = (
     }
   return construct(first, second, undefined, undefined, newRoot);
 };
+
+export const round = (b: Crude): Box => {
+  const b_ = construct(b);
+  return construct(xy.round(b_.one), xy.round(b_.two), undefined, undefined, b_.root);
+};

package/src/spatial/dimensions/dimensions.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 { type Dimensions, dimensions, numberCouple, xy } from "@/spatial/base";
 

package/src/spatial/direction/direction.ts

@@ -20,7 +20,7 @@ import {
   type YLocation,
 } from "@/spatial/base";
 
-export { Direction, direction };
+export { Direction, direction, DIRECTIONS };
 
 export const crude = crudeDirection;
 

package/src/spatial/location/location.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 { caseconv } from "@/caseconv";
 import {

package/src/spatial/scale/scale.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 { clamp } from "@/clamp/clamp";
 import { type numeric } from "@/numeric";