@synnaxlabs/x 0.54.1 → 0.54.2

package/src/primitive/primitive.spec.ts

@@ -64,6 +64,57 @@ describe("primitive", () => {
     });
   });
 
+  describe("is", () => {
+    it("should return true for null and undefined", () => {
+      expect(primitive.is(null)).toBe(true);
+      expect(primitive.is(undefined)).toBe(true);
+    });
+
+    it("should return true for strings", () => {
+      expect(primitive.is("")).toBe(true);
+      expect(primitive.is("hello")).toBe(true);
+    });
+
+    it("should return true for numbers", () => {
+      expect(primitive.is(0)).toBe(true);
+      expect(primitive.is(3.14)).toBe(true);
+      expect(primitive.is(NaN)).toBe(true);
+    });
+
+    it("should return true for booleans", () => {
+      expect(primitive.is(true)).toBe(true);
+      expect(primitive.is(false)).toBe(true);
+    });
+
+    it("should return true for bigints", () => {
+      expect(primitive.is(42n)).toBe(true);
+    });
+
+    it("should return true for symbols", () => {
+      expect(primitive.is(Symbol("x"))).toBe(true);
+    });
+
+    it("should return false for plain objects", () => {
+      expect(primitive.is({})).toBe(false);
+      expect(primitive.is({ a: 1 })).toBe(false);
+    });
+
+    it("should return false for arrays", () => {
+      expect(primitive.is([])).toBe(false);
+      expect(primitive.is([1, 2, 3])).toBe(false);
+    });
+
+    it("should return false for class instances", () => {
+      expect(primitive.is(new Date())).toBe(false);
+      expect(primitive.is(new Map())).toBe(false);
+      expect(primitive.is(new Error())).toBe(false);
+    });
+
+    it("should return false for functions", () => {
+      expect(primitive.is(() => 1)).toBe(false);
+    });
+  });
+
   describe("ValueExtension", () => {
     class MyValueExtension extends primitive.ValueExtension<bigint> {
       valueOf(): bigint {

package/src/primitive/primitive.ts

@@ -105,3 +105,15 @@ export const isZero = <V extends Value>(value: V): value is V & ZeroValue => {
  */
 export const isNonZero = <V extends Value>(value: V): value is V & NonZeroValue =>
   !isZero(value);
+
+/**
+ * @returns true if the given value is a JavaScript primitive: `null`, `undefined`,
+ * or a value whose `typeof` is not `"object"` or `"function"`. Returns false for
+ * objects (including arrays), functions, and class instances.
+ *
+ * Complements {@link isZero} and {@link isNonZero}, which check for the zero value
+ * of a known primitive type. Use `is` when you have an `unknown` value and want to
+ * decide whether to render it inline vs. recurse into it.
+ */
+export const is = (value: unknown): boolean =>
+  value == null || (typeof value !== "object" && typeof value !== "function");

package/src/status/status.spec.ts

@@ -14,6 +14,8 @@ import { id } from "@/id";
 import { status } from "@/status";
 import { TimeStamp } from "@/telem";
 
+type CustomCrude = Partial<status.Crude<z.ZodRecord, "error">>;
+
 describe("status", () => {
   describe("create", () => {
     it("should create a status", () => {
@@ -129,6 +131,117 @@ describe("status", () => {
       const result = status.exceptionDetailsSchema.safeParse(s.details);
       expect(result.success).toBe(true);
     });
+
+    describe("custom errors (toStatus)", () => {
+      class CustomError extends Error implements status.Custom {
+        constructor(message: string) {
+          super(message);
+          this.name = "CustomError";
+        }
+
+        toStatus(): CustomCrude {
+          return {
+            message: "custom headline",
+            description: "custom description body",
+            details: { code: 42, hint: "try again" },
+          };
+        }
+      }
+
+      it("should use toStatus.message as the status message", () => {
+        const s = status.fromException(new CustomError("raw"));
+        expect(s.message).toBe("custom headline");
+      });
+
+      it("should use toStatus.description as the status description", () => {
+        const s = status.fromException(new CustomError("raw"));
+        expect(s.description).toBe("custom description body");
+      });
+
+      it("should merge toStatus.details into status.details", () => {
+        const s = status.fromException(new CustomError("raw"));
+        const details = s.details as Record<string, unknown>;
+        expect(details.code).toBe(42);
+        expect(details.hint).toBe("try again");
+        expect(details.stack).toBeDefined();
+        expect(details.error).toBeInstanceOf(Error);
+      });
+
+      it("should prefix toStatus.message when the caller provides a custom message", () => {
+        const s = status.fromException(new CustomError("raw"), "Saving failed");
+        expect(s.message).toBe("Saving failed: custom headline");
+      });
+
+      it("should fall through to the default path for errors without toStatus", () => {
+        const s = status.fromException(new Error("plain"));
+        expect(s.message).toBe("plain");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it throws", () => {
+        class Bad extends Error {
+          toStatus() {
+            throw new Error("explode");
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it returns a non-object", () => {
+        class Bad extends Error {
+          toStatus() {
+            return "nope" as unknown as CustomCrude;
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+      });
+
+      it("should ignore toStatus if it returns null", () => {
+        class Bad extends Error {
+          toStatus() {
+            return null as unknown as CustomCrude;
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+      });
+
+      it("should ignore individual fields with the wrong type", () => {
+        class Bad extends Error {
+          toStatus() {
+            return {
+              message: 42 as unknown as string,
+              description: { not: "a string" } as unknown as string,
+              details: "also not a record" as unknown as Record<string, unknown>,
+            };
+          }
+        }
+        const s = status.fromException(new Bad("fallback"));
+        expect(s.message).toBe("fallback");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should accept a partial return with only some valid fields", () => {
+        class Partial extends Error {
+          toStatus() {
+            return { message: "only headline" };
+          }
+        }
+        const s = status.fromException(new Partial("raw"));
+        expect(s.message).toBe("only headline");
+        expect(s.description).toBeUndefined();
+      });
+
+      it("should ignore toStatus if it is not a function", () => {
+        const err = new Error("fallback") as Error & { toStatus: string };
+        err.toStatus = "not a function";
+        const s = status.fromException(err);
+        expect(s.message).toBe("fallback");
+      });
+    });
   });
 
   describe("toString", () => {
@@ -301,5 +414,38 @@ describe("status", () => {
       const result = status.toString(s);
       expect(result).toContain("cat");
     });
+
+    describe("custom errors (toStatus)", () => {
+      class CustomError extends Error implements status.Custom {
+        constructor() {
+          super("raw");
+          this.name = "CustomError";
+        }
+
+        toStatus(): CustomCrude {
+          return {
+            message: "custom headline",
+            description: "line one\nline two\nline three",
+            details: { code: 42 },
+          };
+        }
+      }
+
+      it("should render the toStatus headline as the status message", () => {
+        const s = status.fromException(new CustomError());
+        expect(status.toString(s)).toContain("ERROR: custom headline");
+      });
+
+      it("should render a multi-line description on its own block", () => {
+        const out = status.toString(status.fromException(new CustomError()));
+        expect(out).toContain("Description:\nline one\nline two\nline three");
+      });
+
+      it("should include merged details under the Details section", () => {
+        const out = status.toString(status.fromException(new CustomError()));
+        expect(out).toContain("Details:");
+        expect(out).toContain('"code": 42');
+      });
+    });
   });
 });

package/src/status/status.ts

@@ -13,6 +13,7 @@ import { id } from "@/id";
 import { narrow } from "@/narrow";
 import { type optional } from "@/optional";
 import { primitive } from "@/primitive";
+import { record } from "@/record";
 import { type Status, type Variant } from "@/status/types.gen";
 import { TimeStamp } from "@/telem";
 
@@ -32,22 +33,68 @@ export type Crude<
 > = optional.Optional<Base<V>, "key" | "time" | "name"> &
   ([DetailsSchema] extends [z.ZodNever] ? {} : { details: z.output<DetailsSchema> });
 
-export const exceptionDetailsSchema = z.object({
-  stack: z.string(),
-  error: z.instanceof(Error),
+/**
+ * Interface that errors may optionally implement to provide richer rendering when
+ * passed to {@link fromException}. Implementers return a partial {@link Crude} spec
+ * whose fields override the defaults derived from the underlying `Error`.
+ *
+ * This is a duck-typed contract: `fromException` checks for the presence of a
+ * `toStatus` method via the `in` operator, so there is no need to import this
+ * interface to use it.
+ */
+export interface Custom {
+  toStatus(): Partial<Crude<z.ZodRecord, "error">>;
+}
+
+const customReturnZ = z.object({
+  message: z.string().optional(),
+  description: z.string().optional(),
+  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;
+  let raw: unknown;
+  try {
+    raw = exc.toStatus();
+  } catch {
+    return undefined;
+  }
+  const parsed = customReturnZ.safeParse(raw);
+  return parsed.success ? parsed.data : undefined;
+};
+
+export const exceptionDetailsSchema = z
+  .object({
+    stack: z.string(),
+    error: z.instanceof(Error),
+  })
+  .and(record.unknownZ());
+
 export const fromException = (
   exc: unknown,
   message?: string,
 ): Status<typeof exceptionDetailsSchema, z.ZodLiteral<"error">> => {
   if (!(exc instanceof Error)) throw exc;
-  return create<typeof exceptionDetailsSchema, "error">({
+  const crude: Crude<typeof exceptionDetailsSchema, "error"> = {
     variant: "error",
     message: message ?? exc.message,
     description: message != null ? exc.message : undefined,
     details: { stack: exc.stack ?? "", error: exc },
-  });
+  };
+  const custom = safeToStatus(exc);
+  if (custom != null) {
+    if (message != null && custom.message != null)
+      crude.message = `${message}: ${custom.message}`;
+    else if (custom.message != null) crude.message = custom.message;
+    if (custom.description != null) crude.description = custom.description;
+    if (custom.details != null && crude.details != null)
+      crude.details = { ...crude.details, ...custom.details };
+  }
+  return create<typeof exceptionDetailsSchema, "error">(crude);
 };
 
 export const create = <
@@ -97,6 +144,16 @@ const DEFAULT_TO_STRING_OPTIONS: ToStringOptions = {
   includeName: true,
 };
 
+const renderDescription = (description: string): string => {
+  if (description.includes("\n")) return `Description:\n${description}`;
+  try {
+    const parsed = JSON.parse(description);
+    return `Description:\n${JSON.stringify(parsed, null, 2)}`;
+  } catch {
+    return `Description: ${description}`;
+  }
+};
+
 export const toString = <Details extends z.ZodType = z.ZodNever>(
   stat: Status<Details>,
   options: ToStringOptions = {},
@@ -108,21 +165,11 @@ export const toString = <Details extends z.ZodType = z.ZodNever>(
   header += `: ${stat.message}`;
   if (opts.includeTimestamp) header += ` (${stat.time.toString("dateTime", "local")})`;
   parts.push(header);
-  if (stat.description != null) {
-    let descriptionText: string;
-    try {
-      const parsed = JSON.parse(stat.description);
-      descriptionText = `Description:\n${JSON.stringify(parsed, null, 2)}`;
-    } catch {
-      descriptionText = `Description: ${stat.description}`;
-    }
-    parts.push(descriptionText);
-  }
+  if (stat.description != null) parts.push(renderDescription(stat.description));
   if ("details" in stat && narrow.isObject(stat.details)) {
     const details = stat.details as Record<string, unknown>;
-    // Extract stack trace separately for special formatting
-    if ("stack" in details) parts.push(`Stack Trace:\n${String(details.stack)}`);
-    // Include other details (excluding stack and error which don't serialize well)
+    if ("stack" in details && typeof details.stack === "string" && details.stack !== "")
+      parts.push(`Stack Trace:\n${details.stack}`);
     const extraDetails = Object.fromEntries(
       Object.entries(details).filter(([k]) => k !== "stack" && k !== "error"),
     );

package/src/zod/external.ts

@@ -8,6 +8,7 @@
 // included in the file licenses/APL.txt.
 
 export * from "@/zod/nullToUndefined";
+export * from "@/zod/parse";
 export * from "@/zod/schemas";
 export * from "@/zod/toArray";
 export * from "@/zod/util";