V8 Stack Trace Manipulation

Common errors

• TypeError: Cannot read properties of undefined (reading 'toString') (or similar for CallSite methods)

  cause A stack modifier function (either `extend` or `filter`) returned something other than an array of V8 `CallSite` objects, or modified the objects in an unexpected way.
  fix Review your `modifier` functions. Ensure they always return an array, and that array contains valid `CallSite` objects. Do not mutate `CallSite` objects in ways that remove essential properties if they are expected by subsequent processors.

• Error: `Error.stack` is not formatted as expected after calling `chain.format.replace`

  cause Another library or a custom setup is also modifying `Error.stack`, or `Error.stack` was already accessed on the error object before `chain.format.replace` was called.
  fix Verify that `stack-chain` is the last or only library modifying `Error.stack` at the global level. Ensure `chain.format.replace` is called early in your application's lifecycle, before `Error.stack` is likely to be accessed for the first time on relevant error objects.

• ReferenceError: require is not defined (when using `require('stack-chain')` in an ESM module)

  cause Attempting to use CommonJS `require` syntax directly within an ECMAScript Module (ESM) context in Node.js.
  fix Convert your module to CommonJS by using `.js` extension with `"type": "commonjs"` in `package.json`, or rename your file to `.cjs`. Alternatively, if you must use ESM, you can try dynamic `import('stack-chain')` or a build step to transpile, but direct compatibility is not guaranteed for an abandoned package.

Warnings

• gotcha Modifying `Error.stack` globally can lead to conflicts with other libraries or tools that also attempt to manipulate stack traces, causing unpredictable behavior or race conditions. Use with caution in shared environments.
  Fix: Thoroughly test `stack-chain` in your environment, especially if other global error handlers or debugging tools are in use. Consider encapsulating its use or only enabling it in specific execution contexts.
• gotcha Calling `chain.format.restore()` does not guarantee that `Error.stack` will revert to its original V8 format for all existing `Error` objects. If `Error.stack` or `Error.callSite` has already been accessed on an `Error` object, its value is cached and will not change. Only newly created errors or errors whose stack hasn't been accessed will reflect the restored formatter.
  Fix: Be aware of the caching behavior of V8 `Error` objects. If you need to ensure a restored format, primarily apply `restore()` before new errors are generated or before their stacks are accessed.
• breaking The project is abandoned (last commit 2017, last publish 2014) and may not be compatible with modern Node.js versions (e.g., >Node 8-10) or recent V8 engine changes. APIs it relies on (V8 Stack Trace API) might have evolved or been removed, leading to unexpected behavior or crashes.
  Fix: For new projects or existing projects on recent Node.js versions, consider alternative, actively maintained stack manipulation libraries or native V8 APIs directly. If using this package, thorough compatibility testing with your specific Node.js version is essential.
• gotcha When using `chain.filter.attach` or `chain.extend.attach`, your modifier function *must* return a modified `frames` array. Failing to return an array, or returning `null` or `undefined`, can break subsequent modifiers or the stack trace generation process, leading to unexpected errors or incomplete stack traces.
  Fix: Always ensure your modifier function for `attach` methods explicitly returns an array of `callSite` objects, even if it's the original, unmodified array.

Install

• npm install stack-chain npm
• yarn add stack-chain yarn
• pnpm add stack-chain pnpm

Imports

• chain
  wrong:

  import chain from 'stack-chain';

  correct:

  const chain = require('stack-chain');

  This library is primarily CommonJS. While a transpiler might allow `import`, direct ESM support is not provided, and `require` is the intended usage.
• chain.extend.attach
  wrong:

  import { extend } from 'stack-chain'; extend.attach(modifier);

  correct:

  const chain = require('stack-chain');
  chain.extend.attach(modifier);

  The main export is a single 'chain' object with nested methods; individual functions are not directly exportable as named imports.
• chain.format.replace

  const chain = require('stack-chain');
  chain.format.replace(formatter);

  This method replaces the global V8 stack formatter, allowing custom string output for `Error.stack`.

Quickstart

Demonstrates how to attach a stack frame filter and replace the global stack trace formatter, then trigger and print an error.

const chain = require('stack-chain');

// Attach a filter to remove frames originating from this file
chain.filter.attach(function (error, frames) {
    const filteredFrames = frames.filter(function (callSite) {
        return callSite.getFileName() !== module.filename;
    });
    return filteredFrames;
});

// Replace the stack formatter to add a custom prefix
chain.format.replace(function (error, frames) {
    let lines = [];
    lines.push(`CUSTOM ERROR: ${error.toString()}`);
    for (let i = 0; i < frames.length; i++) {
        lines.push(`    at (custom) ${frames[i].toString()}`);
    }
    return lines.join('\n');
});

function myFunction() {
    const err = new Error('Something went wrong!');
    console.log(err.stack);
}

myFunction();

// Restore default V8 formatter after some time (note gotcha on restore)
setTimeout(() => {
  chain.format.restore();
  console.log('\nRestored default stack format, but existing errors may not reflect it.');
  const err2 = new Error('Another error after restore');
  console.log(err2.stack);
}, 100);