@exodus/errors 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 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
+
+- license: re-license under MIT license (#10599)
+
 ## [1.1.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@1.0.1...@exodus/errors@1.1.0) (2024-08-19)
 
 ### Features

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Exodus Movement, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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/sanitize.js

@@ -1,13 +1,13 @@
 const sanitizeErrorMessage = (message) => message
     // 12 word phrase
-    .replaceAll(/(?:[A-Za-z]{3,20}\s+){11}[A-Za-z]{3,20}/g, '****')
+    .replaceAll(/(?:[A-Za-z]{3,20}\s+){11}[A-Za-z]{3,20}/gu, '****')
     // hex
-    .replaceAll(/(?:0x)?[\dA-Fa-f]{20,}/g, '****')
+    .replaceAll(/(?:0x)?[\dA-Fa-f]{20,}/gu, '****')
     // base58
     // https://stackoverflow.com/a/33060399
-    .replaceAll(/[1-9A-HJ-NP-Za-km-z]{50,}/g, '****')
+    .replaceAll(/[1-9A-HJ-NP-Za-km-z]{50,}/gu, '****')
     // base64
     // adapted from https://stackoverflow.com/a/5885097
     // added `{3,}` to match at least 12 characters
-    .replaceAll(/(?:[\d+/A-Za-z]{4}){3,}(?:[\d+/A-Za-z]{2}==|[\d+/A-Za-z]{3}=|[\d+/A-Za-z]{4})/g, '****');
+    .replaceAll(/(?:[\d+/A-Za-z]{4}){3,}(?:[\d+/A-Za-z]{2}==|[\d+/A-Za-z]{3}=|[\d+/A-Za-z]{4})/gu, '****');
 export default sanitizeErrorMessage;

package/lib/stack.js

@@ -16,7 +16,7 @@ export default function parseStackTraceNatively(err) {
         }));
     };
     try {
-        // eslint-disable-next-line no-unused-expressions
+        // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         err.stack; // trigger prepareStackTrace
     }
     finally {

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.0",
+  "version": "1.2.0",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/ExodusMovement/exodus-hydra.git"
   },
   "homepage": "https://github.com/ExodusMovement/exodus-hydra/tree/master/libraries/errors",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "bugs": {
     "url": "https://github.com/ExodusMovement/exodus-hydra/issues?q=is%3Aissue+is%3Aopen+label%3Aerrors"
   },
@@ -27,15 +27,22 @@
     "build": "run -T tsc --build tsconfig.build.json",
     "prepublishOnly": "yarn run -T build --scope @exodus/errors",
     "clean": "run -T tsc --build --clean",
-    "lint": "run -T eslint . --ignore-path ../../.gitignore",
+    "lint": "run -T eslint .",
     "lint:fix": "yarn lint --fix",
     "test": "yarn run test:v8 && yarn run test:hermes",
     "test:v8": "run -T exodus-test --esbuild --jest src/__tests__/v8/*.test.ts",
-    "test:hermes": "run -T exodus-test --engine hermes:bundle --esbuild --jest src/__tests__/hermes/*.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"
   },
-  "gitHead": "0f5db1a33a6a8dd5fee393f6d8204504af5c2c6e"
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "3f98f500b3b5289ff3e38a8c8385c164b4ee8a5e"
 }