@synnaxlabs/x 0.55.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.55.0",
+  "version": "0.56.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.9",
-    "uuid": "^13.0.0",
-    "zod": "^4.3.6"
+    "nanoid": "^5.1.11",
+    "uuid": "^14.0.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
-    "@vitest/coverage-v8": "^4.1.4",
-    "eslint": "^10.2.1",
+    "@types/node": "^25.9.0",
+    "@vitest/coverage-v8": "^4.1.6",
+    "eslint": "^10.4.0",
     "madge": "^8.0.0",
     "typescript": "^6.0.3",
-    "vite": "^8.0.8",
-    "vitest": "^4.1.4",
+    "vite": "^8.0.13",
+    "vitest": "^4.1.6",
     "@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/array/nullable.ts

@@ -19,7 +19,4 @@ import z from "zod";
  * - [items] → [items]
  */
 export const nullishToEmpty = <Z extends z.ZodType>(item: Z) =>
-  z.union([
-    z.union([z.null(), z.undefined()]).transform<z.infer<Z>[]>(() => []),
-    item.array(),
-  ]);
+  z.union([z.null().transform<z.infer<Z>[]>(() => []), item.array()]).default(() => []);

package/src/caseconv/caseconv.spec.ts

@@ -403,6 +403,35 @@ describe("caseconv", () => {
         expect(result.values[0].data.One).toBe(1);
       });
 
+      it("should resolve array element schema through wrapper schemas (default, optional, nullable)", () => {
+        const elementZ = z.object({
+          data: caseconv.preserveCase(z.record(z.string(), z.unknown())),
+        });
+        const input = {
+          items: [{ data: { CamelKey: 1, snake_key: 2, PascalKey: { Inner_Key: 3 } } }],
+        };
+        const expectPreserved = (result: R) => {
+          expect(result.items[0].data.CamelKey).toBe(1);
+          expect(result.items[0].data.snake_key).toBe(2);
+          expect(result.items[0].data.PascalKey.Inner_Key).toBe(3);
+        };
+        expectPreserved(
+          caseconv.snakeToCamel(input, {
+            schema: z.object({ items: elementZ.array().default(() => []) }),
+          }),
+        );
+        expectPreserved(
+          caseconv.snakeToCamel(input, {
+            schema: z.object({ items: elementZ.array().optional() }),
+          }),
+        );
+        expectPreserved(
+          caseconv.snakeToCamel(input, {
+            schema: z.object({ items: elementZ.array().nullable() }),
+          }),
+        );
+      });
+
       it("should handle array.nullishToEmpty with preserveCase on element field", async () => {
         const { nullishToEmpty } = await import("@/array/nullable");
         const elementZ = z.object({
@@ -692,5 +721,47 @@ describe("caseconv", () => {
         expect(decoded.linePlots[0].data.my_custom_key).toBeUndefined();
       });
     });
+
+    describe("discriminated union shape merging", () => {
+      it("should resolve a per-variant field schema when walking a discriminated union", () => {
+        const variantA = z.object({
+          type: z.literal("a"),
+          fieldA: caseconv.preserveCase(z.record(z.string(), z.unknown())),
+        });
+        const variantB = z.object({
+          type: z.literal("b"),
+          fieldB: caseconv.preserveCase(z.record(z.string(), z.unknown())),
+        });
+        const unionZ = z.discriminatedUnion("type", [variantA, variantB]);
+        const wrapperZ = z.object({ envelope: unionZ });
+        const inputB = {
+          envelope: {
+            type: "b",
+            fieldB: { CamelKey: 1, snake_key: 2, PascalKey: { Inner_Key: 3 } },
+          },
+        };
+        const encoded = caseconv.camelToSnake(inputB, { schema: wrapperZ }) as R;
+        expect(encoded.envelope.field_b.CamelKey).toBe(1);
+        expect(encoded.envelope.field_b.snake_key).toBe(2);
+        expect(encoded.envelope.field_b.PascalKey.Inner_Key).toBe(3);
+        expect(encoded.envelope.field_b.camel_key).toBeUndefined();
+      });
+
+      it("should preserve case through preserveCase wrapping a union (record.nullishToEmpty)", () => {
+        const innerZ = caseconv.preserveCase(
+          z
+            .union([z.null().transform(() => ({})), z.record(z.string(), z.unknown())])
+            .default(() => ({})),
+        );
+        const schema = z.object({ payload: innerZ });
+        const input = {
+          payload: { CamelKey: 1, snake_key: 2, PascalKey: { Inner_Key: 3 } },
+        };
+        const encoded = caseconv.camelToSnake(input, { schema }) as R;
+        expect(encoded.payload.CamelKey).toBe(1);
+        expect(encoded.payload.snake_key).toBe(2);
+        expect(encoded.payload.PascalKey.Inner_Key).toBe(3);
+      });
+    });
   });
 });

