ezone

ErrorZone - Javascript Error Framework

The ErrorZone framework helps to use error stack data more efficiently.

Installation

npm install ezone

bower install e3

Environment compatibility

This framework supports the same environments as the error polyfill lib.

I used Karma with Browserify to test the framework in browsers and I used Yadda to run the BDD tests.

Requirements

The error polyfill and the o3 libs are required.

Usage

In this documentation I used the framework as follows:

var e3 = require("ezone"),
    UserError = e3.UserError,
    CompositeError = e3.CompositeError,
    Stack = e3.Stack,
    CompositeStack = e3.CompositeStack;

Errors

Creating custom errors

You can create custom Error sub-classes by extending the UserError class.

var MyError = UserError.extend({
    prototype: {
        name: "MyError"
    }
});

try {
    throw new MyError("problem");
}
catch (theProblem) {
    if (!(theProblem instanceof MyError))
        throw theProblem;
    console.log(theProblem);
        // MyError: problem
    console.log(Error.getStackTrace(theProblem).toString());
        // MyError: problem
            // at (example.js:2:16)
            // at ...
            // ...
}

Overriding and reusing the constructor and the clone method is not recommended by descendant classes, use build and init instead!

Creating composite errors

You can create composite errors with the CompositeError class if you want to report complex problems, which can only described by a hierarchy of error objects.

var MyCompositeError = CompositeError.extend({
    prototype: {
        name: "MyCompositeError"
    }
});

try {
    try {
        throw new MyError("problem");
    }
    catch (theProblem) {
        throw new MyCompositeError({
            message: "complex problem",
            theSource: theProblem
        })
    }
}
catch (theComplexProblem) {
    console.log(Error.getStackTrace(theComplexProblem).toString());
        // MyCompositeError: complex problem
            // at (example.js:5:32)
            // at ...
            // ...
        // caused by <theSource> MyError: problem
            // at (example.js:2:16)
            // at ...
            // ...
}

The CompositeError can be a great help for example by nested validation errors or by reporting about multiple parallel async failures.

Accessing stack frames

If you have your Stack instance, you can access the frames array by reading the stack.frames property.

var stack = Error.getStackTrace(error);
var frames = stack.frames;
for (var index in frames) {
    var frame = frames[index];
    console.log(frame.toString()); // e.g. "fn (example.js:1:1)"
    console.log(frame.getFunction()); // e.g. function fn(){}
}

Using the stack as a string

People tend to use the error.stack as it were a string. This is usually not a wrong assumption, so I added this feature to the lib.

var error = new UserError("cause");
var lines = error.stack.split("\n");
for (var i in lines)
    console.log(line[i]);

This should work despite the fact that the error.stack contains a Stack instance by UserError.

License

MIT - 2015 Jánszky László Lajos