@exodus/errors 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [3.1.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.0.1...@exodus/errors@3.1.0) (2025-08-04)
+
+### Features
+
+- feat: support interpolating non-dynamic safeString into safeString on parse (#13003)
+
+## [3.0.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@3.0.0...@exodus/errors@3.0.1) (2025-07-08)
+
+**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

package/README.md

@@ -3,33 +3,102 @@
 ## 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).
+
+## Recipes
+
+> [!TIP]
+> Before diving into the recipes, you might want to get familiar with what a 'Safe String' is: https://github.com/ExodusMovement/exodus-hydra/tree/master/libraries/safe-string
+
+### I want to preserve server errors in Safe Errors
+
+Do you control the server? If so, better send short error codes from your server instead. `err.code` will [be passed through](https://github.com/ExodusOSS/hydra/blob/master/libraries/errors/src/safe-error.ts#L32) SafeError coercion.
+
+If you do NOT control the server, and you know the specific error messages returned by the server, you can predefine them wrapped in `safeString`:
+
+```js
+import { safeString } from '@exodus/safe-string'
+
+// From: https://github.com/ethereum/go-ethereum/blob/master/core/txpool/errors.go.
+export const KnownErrors = new Set([
+  safeString`already known`,
+  safeString`invalid sender`,
+  safeString`transaction underpriced`,
+])
+```
+
+You can now handle failed requests like this:
+
+```js
+import { safeString } from '@exodus/safe-string`
+import { KnownErrors } from './errors.js'
+
+const response = await this.request(request)
+const error = response?.error
+
+if (error) {
+  const message = KnownErrors.get(msg) ?? safeString`unknown error`
+  throw new Error(safeString`Bad rpc response: ${message}`)
 }
 ```
 
 ## 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.js

@@ -1,4 +1,4 @@
-import { getAllowlist, isSafe } from '@exodus/safe-string';
+import { getAllowlist, parseString } from '@exodus/safe-string';
 import assert from 'minimalistic-assert';
 import parseStackTraceNatively, { stackFramesToString } from './stack.js';
 import { omitUndefined } from './utils.js';
@@ -26,10 +26,6 @@ function isSafeCode(value) {
     return SAFE_CODES_SET.has(value) || isExodusErrorCode(value);
 }
 const staticAllowlist = getAllowlist();
-function getSafeString(str) {
-    if (isSafe(str))
-        return str;
-}
 const FACTORY_SYMBOL = Symbol('SafeError');
 export class SafeError {
     static from(err) {
@@ -44,7 +40,7 @@ export class SafeError {
             const hintCandidates = [hint, message].filter((str) => typeof str === 'string');
             safeHint =
                 // chicken sacrifice to TypeScript, otherwise would be hintCandidates.find((str) => isSafe(str))
-                hintCandidates.map((str) => getSafeString(str)).find(Boolean) ||
+                hintCandidates.map((str) => parseString(str)).find(Boolean) ||
                     staticAllowlist.find((safePrefix) => hintCandidates.some((str) => str.startsWith(safePrefix))) ||
                     toCommonErrorMessage(message);
             const safeStack = parseStackTraceNatively(err);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -24,7 +24,7 @@
     "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 .",
@@ -34,7 +34,7 @@
     "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",
+    "@exodus/safe-string": "^1.2.0",
     "minimalistic-assert": "^1.0.1"
   },
   "devDependencies": {
@@ -44,5 +44,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "aca2b6b0dbe54c8b2b14b14412c81d0237b8d5ee"
+  "gitHead": "917eaccefaf98df19b72a145a52510759cea1237"
 }