package/src/caseconv/caseconv.ts

@@ -97,6 +97,8 @@ const getArrayElementSchema = (
   if (schema == null) return undefined;
   const def = (schema as ZodSchema)._zod?.def;
   if (def?.type === "array" && def.element != null) return def.element as z.ZodType;
+  // Traverse through wrappers (optional, nullable, default, catch) to inner schema
+  if (def?.innerType != null) return getArrayElementSchema(def.innerType);
   // Handle union types that may contain arrays (e.g., nullishToEmpty)
   if (def?.type === "union" && Array.isArray(def.options))
     for (const option of def.options) {
@@ -111,6 +113,12 @@ const getArrayElementSchema = (
  * Extracts the shape (field name → ZodType map) from a Zod schema.
  * Traverses through wrappers (optional, nullable, default, catch, union, pipe)
  * to find the inner object schema's shape. Returns null for non-object schemas.
+ *
+ * For unions (including discriminated unions), the shapes of every option are
+ * merged, with earlier options taking precedence on key conflicts. This lets a
+ * caller looking up a single field name resolve it to the variant that
+ * actually declares it — e.g., walking a discriminated union of action
+ * payloads where each variant carries a distinct inner field.
  */
 const getSchemaShape = (
   schema: z.ZodType | z.core.SomeType | undefined,
@@ -125,11 +133,16 @@ const getSchemaShape = (
   const def = s._zod?.def;
   if (def == null) return null;
   if (def.innerType != null) return getSchemaShape(def.innerType);
-  if (def.type === "union" && Array.isArray(def.options))
+  if (def.type === "union" && Array.isArray(def.options)) {
+    let merged: Record<string, z.ZodType> | null = null;
     for (const option of def.options) {
       const result = getSchemaShape(option);
-      if (result != null) return result;
+      if (result == null) continue;
+      if (merged == null) merged = { ...result };
+      else for (const k in result) if (!(k in merged)) merged[k] = result[k];
     }
+    return merged;
+  }
 
   if (def.type === "pipe") return getSchemaShape(def.in) ?? getSchemaShape(def.out);
   return null;

package/src/compare/compare.spec.ts

@@ -46,4 +46,119 @@ describe("compare", () => {
       });
     });
   });
+
+  describe("mapsEqual", () => {
+    it("returns true for the same reference", () => {
+      const m = new Map<string, number>([["a", 1]]);
+      expect(compare.mapsEqual(m, m)).toBe(true);
+    });
+
+    it("returns true for content-equal maps with identity-equal values", () => {
+      const a = new Map<string, number>([
+        ["a", 1],
+        ["b", 2],
+      ]);
+      const b = new Map<string, number>([
+        ["a", 1],
+        ["b", 2],
+      ]);
+      expect(compare.mapsEqual(a, b)).toBe(true);
+    });
+
+    it("returns true regardless of insertion order", () => {
+      const a = new Map<string, number>([
+        ["a", 1],
+        ["b", 2],
+      ]);
+      const b = new Map<string, number>([
+        ["b", 2],
+        ["a", 1],
+      ]);
+      expect(compare.mapsEqual(a, b)).toBe(true);
+    });
+
+    it("returns false when sizes differ", () => {
+      const a = new Map<string, number>([["a", 1]]);
+      const b = new Map<string, number>([
+        ["a", 1],
+        ["b", 2],
+      ]);
+      expect(compare.mapsEqual(a, b)).toBe(false);
+    });
+
+    it("returns false when a key is present in one but missing in the other", () => {
+      const a = new Map<string, number>([
+        ["a", 1],
+        ["b", 2],
+      ]);
+      const b = new Map<string, number>([
+        ["a", 1],
+        ["c", 2],
+      ]);
+      expect(compare.mapsEqual(a, b)).toBe(false);
+    });
+
+    it("returns false when a value differs by identity", () => {
+      const a = new Map<string, { v: number }>([["a", { v: 1 }]]);
+      const b = new Map<string, { v: number }>([["a", { v: 1 }]]);
+      expect(compare.mapsEqual(a, b)).toBe(false);
+    });
+
+    it("returns true when a value is the same object reference", () => {
+      const shared = { v: 1 };
+      const a = new Map<string, { v: number }>([["a", shared]]);
+      const b = new Map<string, { v: number }>([["a", shared]]);
+      expect(compare.mapsEqual(a, b)).toBe(true);
+    });
+
+    it("treats undefined values as present", () => {
+      const a = new Map<string, number | undefined>([["a", undefined]]);
+      const b = new Map<string, number | undefined>([["b", undefined]]);
+      expect(compare.mapsEqual(a, b)).toBe(false);
+    });
+
+    it("returns true for two empty maps", () => {
+      expect(compare.mapsEqual(new Map(), new Map())).toBe(true);
+    });
+  });
+
+  describe("arraysEqual", () => {
+    it("returns true for the same reference", () => {
+      const a = [1, 2, 3];
+      expect(compare.arraysEqual(a, a)).toBe(true);
+    });
+
+    it("returns true for content-equal primitive arrays", () => {
+      expect(compare.arraysEqual([1, 2, 3], [1, 2, 3])).toBe(true);
+    });
+
+    it("returns false when lengths differ", () => {
+      expect(compare.arraysEqual([1, 2], [1, 2, 3])).toBe(false);
+    });
+
+    it("returns false when an element differs by value", () => {
+      expect(compare.arraysEqual([1, 2, 3], [1, 9, 3])).toBe(false);
+    });
+
+    it("is order-sensitive", () => {
+      expect(compare.arraysEqual([1, 2, 3], [3, 2, 1])).toBe(false);
+    });
+
+    it("uses identity equality for object elements", () => {
+      const a = { v: 1 };
+      const b = { v: 1 };
+      expect(compare.arraysEqual([a], [a])).toBe(true);
+      expect(compare.arraysEqual([a], [b])).toBe(false);
+    });
+
+    it("returns true for two empty arrays", () => {
+      expect(compare.arraysEqual([], [])).toBe(true);
+    });
+
+    it("works with readonly arrays", () => {
+      const a: readonly number[] = [1, 2, 3];
+      const b: readonly number[] = [1, 2, 3];
+      expect(compare.arraysEqual(a, b)).toBe(true);
+    });
+  });
 });

