@exodus/errors 2.2.0 → 3.0.1

package/CHANGELOG.md

@@ -3,9 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [2.2.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.1.1...@exodus/errors@2.2.0) (2025-05-21)
+## [3.0.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.0.0...@exodus/errors@3.0.1) (2025-07-08)
 
-- refactor: pass through safe-strings (#12479)
+**Note:** Version bump only for package @exodus/errors
+
+## [3.0.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.1.1...@exodus/errors@3.0.0) (2025-05-16)
+
+### ⚠ BREAKING CHANGES
+
+- un-export hints whitelist, pass through safe-strings (#12479)
+
+- refactor!: un-export hints whitelist, pass through safe-strings (#12479)
 
 ## [2.1.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.1.0...@exodus/errors@2.1.1) (2025-05-08)
 

package/README.md

@@ -3,33 +3,65 @@
 ## Usage
 
 ```javascript
-import { sanitizeErrorMessage, parseStackTrace } from '@exodus/errors'
+import { SafeError } from '@exodus/errors'
 
 try {
-  // the devil's work
+  throw new Error('Something went wrong')
 } catch (e) {
-  console.error(sanitizeErrorMessage(e.message))
-  sendToErrorTrackingServer(parseStackTrace(e))
+  const safeError = SafeError.from(e)
+
+  // It's now safe to report or log the error, even to a remote server.
+  console.error({
+    name: safeError.name, // Sanitized error name.
+    code: safeError.code, // Optional error code (if present).
+    hint: safeError.hint, // Optional error hint (if present).
+    stack: safeError.stack, // Sanitized stack trace.
+    timestamp: safeError.timestamp, // When the error occurred.
+  })
 }
 ```
 
+## FAQ
+
+### Why using SafeError instead of built-in Errors?
+
+In large codebases, errors can be thrown from anywhere, making it impossible to audit every error message for sensitive information. A single error containing sensitive data could potentially expose user information. Centralizing error handling with `SafeError` makes it possible to enforce security and consistency across the board, by ensuring:
+
+1. **Controlled Error Flow**: All errors go through a single, well-tested sanitization layer before they hit error tracking systems.
+2. **Enforceable Security**: Error handling can be owned through codeowners and covered by tests, so nothing slips through unnoticed.
+
+In addition to enforcing these practices, `SafeError` includes a few key design decisions that make it safer and more reliable than native Error objects:
+
+1. **Message Sanitization**: The `message` property from built-in Errors is intentionally omitted as it often contains sensitive information. Instead, a `hint` property is used that contains only sanitized, non-sensitive information.
+2. **Native Stack Parsing**: The library uses the [`Error.prepareStackTrace` API](https://v8.dev/docs/stack-trace-api) to parse stack traces, providing consistent and reliable stack trace information across different JavaScript environments.
+3. **Immutability**: Once created, a `SafeError` instance cannot be modified, preventing tampering with error data.
+4. **Safe Serialization**: The `toJSON` method ensures safe serialization for logging or sending to error tracking services.
+
+### Why not redacting Error messages?
+
+Parsing/sanitization of error messages is unreliable and the cost of failure is potential loss of user funds and permanent reputation damage.
+
+### Why not use the built-in `.stack` Error property?
+
+Unfortunately, the built-in `.stack` property is mutable and outside of our control. Instead, we use the `Error.prepareStackTrace` API, which enables us to make sure we access the actual call stack and not a cached `err.stack` value that may have already been consumed and modified. We then parse it into a structured format that we can safely sanitize and control. This approach provides consistent, reliable stack traces across different environments (currently supporting both V8 and Hermes).
+
 ## Troubleshooting
 
-### `parseStackTrace` returns undefined stack trace?
+### A SafeError instance returns `undefined` stack trace?
 
-That likely means that something accesses `error.stack` _before_ the `parseStackTrace` had a chance to apply the custom handler. This could be React, a high-level error handler, or any other framework. `error.stack` is computed only on the first access, so the custom handler (`prepareStackTrace`) won’t be called on subsequent attempts (see the `stack.test.js` for a quick demo).
+That likely means that something accesses `error.stack` _before_ the Safe Error constructor had a chance to apply the custom `Error.prepareStackTrace` handler. This could be React, a high-level error handler, or any other framework. `error.stack` is computed only on the first access, so the custom handler won’t be called on subsequent attempts (see the `stack.test.js` for a quick demo).
 
 If you can identify the exact place where `.stack` is accessed, consider capturing the stack trace explicitly like this:
 
 ```javascript
-import { parseStackTrace, captureStackTrace } from '@exodus/errors'
+import { captureStackTrace, SafeError } from '@exodus/errors'
 
 try {
   // the devil's work
 } catch (e) {
   captureStackTrace(e)
   void e.stack // Intentionally access the property to "break" it here.
-  sendToErrorTrackingServer(parseStackTrace(e))
-  // 🎉 Congrats — you just (hopefully) saved hours of debugging! `parseStackTrace` now works because the stack was captured explicitly above.
+  SafeError.from(e).stack // A non-empty string!
+  // 🎉 Congrats — you just (hopefully) saved hours of debugging! The custom stack trace parsing logic now works because the stack was captured explicitly above.
 }
 ```

package/lib/common-errors.d.ts

@@ -12,16 +12,16 @@ declare const commonErrors: readonly [{
     readonly normalized: "Cannot convert undefined to object";
 }, {
     readonly pattern: RegExp;
-    readonly normalized: "Cannot read property/properties of null";
+    readonly normalized: "Cannot read properties of null";
 }, {
     readonly pattern: RegExp;
-    readonly normalized: "Cannot read property/properties of undefined";
+    readonly normalized: "Cannot read properties of undefined";
 }, {
     readonly pattern: RegExp;
-    readonly normalized: "Cannot set property/properties of null";
+    readonly normalized: "Cannot set properties of null";
 }, {
     readonly pattern: RegExp;
-    readonly normalized: "Cannot set property/properties of undefined";
+    readonly normalized: "Cannot set properties of undefined";
 }, {
     readonly pattern: RegExp;
     readonly normalized: "Cannot access property of undefined";

package/lib/common-errors.js

@@ -17,19 +17,19 @@ const commonErrors = [
     },
     {
         pattern: /cannot read (property|properties).* of null/iu,
-        normalized: 'Cannot read property/properties of null',
+        normalized: 'Cannot read properties of null',
     },
     {
         pattern: /cannot read (property|properties).* of undefined/iu,
-        normalized: 'Cannot read property/properties of undefined',
+        normalized: 'Cannot read properties of undefined',
     },
     {
         pattern: /cannot set (property|properties).* of null/iu,
-        normalized: 'Cannot set property/properties of null',
+        normalized: 'Cannot set properties of null',
     },
     {
         pattern: /cannot set (property|properties).* of undefined/iu,
-        normalized: 'Cannot set property/properties of undefined',
+        normalized: 'Cannot set properties of undefined',
     },
     {
         pattern: /undefined is not an object \(evaluating '.*'\)/iu,

package/lib/safe-error.d.ts

@@ -20,24 +20,6 @@ type UnknownError = Error & {
 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" | "TimeoutError";
     get code(): SafeCode | undefined;

package/lib/safe-error.js

@@ -16,24 +16,6 @@ const SAFE_NAMES_SET = makeReadonlySet([
     'SafeErrorFailedToParse',
     'TimeoutError',
 ]);
-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',
-    },
-};
 function isSafeName(value) {
     return SAFE_NAMES_SET.has(value);
 }
@@ -50,7 +32,6 @@ function getSafeString(str) {
 }
 const FACTORY_SYMBOL = Symbol('SafeError');
 export class SafeError {
-    static hints = safeHints;
     static from(err) {
         let safeName;
         let safeCode;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -24,14 +24,14 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "run -T tsc --build tsconfig.build.json",
+    "build": "run -T tsc -p tsconfig.build.json",
     "prepublishOnly": "yarn run -T build --scope @exodus/errors",
     "clean": "run -T tsc --build --clean",
     "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": "EXODUS_TEST_COVERAGE=0 run -T exodus-test --engine hermes:bundle --esbuild --jest src/__tests__/hermes/*.test.ts"
+    "test:v8": "run -T exodus-test --esbuild --jest src/__tests__/v8/*.test.ts src/__tests__/engine-agnostic/*.test.ts",
+    "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/safe-string": "^1.0.0",
@@ -44,5 +44,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "30ebd4bfc064662078e5819e335a3d658f00bd1b"
+  "gitHead": "7fd991f460540c1396fc68391393ee690269fa7f"
 }