Error Polyfill for V8 Stack Trace API

Common errors

• Error: ES5 support is required!

  cause The runtime environment where the polyfill is executed lacks full ES5 feature support, which is a hard requirement for the library.
  fix Ensure your execution environment (browser, Node.js version) provides complete ES5 support. For very old or non-compliant environments, pre-process your code with a transpiler (e.g., Babel) to ensure ES5 compatibility.

• TypeError: Error.captureStackTrace is not a function

  cause The `error-polyfill` library, which adds `captureStackTrace` as a static method to the global `Error` object, was not loaded or executed before code attempted to call `Error.captureStackTrace`.
  fix Ensure `require("error-polyfill");` is placed at the very top of your application's main entry file or explicitly before any code that attempts to use the polyfilled `Error` methods.

Warnings

• gotcha The `error-polyfill` library explicitly requires ES5 support to function. Running in environments that do not fully support ES5 will cause the library to throw an error and stop working.
  Fix: Ensure the JavaScript execution environment fully supports ES5. For older browsers, this might necessitate transpiling your code to ES5, though this polyfill targets older runtimes where native ES5 support was expected or could be shimmed separately.
• gotcha When `error-polyfill` is active, especially in non-V8 environments, directly accessing `throwable.stack` may yield unformatted or inconsistent stack trace strings. The polyfill mechanism involves parsing and reformatting the stack.
  Fix: Always use the static method `Error.getStackTrace(throwable)` provided by the polyfill to reliably retrieve properly formatted stack traces from `Error` (or `Object`) instances.
• breaking This package is effectively abandoned, indicated by its very low version (0.1.3), reliance on outdated compatibility targets (Node.js 8/9, PhantomJS 2.1, old browser versions), and use of an inactive CI platform (Travis CI). It is unlikely to function correctly or integrate seamlessly with modern JavaScript runtimes (e.g., Node.js 16+), contemporary browser environments, or modern bundlers (Webpack 5+, Vite) without significant manual polyfilling, configuration, or potential conflicts.
  Fix: For new projects, consider using native `Error.stack` if your target environments support it, or opt for a more actively maintained polyfill or transpilation solution for consistent stack trace management. Avoid `error-polyfill` in environments that are not explicitly the deprecated ones it targets.

Install

• npm install error-polyfill npm
• yarn add error-polyfill yarn
• pnpm add error-polyfill pnpm

Imports

• error-polyfill
  wrong:

  import 'error-polyfill';

  correct:

  require("error-polyfill");

  The package is designed to be loaded as a CommonJS module for its side effects, polyfilling global `Error` object methods. Direct ES module import syntax (`import 'error-polyfill';`) is not officially supported and may not work as expected given the package's age and design.
• Error.captureStackTrace
  wrong:

  new Error().captureStackTrace(this, this.constructor);

  correct:

  Error.captureStackTrace(this, this.constructor);

  This is a static method added to the global `Error` constructor by the polyfill; it's not available on `Error` instances directly.
• Error.getStackTrace
  wrong:

  error.stack;

  correct:

  Error.getStackTrace(error);

  This static method is the recommended way to retrieve a formatted stack trace from an error instance when the polyfill is active, especially in non-V8 environments. Directly accessing `error.stack` might return an unformatted or inconsistent string.

Quickstart

This quickstart demonstrates how to load the `error-polyfill`, define a custom error using the polyfilled `Error.captureStackTrace` for structured stack tracing, and then retrieve the formatted stack trace using the recommended `Error.getStackTrace` in both error handling and for general stack capture scenarios.

require("error-polyfill");

// Define a custom error to demonstrate captureStackTrace
var CustomError = function (message) {
    this.name = "CustomError";
    this.message = message;
    // Capture the current stack trace, excluding the CustomError constructor call
    Error.captureStackTrace(this, this.constructor);
};
// Inherit from Error.prototype to ensure proper error instance behavior
CustomError.prototype = Object.create(Error.prototype);
CustomError.prototype.constructor = CustomError; // Maintain correct constructor reference

function doSomethingWithError() {
    function triggerError() {
        throw new CustomError("An intentional error occurred!");
    }
    triggerError();
}

try {
    doSomethingWithError();
} catch (error) {
    console.log("Caught an error:");
    if (error instanceof CustomError) {
        console.log(`  Type: ${error.name}`);
        console.log(`  Message: ${error.message}`);
    }
    // Always use Error.getStackTrace for consistent results with this polyfill
    console.log("  Stack Trace:\n" + Error.getStackTrace(error));
}

// Example of capturing a stack without throwing an error
const myObject = {};
Error.captureStackTrace(myObject);
console.log('\nCaptured stack for a plain object:\n' + Error.getStackTrace(myObject));