@exodus/errors 2.0.2 → 2.1.1

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.
 
+## [2.1.1](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.1.0...@exodus/errors@2.1.1) (2025-05-08)
+
+### Bug Fixes
+
+- fix: remove `void` keyword (#12267)
+
+## [2.1.0](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.0.2...@exodus/errors@2.1.0) (2025-04-28)
+
+### Features
+
+- feat: introduce `captureStackTrace` util (#12042)
+
 ## [2.0.2](https://github.com/ExodusMovement/exodus-hydra/compare/@exodus/errors@2.0.1...@exodus/errors@2.0.2) (2025-02-27)
 
 ### Bug Fixes

package/README.md

@@ -12,3 +12,24 @@ try {
   sendToErrorTrackingServer(parseStackTrace(e))
 }
 ```
+
+## Troubleshooting
+
+### `parseStackTrace` 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).
+
+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'
+
+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.
+}
+```

package/lib/index.d.ts

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

package/lib/index.js

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

package/lib/stack.d.ts

@@ -1,3 +1,15 @@
 import type { Frame } from './types.js';
+export declare function captureStackTrace(err: Error): void;
 export declare function stackFramesToString(frames?: Frame[]): string | undefined;
+/**
+ * If this function returns undefined, that likely means `error.stack` has been already accessed.
+ * Consider calling `captureStackTrace` first to capture the customized stack trace, e.g.,
+ *
+ * ```ts
+ * captureStackTrace(error)
+ * console.log(error.stack)
+ * ...
+ * const safeError = SafeError.from(error) // Works even if `error.stack` has been accessed.
+ * ```
+ */
 export default function parseStackTraceNatively(err: Error): Frame[] | undefined;

package/lib/stack.js

@@ -1,21 +1,14 @@
-export function stackFramesToString(frames) {
-    if (frames === undefined) {
+const stackCache = new WeakMap();
+export function captureStackTrace(err) {
+    if (stackCache.has(err)) {
         return;
     }
-    return frames
-        .map((frame) => {
-        const { function: fn, file, line, column } = frame;
-        return `    at ${fn || 'unknownFn'}${file ? ` (${file}${line === null ? '' : `:${line}:${column}`})` : ''}`;
-    })
-        .join('\n');
-}
-export default function parseStackTraceNatively(err) {
-    const { prepareStackTrace } = Error;
-    let stack;
+    const { prepareStackTrace: originalPrepareStackTrace } = Error;
+    let structuredStack;
     let calledOn;
-    Error.prepareStackTrace = (e, callSites) => {
-        calledOn = e;
-        stack = callSites.map((trace) => ({
+    Error.prepareStackTrace = (err, callSites) => {
+        calledOn = err;
+        structuredStack = callSites.map((trace) => ({
             function: trace.getFunctionName(),
             method: trace.getMethodName(),
             file: trace.getFileName(),
@@ -25,15 +18,55 @@ export default function parseStackTraceNatively(err) {
             async: trace.isAsync?.(),
             toplevel: trace.isToplevel(),
         }));
+        // Let V8 continue to build the default `.stack` string
+        if (originalPrepareStackTrace)
+            return originalPrepareStackTrace(err, callSites);
+        // Non V8 case (e.g. Hermes).
+        return err.stack;
     };
     try {
+        // do NOT add "void", it will remove the whole line in a tragic transpilation accident
         // eslint-disable-next-line @typescript-eslint/no-unused-expressions
         err.stack; // trigger prepareStackTrace
     }
     finally {
-        Error.prepareStackTrace = prepareStackTrace;
+        Error.prepareStackTrace = originalPrepareStackTrace;
     }
     // @ts-expect-error calledOn gets assigned in prepareStackTrace
-    if (calledOn === err && Array.isArray(stack))
-        return stack;
+    if (calledOn === err && Array.isArray(structuredStack)) {
+        stackCache.set(err, structuredStack);
+    }
+    else {
+        // This helps to avoid calling `captureStackTrace` multiple times on the same error.
+        stackCache.set(err, undefined);
+    }
+}
+export function stackFramesToString(frames) {
+    if (frames === undefined) {
+        return;
+    }
+    return frames
+        .map((frame) => {
+        const { function: fn, file, line, column } = frame;
+        return `    at ${fn || 'unknownFn'}${file ? ` (${file}${line === null ? '' : `:${line}:${column}`})` : ''}`;
+    })
+        .join('\n');
+}
+/**
+ * If this function returns undefined, that likely means `error.stack` has been already accessed.
+ * Consider calling `captureStackTrace` first to capture the customized stack trace, e.g.,
+ *
+ * ```ts
+ * captureStackTrace(error)
+ * console.log(error.stack)
+ * ...
+ * const safeError = SafeError.from(error) // Works even if `error.stack` has been accessed.
+ * ```
+ */
+export default function parseStackTraceNatively(err) {
+    if (stackCache.has(err)) {
+        return stackCache.get(err);
+    }
+    captureStackTrace(err);
+    return stackCache.get(err);
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@exodus/errors",
   "type": "module",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Utilities for error handling in client code, such as sanitization",
   "author": "Exodus Movement, Inc.",
   "repository": {
@@ -38,11 +38,10 @@
   },
   "devDependencies": {
     "@exodus/errors-fixture": "^1.0.0",
-    "@types/minimalistic-assert": "^1.0.1",
-    "hermes-engine-cli": "^0.12.0"
+    "@types/minimalistic-assert": "^1.0.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "7fa27377d258917916c478eaa84e2495a23467be"
+  "gitHead": "5d915aed4f43c8b9377e87c902347aac778391d2"
 }