@synnaxlabs/x 0.55.0 → 0.56.1

package/src/debounce/debounce.ts

@@ -7,38 +7,57 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export const debounce = <F extends (...args: any[]) => void>(
-  func: F,
-  waitFor: number,
-): F => {
-  let timeout: ReturnType<typeof setTimeout> | null = null;
-  if (waitFor === 0) return func;
+import { type CrudeTimeSpan, TimeSpan } from "@/telem/telem";
 
-  const debounced = (...args: Parameters<F>): void => {
-    if (timeout !== null) {
-      clearTimeout(timeout);
-      timeout = null;
-    }
-    timeout = setTimeout(() => func(...args), waitFor);
-  };
-
-  return debounced as F;
-};
+// DebouncedFn is the function returned by debounce. It carries cancel and
+// flush handles so callers (e.g., React cleanup paths) can drop pending
+// invocations or force them to run immediately on demand. Shape matches
+// lodash.debounce.
+export interface DebouncedFn<Args extends unknown[]> {
+  (...args: Args): void;
+  cancel: () => void;
+  flush: () => void;
+}
 
-export const throttle = <F extends (...args: unknown[]) => void>(
-  func: F,
-  waitFor: number,
-): F => {
-  let timeout: ReturnType<typeof setTimeout> | null = null;
-  if (waitFor === 0) return func;
+const noop = (): void => {};
 
-  const throttled = (...args: Parameters<F>): void => {
-    if (timeout === null)
-      timeout = setTimeout(() => {
-        func(...args);
-        timeout = null;
-      }, waitFor);
+export const debounce = <Args extends unknown[]>(
+  func: (...args: Args) => void,
+  waitFor: CrudeTimeSpan,
+): DebouncedFn<Args> => {
+  const debouncePeriod = new TimeSpan(waitFor);
+  if (debouncePeriod.valueOf() <= 0) {
+    const passthrough = ((...args: Args) => func(...args)) as DebouncedFn<Args>;
+    passthrough.cancel = noop;
+    passthrough.flush = noop;
+    return passthrough;
+  }
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let latestArgs: Args | null = null;
+  const invoke = (): void => {
+    if (latestArgs === null) return;
+    const args = latestArgs;
+    latestArgs = null;
+    func(...args);
   };
-
-  return throttled as F;
+  const debounced = ((...args: Args): void => {
+    latestArgs = args;
+    clearTimeout(timeout);
+    timeout = setTimeout(() => {
+      timeout = undefined;
+      invoke();
+    }, debouncePeriod.milliseconds);
+  }) as DebouncedFn<Args>;
+  debounced.cancel = (): void => {
+    clearTimeout(timeout);
+    timeout = undefined;
+    latestArgs = null;
+  };
+  debounced.flush = (): void => {
+    if (timeout === undefined) return;
+    clearTimeout(timeout);
+    timeout = undefined;
+    invoke();
+  };
+  return debounced;
 };

package/src/deep/copy.spec.ts

@@ -145,4 +145,17 @@ describe("copy", () => {
       expect(copied.uint8).not.toBe(uint8);
     } else expect(Array.from(copied.uint8 as Uint8Array)).toEqual([1, 2, 3]);
   });
+
+  // Mirrors the immer Draft scenario: callers store snapshots of mutable
+  // proxy state in long-lived structures (e.g., undo entries) that outlive
+  // the proxy. The snapshot must own its data so it survives revocation.
+  it("should produce a snapshot detached from a revocable proxy source", () => {
+    const target = { nested: { value: 1 }, list: [1, 2, 3] };
+    const { proxy, revoke } = Proxy.revocable(target, {});
+    const copied = deep.copy(proxy);
+    revoke();
+    expect(copied).toEqual({ nested: { value: 1 }, list: [1, 2, 3] });
+    expect(copied.nested).not.toBe(target.nested);
+    expect(copied.list).not.toBe(target.list);
+  });
 });

package/src/deep/difference.ts

