Javascript Error Polyfill
Implementing the V8 Stack Trace API in non-V8 environments as much as possible
Installation
npm install error-polyfill
bower install error-polyfill
Environment compatibility
Tested on the following environments:
Windows 7
- Node.js 9.6
- Chrome 64.0
- Firefox 58.0
- Internet Explorer 10.0, 11.0
- PhantomJS 2.1
- Opera 51.0
Travis
- Node.js 8, 9
- Chrome
- Firefox
- PhantomJS
The polyfill might work on other environments too due to its adaptive design. I use Karma with Browserify to test the framework in browsers.
Requirements
ES5 support is required, without that the lib throws an Error and stops working.
The ES5 features are tested by the capability lib run time.
Classes are created by the o3 lib.
Utility functions are implemented in the u3 lib.
API documentation
Usage
In this documentation I used the framework as follows:
require("error-polyfill");
It is recommended to require the polyfill in your main script.
Getting a past stack trace with Error.getStackTrace
This static method is not part of the V8 Stack Trace API, but it is recommended to use Error.getStackTrace(throwable)
instead of throwable.stack
to get the stack trace of Error instances!
Explanation:
By non-V8 environments we cannot replace the default stack generation algorithm, so we need a workaround to generate the stack when somebody tries to access it. So the original stack string will be parsed and the result will be properly formatted by accessing the stack using the Error.getStackTrace
method.
Arguments and return values:
- The
throwable
argument should be an Error
(descendant) instance, but it can be an Object
instance as well. - The return value is the generated
stack
of the throwable
argument.
Example:
try {
theNotDefinedFunction();
}
catch (error) {
console.log(Error.getStackTrace(error));
}
Capturing the present stack trace with Error.captureStackTrace
The Error.captureStackTrace(throwable [, terminator])
sets the present stack above the terminator
on the throwable
.
Arguments and return values:
- The
throwable
argument should be an instance of an Error
descendant, but it can be an Object
instance as well. It is recommended to use Error
descendant instances instead of inline objects, because we can recognize them by type e.g. error instanceof UserError
. - The optional
terminator
argument should be a Function
. Only the calls before this function will be reported in the stack, so without a terminator
argument, the last call in the stack will be the call of the Error.captureStackTrace
. - There is no return value, the
stack
will be set on the throwable
so you will be able to access it using Error.getStackTrace
. The format of the stack depends on the Error.prepareStackTrace
implementation.
Example:
var UserError = function (message){
this.name = "UserError";
this.message = message;
Error.captureStackTrace(this, this.constructor);
};
UserError.prototype = Object.create(Error.prototype);
function codeSmells(){
throw new UserError("What's going on?!");
}
codeSmells();
Limitations:
By the current implementation the terminator
can be only the Error.captureStackTrace
caller function. This will change soon, but in certain conditions, e.g. by using strict mode ("use strict";
) it is not possible to access the information necessary to implement this feature. You will get an empty frames
array and a warning
in the Error.prepareStackTrace
when the stack parser meets with such conditions.
Formatting the stack trace with Error.prepareStackTrace
The Error.prepareStackTrace(throwable, frames [, warnings])
formats the stack frames
and returns the stack
value for Error.captureStackTrace
or Error.getStackTrace
. The native implementation returns a stack string, but you can override that by setting a new function value.
Arguments and return values:
- The
throwable
argument is an Error
or Object
instance coming from the Error.captureStackTrace
or from the creation of a new Error
instance. Be aware that in some environments you need to throw that instance to get a parsable stack. Without that you will get only a warning
by trying to access the stack with Error.getStackTrace
. - The
frames
argument is an array of Frame
instances. Each frame
represents a function call in the stack. You can use these frames to build a stack string. To access information about individual frames you can use the following methods. frame.toString()
- Returns the string representation of the frame, e.g. codeSmells (myModule.js:23:1)
.frame.getThis()
- Cannot be supported. Returns the context of the call, only V8 environments support this natively.frame.getTypeName()
- Not implemented yet. Returns the type name of the context, by the global namespace it is Window
in Chrome.frame.getFunction()
- Returns the called function or undefined
by strict mode.frame.getFunctionName()
- Not implemented yet. Returns the name of the called function.frame.getMethodName()
- Not implemented yet. Returns the method name of the called function is a method of an object.frame.getFileName()
- Not implemented yet. Returns the file name where the function was called.frame.getLineNumber()
- Not implemented yet. Returns at which line the function was called in the file.frame.getColumnNumber()
- Not implemented yet. Returns at which column the function was called in the file. This information is not always available.frame.getEvalOrigin()
- Not implemented yet. Returns the original of an eval
call.frame.isTopLevel()
- Not implemented yet. Returns whether the function was called from the top level.frame.isEval()
- Not implemented yet. Returns whether the called function was eval
.frame.isNative()
- Not implemented yet. Returns whether the called function was native.frame.isConstructor()
- Not implemented yet. Returns whether the called function was a constructor.- The optional
warnings
argument contains warning messages coming from the stack parser. It is not part of the V8 Stack Trace API. - The return value will be the stack you can access with
Error.getStackTrace(throwable)
. If it is an object, it is recommended to add a toString
method, so you will be able to read it in the console.
Example:
Error.prepareStackTrace = function (throwable, frames, warnings) {
var string = "";
string += throwable.name || "Error";
string += ": " + (throwable.message || "");
if (warnings instanceof Array)
for (var warningIndex in warnings) {
var warning = warnings[warningIndex];
string += "\n # " + warning;
}
for (var frameIndex in frames) {
var frame = frames[frameIndex];
string += "\n at " + frame.toString();
}
return string;
};
Stack trace size limits with Error.stackTraceLimit
Not implemented yet.
You can set size limits on the stack trace, so you won't have any problems because of too long stack traces.
Example:
Error.stackTraceLimit = 10;
Handling uncaught errors and rejections
Not implemented yet.
Differences between environments and modes
Since there is no Stack Trace API standard, every browsers solves this problem differently. I try to document what I've found about these differences as detailed as possible, so it will be easier to follow the code.
Overriding the error.stack
property with custom Stack instances
- by Node.js and Chrome the
Error.prepareStackTrace()
can override every error.stack
automatically right by creation - by Firefox, Internet Explorer and Opera you cannot automatically override every
error.stack
by native errors - by PhantomJS you cannot override the
error.stack
property of native errors, it is not configurable
Capturing the current stack trace
- by Node.js, Chrome, Firefox and Opera the stack property is added by instantiating a native error
- by Node.js and Chrome the stack creation is lazy loaded and cached, so the
Error.prepareStackTrace()
is called only by the first access - by Node.js and Chrome the current stack can be added to any object with
Error.captureStackTrace()
- by Internet Explorer the stack is created by throwing a native error
- by PhantomJS the stack is created by throwing any object, but not a primitive
Accessing the stack
- by Node.js, Chrome, Firefox, Internet Explorer, Opera and PhantomJS you can use the
error.stack
property - by old Opera you have to use the
error.stacktrace
property to get the stack
Prefixes and postfixes on the stack string
- by Node.js, Chrome, Internet Explorer and Opera you have the
error.name
and the error.message
in a {name}: {message}
format at the beginning of the stack string - by Firefox and PhantomJS the stack string does not contain the
error.name
and the error.message
- by Firefox you have an empty line at the end of the stack string
Accessing the stack frames array
- by Node.js and Chrome you can access the frame objects directly by overriding the
Error.prepareStackTrace()
- by Firefox, Internet Explorer, PhantomJS, and Opera you need to parse the stack string in order to get the frames
The structure of the frame string
- by Node.js and Chrome
- the frame string of calling a function from a module:
thirdFn (http://localhost/myModule.js:45:29)
- the frame strings contain an
at
prefix, which is not present by the frame.toString()
output, so it is added by the stack.toString()
- by Firefox
- the frame string of calling a function from a module:
thirdFn@http://localhost/myModule.js:45:29
- by Internet Explorer
- the frame string of calling a function from a module:
at thirdFn (http://localhost/myModule.js:45:29)
- by PhantomJS
- the frame string of calling a function from a module:
thirdFn@http://localhost/myModule.js:45:29
- by Opera
- the frame string of calling a function from a module:
at thirdFn (http://localhost/myModule.js:45)
Accessing information by individual frames
- by Node.js and Chrome the
frame.getThis()
and the frame.getFunction()
returns undefined
by frames originate from strict mode code - by Firefox, Internet Explorer, PhantomJS, and Opera the context of the function calls is not accessible, so the
frame.getThis()
cannot be implemented - by Firefox, Internet Explorer, PhantomJS, and Opera functions are not accessible with
arguments.callee.caller
by frames originate from strict mode, so by these frames frame.getFunction()
can return only undefined
(this is consistent with V8 behavior)
License
MIT - 2016 Jánszky László Lajos