@synnaxlabs/x 0.56.0 → 0.56.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synnaxlabs/x",
-  "version": "0.56.0",
+  "version": "0.56.1",
   "type": "module",
   "description": "Common Utilities for Synnax Labs",
   "repository": "https://github.com/synnaxlabs/synnax/tree/main/x/ts",
@@ -26,9 +26,9 @@
     "typescript": "^6.0.3",
     "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/tsconfig": "^0.0.0"
+    "@synnaxlabs/eslint-config": "^0.0.0"
   },
   "main": "dist/x.cjs",
   "module": "dist/x.js",

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/errors/errors.spec.ts

@@ -128,6 +128,98 @@ describe("errors", () => {
     });
   });
 
+  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", () => {
     it("should return true if the errors are exactly the same", () => {
       const v = new ErrorOne("test");

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";
 

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/status/status.spec.ts

@@ -110,9 +110,24 @@ describe("status", () => {
       expect(s.details.error).toBe(error);
     });
 
-    it("should throw when exception is not an Error instance", () => {
+    it("should coerce a non-Error throwable into an error status via fromUnknown", () => {
       const notAnError = "just a string";
-      expect(() => status.fromException(notAnError)).toThrow("just a string");
+      const s = status.fromException(notAnError);
+      expect(s.variant).toEqual("error");
+      // JSON.stringify of a string quotes it.
+      expect(s.message).toEqual('"just a string"');
+      expect(s.details.error).toBeInstanceOf(Error);
+      expect(s.details.error.cause).toEqual("just a string");
+    });
+
+    it("should pick up custom toStatus contributions from non-Error throwables", () => {
+      const custom = {
+        toStatus: () => ({ message: "custom msg", description: "custom desc" }),
+      };
+      const s = status.fromException(custom);
+      expect(s.variant).toEqual("error");
+      expect(s.message).toEqual("custom msg");
+      expect(s.description).toEqual("custom desc");
     });
 
     it("should include valid key and timestamp", () => {

package/src/status/status.ts

@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 
+import { errors } from "@/errors";
 import { id } from "@/id";
 import { narrow } from "@/narrow";
 import { type optional } from "@/optional";
@@ -52,11 +53,14 @@ const customReturnZ = z.object({
   details: record.unknownZ().optional(),
 });
 
-const hasToStatusMethod = (exc: Error): exc is Error & { toStatus: () => unknown } =>
-  "toStatus" in exc && typeof (exc as { toStatus: unknown }).toStatus === "function";
-
-const safeToStatus = (exc: Error): z.infer<typeof customReturnZ> | undefined => {
-  if (!hasToStatusMethod(exc)) return undefined;
+const safeToStatus = (exc: unknown): z.infer<typeof customReturnZ> | undefined => {
+  if (
+    exc == null ||
+    typeof exc !== "object" ||
+    !("toStatus" in exc) ||
+    typeof exc.toStatus !== "function"
+  )
+    return undefined;
   let raw: unknown;
   try {
     raw = exc.toStatus();
@@ -78,13 +82,15 @@ export const fromException = (
   exc: unknown,
   message?: string,
 ): Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">> => {
-  if (!(exc instanceof Error)) throw exc;
+  const err = errors.fromUnknown(exc);
   const crude: Crude<typeof exceptionDetailsSchema, "error"> = {
     variant: "error",
-    message: message ?? exc.message,
-    description: message != null ? exc.message : undefined,
-    details: { stack: exc.stack ?? "", error: exc },
+    message: message ?? err.message,
+    description: message != null ? err.message : undefined,
+    details: { stack: err.stack ?? "", error: err },
   };
+  // Probe the original (pre-coercion) value so a non-Error throwable with a custom
+  // `toStatus()` method still contributes its status fields.
   const custom = safeToStatus(exc);
   if (custom != null) {
     if (message != null && custom.message != null)