package/src/compare/compare.ts

@@ -104,6 +104,35 @@ export const uniqueUnorderedPrimitiveArrays = <T extends primitive.Value>(
   return unorderedPrimitiveArrays(uniqueA, uniqueB);
 };
 
+/**
+ * Returns true if the two maps have the same set of keys and each value is
+ * identity-equal (===). Intended for use as a reference-stability comparator
+ * (e.g. React's `useSyncExternalStoreWithSelector`) where the values are
+ * already reference-stable in storage (e.g. Immer state). For deeper value
+ * comparison, compose with `deep.equal` at the call site.
+ */
+export const mapsEqual = <K, V>(a: Map<K, V>, b: Map<K, V>): boolean => {
+  if (a === b) return true;
+  if (a.size !== b.size) return false;
+  for (const [k, v] of a) if (!b.has(k) || b.get(k) !== v) return false;
+  return true;
+};
+
+/**
+ * Returns true if the two arrays have the same length and each element is
+ * identity-equal (===). Same use case as `mapsEqual` for selectors that
+ * derive arrays from reference-stable storage.
+ */
+export const arraysEqual = <T>(
+  a: readonly T[] | T[],
+  b: readonly T[] | T[],
+): boolean => {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+};
+
 export const order = (a: spatial.Order, b: spatial.Order): number => {
   if (a === b) return 0;
   if (a === "first" && b === "last") return 1;

package/src/debounce/debounce.spec.ts

@@ -7,45 +7,279 @@
 // 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 { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { debounce, throttle } from "@/debounce/debounce";
+import { debounce } from "@/debounce/debounce";
+import { TimeSpan } from "@/telem/telem";
 
 describe("debounce", () => {
-  describe("debounce", () => {
-    it("should debounce the execution of the given function", () => {
-      vi.useFakeTimers();
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("should not execute immediately", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+
+    expect(fn).toHaveBeenCalledTimes(0);
+  });
+
+  it("should execute after the wait period", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+
+    vi.advanceTimersByTime(99);
+    expect(fn).toHaveBeenCalledTimes(0);
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+  });
+
+  it("should reset the timer on repeated calls", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    vi.advanceTimersByTime(90);
+
+    debounced(20);
+    vi.advanceTimersByTime(90);
+
+    expect(fn).toHaveBeenCalledTimes(0);
+
+    vi.advanceTimersByTime(10);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(20);
+  });
+
+  it("should run with the latest arguments", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    debounced(20);
+    debounced(30);
+    debounced(40);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(40);
+  });
+
+  it("should not execute before the full wait period since the latest call", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    vi.advanceTimersByTime(50);
+
+    debounced(20);
+    vi.advanceTimersByTime(99);
+
+    expect(fn).toHaveBeenCalledTimes(0);
+
+    vi.advanceTimersByTime(1);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(20);
+  });
+
+  it("should only execute once for a burst of calls", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    vi.advanceTimersByTime(25);
+    debounced(20);
+    vi.advanceTimersByTime(25);
+    debounced(30);
+    vi.advanceTimersByTime(25);
+    debounced(40);
+
+    vi.advanceTimersByTime(99);
+    expect(fn).toHaveBeenCalledTimes(0);
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(40);
+
+    vi.advanceTimersByTime(100);
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  it("should execute again after a previous debounce cycle completes", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenNthCalledWith(1, 10);
+
+    debounced(20);
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(2, 20);
+  });
+
+  it("should preserve null arguments", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    debounced(null);
+    debounced(20);
+    debounced(null);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(null);
+  });
+
+  it("should preserve multiple arguments", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(1, "a", false);
+    debounced(2, "b", true);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(2, "b", true);
+  });
+
+  it("should clear pending state before invoking the function", () => {
+    const fn = vi.fn();
+    fn.mockImplementation((value: number) => {
+      if (value === 20) debounced(30);
+    });
+
+    const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+    debounced(10);
+    debounced(20);
+
+    vi.advanceTimersByTime(100);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenNthCalledWith(1, 20);
+
+    vi.advanceTimersByTime(99);
+    expect(fn).toHaveBeenCalledTimes(1);
+
+    vi.advanceTimersByTime(1);
+    expect(fn).toHaveBeenCalledTimes(2);
+    expect(fn).toHaveBeenNthCalledWith(2, 30);
+  });
+
+  it("should invoke the function synchronously when the wait period is 0", () => {
+    const fn = vi.fn();
+    const debounced = debounce(fn, TimeSpan.ZERO);
+
+    debounced(10);
+
+    expect(fn).toHaveBeenCalledTimes(1);
+    expect(fn).toHaveBeenLastCalledWith(10);
+  });
+
+  describe("cancel", () => {
+    it("should drop a pending invocation", () => {
       const fn = vi.fn();
-      const debounced = debounce(fn, 100);
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+      debounced(10);
+      debounced.cancel();
+
+      vi.advanceTimersByTime(200);
+
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("should be a no-op when no invocation is pending", () => {
+      const fn = vi.fn();
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+      expect(() => debounced.cancel()).not.toThrow();
+
       debounced(10);
-      debounced(20);
-      debounced(30);
-      debounced(40);
-      expect(fn).toHaveBeenCalledTimes(0);
       vi.advanceTimersByTime(100);
+
       expect(fn).toHaveBeenCalledTimes(1);
-      expect(fn).toHaveBeenCalledWith(40);
+      expect(fn).toHaveBeenLastCalledWith(10);
     });
-    it("should not debounce the execution of the given function if the time is 0", () => {
+
+    it("should be a no-op for a zero-wait debounce", () => {
       const fn = vi.fn();
-      const debounced = debounce(fn, 0);
-      // assert that debounced is the same
-      expect(debounced).toBe(fn);
+      const debounced = debounce(fn, TimeSpan.ZERO);
+
+      expect(() => debounced.cancel()).not.toThrow();
+
+      debounced(10);
+      expect(fn).toHaveBeenCalledTimes(1);
     });
-  });
-  describe("throttle", () => {
-    it("should throttle the execution of the given function", () => {
-      vi.useFakeTimers();
+
+    it("should allow scheduling a new invocation after cancellation", () => {
       const fn = vi.fn();
-      const debounced = throttle(fn, 100);
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
       debounced(10);
+      debounced.cancel();
+      vi.advanceTimersByTime(100);
+      expect(fn).not.toHaveBeenCalled();
+
       debounced(20);
-      debounced(30);
-      debounced(40);
       vi.advanceTimersByTime(100);
+
       expect(fn).toHaveBeenCalledTimes(1);
-      expect(fn).toHaveBeenCalledWith(10);
-      vi.advanceTimersByTime(100);
+      expect(fn).toHaveBeenLastCalledWith(20);
+    });
+  });
+
+  describe("flush", () => {
+    it("should invoke a pending call immediately with the latest arguments", () => {
+      const fn = vi.fn();
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+      debounced(10);
+      debounced(20);
+      debounced.flush();
+
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenLastCalledWith(20);
+    });
+
+    it("should be a no-op when no invocation is pending", () => {
+      const fn = vi.fn();
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+      debounced.flush();
+
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("should clear the pending timer so the function does not fire again later", () => {
+      const fn = vi.fn();
+      const debounced = debounce(fn, TimeSpan.milliseconds(100));
+
+      debounced(10);
+      debounced.flush();
+      vi.advanceTimersByTime(200);
+
       expect(fn).toHaveBeenCalledTimes(1);
     });
   });