@exodus/errors 3.3.0 → 3.5.0

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.5.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.4.0...@exodus/errors@3.5.0) (2025-11-04)
+
+### Features
+
+- feat: allow exporting `traceId` in errors context (#14099)
+
+- feat: handle `cause` properties of errors (#14307)
+
+## [3.4.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.3.0...@exodus/errors@3.4.0) (2025-10-14)
+
+### Features
+
+- feat: support capturing error context (#13933)
+
 ## [3.3.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.2.0...@exodus/errors@3.3.0) (2025-08-08)
 
 ### Features

package/lib/index.d.ts

@@ -1,3 +1,4 @@
 export { default as sanitizeErrorMessage } from './sanitize.js';
 export { default as parseStackTrace, captureStackTrace } from './stack.js';
 export * from './safe-error.js';
+export { SafeContext, type SafeContextType } from './safe-context/index.js';

package/lib/index.js

@@ -1,3 +1,4 @@
 export { default as sanitizeErrorMessage } from './sanitize.js';
 export { default as parseStackTrace, captureStackTrace } from './stack.js';
 export * from './safe-error.js';
+export { SafeContext } from './safe-context/index.js';

package/lib/safe-context/index.d.ts

@@ -0,0 +1,30 @@
+import { type SafeContextType } from './schemas.js';
+export declare const SafeContext: {
+    parse(unsafeContext: unknown): SafeContextType;
+    getSchema: () => ReturnType<() => import("@exodus/zod").ZodOptional<import("@exodus/zod").ZodNullable<import("@exodus/zod").ZodObject<{
+        navigation: import("@exodus/zod").ZodOptional<import("@exodus/zod").ZodNullable<import("@exodus/zod").ZodObject<{
+            currentRouteName: import("@exodus/zod").ZodEffects<import("@exodus/zod").ZodString, string, string>;
+            previousRouteName: import("@exodus/zod").ZodOptional<import("@exodus/zod").ZodNullable<import("@exodus/zod").ZodEffects<import("@exodus/zod").ZodString, string, string>>>;
+        }, "strict", import("@exodus/zod").ZodTypeAny, {
+            currentRouteName: string;
+            previousRouteName?: string | null | undefined;
+        }, {
+            currentRouteName: string;
+            previousRouteName?: string | null | undefined;
+        }>>>;
+        traceId: import("@exodus/zod").ZodOptional<import("@exodus/zod").ZodNullable<import("@exodus/zod").ZodEffects<import("@exodus/zod").ZodString, string, string>>>;
+    }, "strict", import("@exodus/zod").ZodTypeAny, {
+        navigation?: {
+            currentRouteName: string;
+            previousRouteName?: string | null | undefined;
+        } | null | undefined;
+        traceId?: string | null | undefined;
+    }, {
+        navigation?: {
+            currentRouteName: string;
+            previousRouteName?: string | null | undefined;
+        } | null | undefined;
+        traceId?: string | null | undefined;
+    }>>>>;
+};
+export type { SafeContextType } from './schemas.js';

package/lib/safe-context/index.js

@@ -0,0 +1,12 @@
+import { getContextSchema } from './schemas.js';
+export const SafeContext = {
+    parse(unsafeContext) {
+        try {
+            return getContextSchema().parse(unsafeContext);
+        }
+        catch {
+            return undefined;
+        }
+    },
+    getSchema: getContextSchema,
+};

package/lib/safe-context/schemas.d.ts

@@ -0,0 +1,29 @@
+import { z } from '@exodus/zod';
+declare const createContextSchema: () => z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    navigation: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        currentRouteName: z.ZodEffects<z.ZodString, string, string>;
+        previousRouteName: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+    }, "strict", z.ZodTypeAny, {
+        currentRouteName: string;
+        previousRouteName?: string | null | undefined;
+    }, {
+        currentRouteName: string;
+        previousRouteName?: string | null | undefined;
+    }>>>;
+    traceId: z.ZodOptional<z.ZodNullable<z.ZodEffects<z.ZodString, string, string>>>;
+}, "strict", z.ZodTypeAny, {
+    navigation?: {
+        currentRouteName: string;
+        previousRouteName?: string | null | undefined;
+    } | null | undefined;
+    traceId?: string | null | undefined;
+}, {
+    navigation?: {
+        currentRouteName: string;
+        previousRouteName?: string | null | undefined;
+    } | null | undefined;
+    traceId?: string | null | undefined;
+}>>>;
+declare const getContextSchema: () => ReturnType<typeof createContextSchema>;
+export type SafeContextType = z.infer<ReturnType<typeof createContextSchema>>;
+export { getContextSchema };

package/lib/safe-context/schemas.js

@@ -0,0 +1,19 @@
+import { z } from '@exodus/zod';
+import { isSafe } from '@exodus/safe-string';
+import { memoize } from '@exodus/basic-utils';
+const createContextSchema = () => z
+    .object({
+    navigation: z
+        .object({
+        currentRouteName: z.string().refine(isSafe),
+        previousRouteName: z.string().refine(isSafe).nullish(),
+    })
+        .strict()
+        .nullish(),
+    traceId: z.string().refine(isSafe).nullish(),
+})
+    .strict()
+    .nullish();
+// Memoize the factory for lazy loading.
+const getContextSchema = memoize(createContextSchema);
+export { getContextSchema };

package/lib/safe-error.d.ts

@@ -1,5 +1,6 @@
 import type { Frame } from './types.js';
 import type { CommonErrorString } from './common-errors.js';
+export declare const MAX_LINKED_ERRORS_DEPTH = 5;
 type ReadonlySetValues<S> = S extends ReadonlySet<infer T> ? T : never;
 declare const SAFE_NAMES_SET: ReadonlySet<"Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError" | "SyntaxError">;
 type StaticAllowlistString = string & {
@@ -13,14 +14,23 @@ export type SafeCode = string & {
     __branded_type: 'SafeCodeOutcome';
 };
 export type SafeString = CommonErrorString | StaticAllowlistString | RuntimeSafeString;
+export type SafeErrorJSON = {
+    name: SafeName;
+    code?: SafeCode;
+    hint?: SafeString;
+    stack?: string;
+    linkedErrors?: SafeErrorJSON[];
+    timestamp: number;
+};
 type UnknownError = Error & {
     hint?: unknown;
     code?: unknown;
+    cause?: unknown;
 };
 declare const FACTORY_SYMBOL: unique symbol;
 export declare class SafeError {
     #private;
-    static from<T extends UnknownError>(err: T): SafeError;
+    static from<T extends UnknownError>(err: T, depth?: number): SafeError;
     get name(): "Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse" | "TimeoutError" | "SyntaxError";
     get code(): SafeCode | undefined;
     get hint(): SafeString | undefined;
@@ -36,19 +46,15 @@ export declare class SafeError {
         __proto__: null;
     }[] | undefined;
     get stack(): string | undefined;
+    get linkedErrors(): SafeError[] | undefined;
     get timestamp(): number;
-    toJSON(): {
-        name: SafeName;
-        code?: SafeCode;
-        hint?: SafeString;
-        stack?: string;
-        timestamp: number;
-    };
-    constructor({ name, code, hint, stack, initSymbol, }: {
+    toJSON(): SafeErrorJSON;
+    constructor({ name, code, hint, stack, linkedErrors, initSymbol, }: {
         name: SafeName;
         code?: SafeCode;
         hint?: SafeString;
         stack?: Frame[];
+        linkedErrors?: SafeError[];
         initSymbol: typeof FACTORY_SYMBOL;
     });
 }

package/lib/safe-error.js

@@ -3,6 +3,7 @@ import assert from 'minimalistic-assert';
 import parseStackTraceNatively, { stackFramesToString } from './stack.js';
 import { omitUndefined } from './utils.js';
 import { toCommonErrorMessage } from './common-errors.js';
+export const MAX_LINKED_ERRORS_DEPTH = 5;
 function makeReadonlySet(values) {
     return new Set(values);
 }
@@ -29,12 +30,13 @@ function isSafeCode(value) {
 const staticAllowlist = getAllowlist();
 const FACTORY_SYMBOL = Symbol('SafeError');
 export class SafeError {
-    static from(err) {
+    static from(err, depth = 0) {
         let safeName;
         let safeCode;
         let safeHint;
+        let linkedSafeErrors;
         try {
-            const { name, message, hint, code } = err;
+            const { name, message, hint, code, cause } = err;
             safeName = isSafeName(name) ? name : 'UnknownError';
             const safeCodeCandidate = `${code}`;
             safeCode = isSafeCode(safeCodeCandidate) ? safeCodeCandidate : undefined;
@@ -45,11 +47,27 @@ export class SafeError {
                     staticAllowlist.find((safePrefix) => hintCandidates.some((str) => str.startsWith(safePrefix))) ||
                     toCommonErrorMessage(message);
             const safeStack = parseStackTraceNatively(err);
+            if (cause instanceof Error && depth === 0) {
+                linkedSafeErrors = [];
+                let currentCause = cause;
+                while (currentCause instanceof Error && ++depth <= MAX_LINKED_ERRORS_DEPTH) {
+                    try {
+                        linkedSafeErrors.push(SafeError.from(currentCause, depth));
+                    }
+                    catch {
+                        linkedSafeErrors.push(FAILED_TO_PARSE_ERROR);
+                    }
+                    finally {
+                        currentCause = currentCause.cause;
+                    }
+                }
+            }
             return new SafeError({
                 name: safeName,
                 code: safeCode,
                 hint: safeHint,
                 stack: safeStack,
+                linkedErrors: linkedSafeErrors,
                 initSymbol: FACTORY_SYMBOL,
             });
         }
@@ -60,6 +78,7 @@ export class SafeError {
                         name: safeName,
                         code: safeCode,
                         hint: safeHint,
+                        linkedErrors: linkedSafeErrors,
                         initSymbol: FACTORY_SYMBOL,
                     })
                     : FAILED_TO_PARSE_ERROR;
@@ -73,6 +92,7 @@ export class SafeError {
     #code;
     #hint;
     #stackFrames;
+    #linkedErrors;
     #timestamp;
     get name() {
         return this.#name;
@@ -92,6 +112,9 @@ export class SafeError {
             ? `${this.name}: ${this.code || this.hint || 'unknownHint'}\n${stackTrace}`
             : undefined;
     }
+    get linkedErrors() {
+        return this.#linkedErrors;
+    }
     get timestamp() {
         return this.#timestamp;
     }
@@ -102,15 +125,17 @@ export class SafeError {
             code: this.code,
             hint: this.hint,
             stack: this.stack,
+            linkedErrors: this.linkedErrors?.map((linkedError) => linkedError.toJSON()),
             timestamp: this.timestamp,
         });
     }
-    constructor({ name, code, hint, stack, initSymbol, }) {
+    constructor({ name, code, hint, stack, linkedErrors, initSymbol, }) {
         assert(initSymbol === FACTORY_SYMBOL, 'SafeError: use SafeError.from()');
         this.#name = name;
         this.#code = code;
         this.#hint = hint;
         this.#stackFrames = stack?.map((frame) => ({ ...frame }));
+        this.#linkedErrors = linkedErrors;
         this.#timestamp = Date.now();
     }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -34,7 +34,9 @@
     "test:hermes": "EXODUS_TEST_COVERAGE=0 run -T exodus-test --engine hermes:bundle --esbuild --jest src/__tests__/hermes/*.test.ts src/__tests__/engine-agnostic/*.test.ts"
   },
   "dependencies": {
+    "@exodus/basic-utils": "^3.0.1",
     "@exodus/safe-string": "^1.2.0",
+    "@exodus/zod": "^3.24.2",
     "minimalistic-assert": "^1.0.1"
   },
   "devDependencies": {
@@ -42,7 +44,8 @@
     "@types/minimalistic-assert": "^1.0.1"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": false
   },
-  "gitHead": "15487091c1c6bd495e315ea164df34fb314ee156"
+  "gitHead": "32d28daa40c3e8c600440732d2792699448e1be8"
 }