@@ -30,7 +30,7 @@ export const difference = (
         }
         for (let i = 0; i < a.length; i++) compare(a[i], b[i], `${currentPath}[${i}]`);
       } else {
-        const keys = new Set([...Object.keys(a as {}), ...Object.keys(b as {})]);
+        const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
         keys.forEach((key) => {
           compare(
             a[key as keyof typeof a],

package/src/deep/merge.ts

@@ -10,6 +10,7 @@
 import { type z } from "zod";
 
 import { type Partial } from "@/deep/partial";
+import { errors } from "@/errors";
 import { narrow } from "@/narrow";
 
 /**
@@ -32,7 +33,7 @@ export const override = <T>(base: T, ...overrides: Array<Partial<T>>): T => {
       } catch (e) {
         if (e instanceof TypeError)
           throw new TypeError(`.${key}: ${e.message}`, { cause: e });
-        throw e;
+        throw errors.fromUnknown(e);
       }
 
   return override(base, ...overrides);

package/src/deep/set.ts

@@ -8,6 +8,7 @@
 // included in the file licenses/APL.txt.
 
 import { defaultGetter, findBestKey, getIndex, SEPARATOR } from "@/deep/path";
+import { errors } from "@/errors";
 import { type record } from "@/record";
 
 export const set = <V>(obj: V, path: string, value: unknown): void => {
@@ -86,6 +87,6 @@ export const set = <V>(obj: V, path: string, value: unknown): void => {
     result[lastPart] = value;
   } catch (e) {
     console.error("failed to set value", value, "at path", path, "on object", obj);
-    throw e;
+    throw errors.fromUnknown(e);
   }
 };

package/src/destructor/destructor.ts

@@ -14,3 +14,5 @@ export interface Destructor {
 export interface Async {
   (): Promise<void>;
 }
+
+export const NOOP = () => {};

package/src/errors/errors.spec.ts

@@ -96,6 +96,128 @@ describe("errors", () => {
       const decoded = errors.decode(encoded);
       expect(errors.Unknown.matches(decoded)).toBe(true);
     });
+
+    it("should preserve name and stack across encode/decode for a generic Error", () => {
+      const error = new TypeError("boom");
+      const encoded = errors.encode(error);
+      expect(encoded.name).toEqual("TypeError");
+      expect(encoded.stack).toEqual(error.stack);
+      const decoded = errors.decode(encoded);
+      expect((decoded as Error).name).toEqual("TypeError");
+      expect((decoded as Error).stack).toEqual(error.stack);
+    });
+
+    it("should preserve name and stack when a typed error round-trips through a provider", () => {
+      errors.register({
+        encode: myCustomErrorEncoder,
+        decode: myCustomErrorDecoder,
+      });
+      const error = new ErrorOne("boom");
+      const encoded = errors.encode(error);
+      expect(encoded.name).toEqual(ErrorOne.TYPE);
+      expect(encoded.stack).toEqual(error.stack);
+      const decoded = errors.decode(encoded);
+      expect(ErrorOne.matches(decoded)).toBe(true);
+      expect((decoded as Error).stack).toEqual(error.stack);
+    });
+
+    it("should leave the decoded error untouched when the payload omits name and stack", () => {
+      const decoded = errors.decode({ type: errors.UNKNOWN, data: "no native fields" });
+      expect(decoded).toBeInstanceOf(Error);
+      expect((decoded as Error).message).toEqual("no native fields");
+    });
+  });
+
+  describe("fromUnknown", () => {
+    it("should return the same Error instance when given an Error", () => {
+      const original = new Error("already an error");
+      const result = errors.fromUnknown(original);
+      expect(result).toBe(original);
+    });
+
+    it("should preserve typed-error subclasses when given one", () => {
+      const original = new ErrorOne("typed");
+      const result = errors.fromUnknown(original);
+      expect(result).toBe(original);
+      expect(ErrorOne.matches(result)).toBe(true);
+    });
+
+    it("should preserve other Error subclasses like TypeError", () => {
+      const original = new TypeError("bad type");
+      const result = errors.fromUnknown(original);
+      expect(result).toBe(original);
+      expect(result).toBeInstanceOf(TypeError);
+    });
+
+    it("should wrap a string with the string as the message", () => {
+      const result = errors.fromUnknown("plain string");
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual('"plain string"');
+      expect(result.cause).toEqual("plain string");
+    });
+
+    it("should wrap a number using JSON.stringify for the message", () => {
+      const result = errors.fromUnknown(42);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual("42");
+      expect(result.cause).toEqual(42);
+    });
+
+    it("should wrap an object using JSON.stringify for the message", () => {
+      const value = { foo: "bar", n: 1 };
+      const result = errors.fromUnknown(value);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual('{"foo":"bar","n":1}');
+      expect(result.cause).toBe(value);
+    });
+
+    it("should fall back to String() when JSON.stringify throws on a circular ref", () => {
+      const value: Record<string, unknown> = { name: "loop" };
+      value.self = value;
+      const result = errors.fromUnknown(value);
+      expect(result).toBeInstanceOf(Error);
+      // Plain objects without a custom toString fall through to "[object Object]".
+      expect(result.message).toEqual("[object Object]");
+      expect(result.cause).toBe(value);
+    });
+
+    it("should fall back to String() for a BigInt", () => {
+      const value = 9007199254740993n;
+      const result = errors.fromUnknown(value);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual(String(value));
+      expect(result.cause).toBe(value);
+    });
+
+    it("should wrap null with a stringified message", () => {
+      const result = errors.fromUnknown(null);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual("null");
+      expect(result.cause).toBeNull();
+    });
+
+    it("should fall back to String() for undefined (JSON.stringify returns undefined)", () => {
+      const result = errors.fromUnknown(undefined);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual("undefined");
+      expect(result.cause).toBeUndefined();
+    });
+
+    it("should fall back to String() for a function (JSON.stringify returns undefined)", () => {
+      const value = function named() {};
+      const result = errors.fromUnknown(value);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual(String(value));
+      expect(result.cause).toBe(value);
+    });
+
+    it("should fall back to String() for a symbol (JSON.stringify returns undefined)", () => {
+      const value = Symbol("sym");
+      const result = errors.fromUnknown(value);
+      expect(result).toBeInstanceOf(Error);
+      expect(result.message).toEqual("Symbol(sym)");
+      expect(result.cause).toBe(value);
+    });
   });
 
   describe("matches", () => {

package/src/errors/errors.ts

@@ -142,6 +142,28 @@ export const isTyped = (error: unknown): error is Typed => {
   return true;
 };
 
+/**
+ * Coerces an arbitrary thrown value into an `Error` so it can be re-thrown without
+ * tripping `@typescript-eslint/only-throw-error` and so callers can rely on a uniform
+ * `Error` shape. The original value is preserved on `Error.cause` for stack-trace
+ * continuity.
+ *
+ * - If `value` is already an `Error`, it is returned unchanged.
+ * - Otherwise the message is derived from `JSON.stringify(value)` when possible (which
+ *   carries more detail for plain objects), falling back to `String(value)` for
+ *   circular structures, BigInts, or anything else that fails to serialize.
+ */
+export const fromUnknown = (value: unknown): Error => {
+  if (value instanceof Error) return value;
+  let message: string;
+  try {
+    message = JSON.stringify(value) ?? String(value);
+  } catch {
+    message = String(value);
+  }
+  return new Error(message, { cause: value });
+};
+
 /** Constant representing an unknown error type */
 export const UNKNOWN = "unknown";
 
@@ -169,6 +191,18 @@ interface Provider {
   decode: Decoder;
 }
 
+const withNative = (payload: Payload, error: Error): Payload => ({
+  ...payload,
+  name: error.name,
+  stack: error.stack,
+});
+
+const applyNative = (error: Error, payload: Payload): Error => {
+  if (payload.name != null) error.name = payload.name;
+  if (payload.stack != null) error.stack = payload.stack;
+  return error;
+};
+
 class Registry {
   private readonly providers: Provider[] = [];
 
@@ -181,9 +215,10 @@ class Registry {
     if (isTyped(error))
       for (const provider of this.providers) {
         const payload = provider.encode(error);
-        if (payload != null) return payload;
+        if (payload != null) return withNative(payload, error);
       }
-    if (error instanceof Error) return { type: UNKNOWN, data: error.message };
+    if (error instanceof Error)
+      return withNative({ type: UNKNOWN, data: error.message }, error);
     if (typeof error === "string") return { type: UNKNOWN, data: error };
     try {
       return { type: UNKNOWN, data: JSON.stringify(error) };
@@ -194,12 +229,13 @@ class Registry {
 
   decode(payload?: Payload | null): Error | null {
     if (payload == null || payload.type === NONE) return null;
-    if (payload.type === UNKNOWN) return new Unknown(payload.data);
+    if (payload.type === UNKNOWN)
+      return applyNative(new Unknown(payload.data), payload);
     for (const provider of this.providers) {
       const error = provider.decode(payload);
-      if (error != null) return error;
+      if (error != null) return applyNative(error, payload);
     }
-    return new Unknown(payload.data);
+    return applyNative(new Unknown(payload.data), payload);
   }
 }
 
@@ -242,8 +278,16 @@ export const decode = (payload?: Payload | null): Error | null => {
  */
 export class Unknown extends createTyped("unknown") {}
 
-/** Zod schema for validating error payloads */
-export const payloadZ = z.object({ type: z.string(), data: z.string() });
+/** Zod schema for validating error payloads. `name` and `stack` are TypeScript-only
+ * fields; Go and Python don't populate them. They're carried opaquely across the wire
+ * and re-applied to the reconstructed error on decode, which keeps the original error
+ * name (e.g. "TypeError") and stack trace alive across worker / network boundaries. */
+export const payloadZ = z.object({
+  type: z.string(),
+  data: z.string(),
+  name: z.string().optional(),
+  stack: z.string().optional(),
+});
 
 /** Network-portable representation of an error */
 export type Payload = z.infer<typeof payloadZ>;
@@ -251,15 +295,5 @@ export type Payload = z.infer<typeof payloadZ>;
 /** Error for representing the cancellation of an operation */
 export class Canceled extends createTyped("canceled") {}
 
-/** A payload representing a native JavaScript Error */
-export interface NativePayload {
-  /** The name of the error */
-  name: string;
-  /** The message of the error */
-  message: string;
-  /** The stack trace of the error */
-  stack?: string;
-}
-
 /** Error for representing a method that is not implemented */
 export class NotImplemented extends createTyped("not_implemented") {}

package/src/index.ts

@@ -33,10 +33,12 @@ export * from "@/math";
 export * from "@/migrate";
 export * from "@/narrow";
 export * from "@/notation";
+export * from "@/numeric";
 export * from "@/observe";
 export * from "@/optional";
 export * from "@/primitive";
 export * from "@/record";
+export * from "@/require";
 export * from "@/runtime";
 export * from "@/scheduler";
 export * from "@/shallow";
@@ -47,9 +49,10 @@ export * from "@/strings";
 export * from "@/sync";
 export * from "@/telem";
 export * from "@/testutil";
+export * from "@/text";
+export * from "@/throttle";
 export * from "@/types";
 export * from "@/unique";
 export * from "@/url";
 export * from "@/uuid";
-export * from "@/worker";
 export * from "@/zod";

package/src/migrate/migrate.ts

@@ -10,6 +10,7 @@
 import { z } from "zod";
 
 import { compare } from "@/compare";
+import { errors } from "@/errors";
 import { type optional } from "@/optional";
 
 export const semVerZ = z
@@ -203,7 +204,7 @@ export const createMigration =
     } catch (e) {
       console.log(`${name} failed to migrate from ${input.version}`);
       console.error(e);
-      throw e;
+      throw errors.fromUnknown(e);
     }
   };
 

package/src/notation/external.ts

@@ -0,0 +1,11 @@
+// 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 * from "@/notation/notation";
+export { type Notation, NOTATIONS, notationZ } from "@/notation/types.gen";

package/src/notation/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as notation from "@/notation/notation";
+export * as notation from "@/notation/external";