@exodus/errors 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [1.2.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@1.1.1...@exodus/errors@1.2.0) (2025-02-12)
+
+### Features
+
+- feat(errors): any error to SafeError conversion capability (#9918)
+
 ## [1.1.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@1.1.0...@exodus/errors@1.1.1) (2024-12-20)
 
 ### License

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/safe-error.d.ts

@@ -0,0 +1,77 @@
+import type { Frame } from './types.js';
+type ReadonlySetValues<S> = S extends ReadonlySet<infer T> ? T : never;
+declare const SAFE_NAMES_SET: ReadonlySet<"Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse">;
+declare const SAFE_HINTS_SET: ReadonlySet<"broadcastTx" | "otherErr:broadcastTx" | "retry:broadcastTx" | "getNftArguments" | "ethCall" | "ethCall:executionReverted" | "failed to parse error">;
+type SafeName = ReadonlySetValues<typeof SAFE_NAMES_SET>;
+type SafeHint = ReadonlySetValues<typeof SAFE_HINTS_SET>;
+type SafeCode = string & {
+    __branded_type: 'SafeCodeOutcome';
+};
+type UnknownError = Error & {
+    hint?: unknown;
+    code?: unknown;
+};
+declare const FACTORY_SYMBOL: unique symbol;
+export declare class SafeError {
+    #private;
+    static readonly hints: {
+        readonly __proto__: null;
+        readonly broadcastTx: {
+            readonly general: "broadcastTx";
+            readonly other: "otherErr:broadcastTx";
+            readonly retry: "retry:broadcastTx";
+        };
+        readonly getNftArguments: {
+            readonly general: "getNftArguments";
+        };
+        readonly ethCall: {
+            readonly general: "ethCall";
+            readonly executionReverted: "ethCall:executionReverted";
+        };
+        readonly safeError: {
+            readonly failedToParse: "failed to parse error";
+        };
+    };
+    static from<T extends UnknownError>(err: T): SafeError;
+    get name(): "Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse";
+    get code(): SafeCode | undefined;
+    get hint(): "broadcastTx" | "otherErr:broadcastTx" | "retry:broadcastTx" | "getNftArguments" | "ethCall" | "ethCall:executionReverted" | "failed to parse error" | undefined;
+    get stackFrames(): {
+        function?: string | null;
+        method?: string | null;
+        file?: string | null;
+        line?: number | null;
+        column?: number | null;
+        async?: boolean | null;
+        toplevel?: boolean | null;
+        in_app?: boolean | null;
+        __proto__: null;
+    }[] | undefined;
+    get timestamp(): number;
+    toJSON(): {
+        __proto__: null;
+        name: "Error" | "AssertionError" | "TypeError" | "RangeError" | "UnknownError" | "SafeErrorFailedToParse";
+        code: SafeCode | undefined;
+        hint: "broadcastTx" | "otherErr:broadcastTx" | "retry:broadcastTx" | "getNftArguments" | "ethCall" | "ethCall:executionReverted" | "failed to parse error" | undefined;
+        stackFrames: {
+            function?: string | null;
+            method?: string | null;
+            file?: string | null;
+            line?: number | null;
+            column?: number | null;
+            async?: boolean | null;
+            toplevel?: boolean | null;
+            in_app?: boolean | null;
+            __proto__: null;
+        }[] | undefined;
+        timestamp: number;
+    };
+    constructor({ name, code, hint, stack, initSymbol, }: {
+        name: SafeName;
+        code?: SafeCode;
+        hint?: SafeHint;
+        stack?: Frame[];
+        initSymbol: typeof FACTORY_SYMBOL;
+    });
+}
+export {};

package/lib/safe-error.js

@@ -0,0 +1,140 @@
+import assert from 'minimalistic-assert';
+import parseStackTraceNatively from './stack.js';
+function makeReadonlySet(values) {
+    return new Set(values);
+}
+const SAFE_CODES_SET = makeReadonlySet(['EPIPE']);
+const SAFE_NAMES_SET = makeReadonlySet([
+    'Error',
+    'AssertionError',
+    'TypeError',
+    'RangeError',
+    'UnknownError',
+    'SafeErrorFailedToParse',
+]);
+const safeHints = {
+    __proto__: null,
+    broadcastTx: {
+        general: 'broadcastTx',
+        other: 'otherErr:broadcastTx',
+        retry: 'retry:broadcastTx',
+    },
+    getNftArguments: {
+        general: 'getNftArguments',
+    },
+    ethCall: {
+        general: 'ethCall',
+        executionReverted: 'ethCall:executionReverted',
+    },
+    safeError: {
+        failedToParse: 'failed to parse error',
+    },
+};
+const SAFE_HINTS_SET = makeReadonlySet(
+// @ts-expect-error doesn't like __proto__: null
+Object.values(safeHints).flatMap((safeHintCategory) => Object.values(safeHintCategory)));
+function getSafeHint(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    if (value === '') {
+        return undefined;
+    }
+    if (isSafeHint(value)) {
+        return value;
+    }
+    return [...SAFE_HINTS_SET].find((sh) => value.includes(sh));
+}
+function isSafeHint(value) {
+    return SAFE_HINTS_SET.has(value);
+}
+function isSafeName(value) {
+    return SAFE_NAMES_SET.has(value);
+}
+function isExodusErrorCode(code) {
+    return /^EXOD-\d{1,4}$/u.test(code);
+}
+function isSafeCode(value) {
+    return SAFE_CODES_SET.has(value) || isExodusErrorCode(value);
+}
+const FACTORY_SYMBOL = Symbol('SafeError');
+export class SafeError {
+    static hints = safeHints;
+    static from(err) {
+        let safeName;
+        let safeCode;
+        let safeHint;
+        try {
+            const { name, message, hint, code } = err;
+            safeName = isSafeName(name) ? name : 'UnknownError';
+            const safeCodeCandidate = `${code}`;
+            safeCode = isSafeCode(safeCodeCandidate) ? safeCodeCandidate : undefined;
+            safeHint = getSafeHint(hint) || getSafeHint(message);
+            const safeStack = parseStackTraceNatively(err);
+            return new SafeError({
+                name: safeName,
+                code: safeCode,
+                hint: safeHint,
+                stack: safeStack,
+                initSymbol: FACTORY_SYMBOL,
+            });
+        }
+        catch {
+            try {
+                return safeName
+                    ? new SafeError({
+                        name: safeName,
+                        code: safeCode,
+                        hint: safeHint,
+                        initSymbol: FACTORY_SYMBOL,
+                    })
+                    : FAILED_TO_PARSE_ERROR;
+            }
+            catch {
+                return FAILED_TO_PARSE_ERROR;
+            }
+        }
+    }
+    #name;
+    #code;
+    #hint;
+    #stackFrames;
+    #timestamp;
+    get name() {
+        return this.#name;
+    }
+    get code() {
+        return this.#code;
+    }
+    get hint() {
+        return this.#hint;
+    }
+    get stackFrames() {
+        return this.#stackFrames?.map((frame) => ({ __proto__: null, ...frame }));
+    }
+    get timestamp() {
+        return this.#timestamp;
+    }
+    toJSON() {
+        return {
+            __proto__: null,
+            name: this.name,
+            code: this.code,
+            hint: this.hint,
+            stackFrames: this.stackFrames,
+            timestamp: this.timestamp,
+        };
+    }
+    constructor({ name, code, hint, stack, 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.#timestamp = Date.now();
+    }
+}
+const FAILED_TO_PARSE_ERROR = new SafeError({
+    initSymbol: FACTORY_SYMBOL,
+    name: 'SafeErrorFailedToParse',
+});

package/lib/types.d.ts

@@ -1,10 +1,10 @@
 export type Frame = {
-    function?: string;
-    method?: string;
-    file?: string;
-    line?: number;
-    column?: number;
-    async?: boolean;
-    toplevel?: boolean;
-    in_app?: boolean;
+    function?: string | null;
+    method?: string | null;
+    file?: string | null;
+    line?: number | null;
+    column?: number | null;
+    async?: boolean | null;
+    toplevel?: boolean | null;
+    in_app?: boolean | null;
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -33,12 +33,16 @@
     "test:v8": "run -T exodus-test --esbuild --jest src/__tests__/v8/*.test.ts",
     "test:hermes": "EXODUS_TEST_COVERAGE=0 run -T exodus-test --engine hermes:bundle --esbuild --jest src/__tests__/hermes/*.test.ts"
   },
+  "dependencies": {
+    "minimalistic-assert": "^1.0.1"
+  },
   "devDependencies": {
     "@exodus/errors-fixture": "^1.0.0",
+    "@types/minimalistic-assert": "^1.0.1",
     "hermes-engine-cli": "^0.12.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "9cef1436f1cf2fa9afa1672954ea92c63a8e0f16"
+  "gitHead": "3f98f500b3b5289ff3e38a8c8385c164b4ee8a5e"
 }