errlich

a lightweight provider of utility error handling functions for RESTful apis, using boom.

Installing

install

npm install --save errlich

Getting Started

See below for some common usage patterns.

const Errlich = require('errlich');
const errlich = new Errlich();


// install a notifier or two
const logErrors = function(...args) {
    console.error.apply(console, args);
}
const bugsnag = require('bugsnag');
bugsnag.register({ apiKey: '*******************' });
errlich.addNotifier(logErrors);
errlich.addNotifier(bugsnag.notify);


// convert to boom error and call notifiers
Model.find({}, function(err, results) {
    if (err) {
        err = errlich.initialize(err, 500);
        errlich.notify(err);
    }
});


// or better yet, we can intercept callback errors, convert them into
// http friendly boom errors, and pass to our notifiers before passing
// to the original callback
Model.find({}, errlich.wrap(500, function(err, results) {

}));


// for synchronous functions that might throw, we can achieve the same
// functionality as above using #wrapSync
Model.findOne()
.then(errlich.wrapSync(500, function getNestedProp(obj) {
    return obj.nested.prop;
}))
.then(function(data) {
    res.status(200).send({ data });
})
.catch(next);


// you can also predefine any potential known errors and provide custom definitions
const errlich = new Errlich({
    accessTokenMissing: {
        code: 'access-token-missing',
        status: 401,
        title: 'Missing Access Token',
        detail: 'Unable to locate access token'
    },
    cacheError: {
        code: 'cache-error',
        status: 500,
        title: 'Unexpected Cache Error',
        detail: 'There was an unexpected error while retrieving data from the cache'
    }
});
errlich.wrap('accessTokenMissing', myCallback);

API

new Errlich(errors)

Constructor function.

Parameters

Name	Type	Description
errors*	Object	error definitions

Example

const Errlich = require('errlich');

const errors = {
    accessTokenMissing: {
        status: 400,
        title: 'Missing Access Token',
        code: 'access-token-missing'
    }
};

const errlich = new Errlich(errors);

---

#addNotifier(notifier)

Install a notifier.

Parameters

Name	Type	Description
notifier*	Function	notifier function

Example

const bugsnag = require('bugsnag');
bugsnag.register({apiKey: '**************'})

errlich.addNotifier(bugsnag.notify);

---

#get(name)

returns the error definition with the specified name or an undefined error definition.

Parameters

Name	Type	Description
name*	String	definition key

Example

console.log(errlich.get('accessTokenMissing'));

---

#initialize(err, nameOrStatus, msg, properties)

Convert an error into a boom error with additional definition data. See wrap for additional functionality.

Parameters

Name	Type	Description
err*	Error	the error to convert. if not an Error instance, a new error will instantiated
nameOrStatus	Number,String	the name of the error definition or an http status
msg	String	custom message/detail to use. if not provided, the existing error message will be used
properties	Object	additional data to be included at err.data

Returns

Error - the decorated error

Example

if (err) {
    errlich.initialize(err, 'accessTokenMissing', 'No access token was found on the request', { id: req.id });
}

---

#notify(...args)

Pass an error to all notifiers for handling.

Parameters

Name	Type	Description
args*	*	all arguments will be passed to all notifiers

Example

if (err) {
    errlich.notify(err);
}

---

#silentWrap(...args)

Same as #wrap, except no notifiers will be called.

---

#silentWrapSync(...args)

Same as #wrapSync, except no notifiers will be called.

---

#wrap(...args)

Wrap a callback function. If the callback is called with an error, convert it using the provided data, pass error to all notifiers, and then pass to the original callback. If no callback function is passed as an argument, a curried version of the wrapping function will be returned.

Example

// convert any error passed by #doSomethingAsync using the "my-error" definition
doSomethingAsync(errlich.wrap('my-error', function(err, data) {
    console.log(err);
}));

// convert any error passed to a generic forbidden error.
doSomethingAsync(errlich.wrap(403, 'Uh oh! not allowed!', function(err, data) {
    console.log(err);
}));

const wrapReqError = errlich.wrap({ req: req.id });
const wrapMyError = wrapReqError('my-error');
doSomethingAsync(wrapMyError('my custom message', function(err, data) {
    console.log(err);
}));

---

#wrapSync(...args)

Wrap a synchronous function that could potentially throw. Convert any error thrown using the provided data, pass error to all notifiers, and then throw the converted error. If no function is passed as an argument, a curried version of the wrapping function will be returned.

Example

// convert any error passed by #doSomethingAsync using the "my-error" definition
function findMin(values) {
    if (!_.isArray(values) || !values.length) {
        throw new Error('Unable to find min of non/empty array');
    }
    return Math.min.apply(Math, values);
}
Transactions.findByAccountId(id)
.then(errlich.wrapSync(404, findMin))
.then(function(min) {
    res.status(200).send({ min });
})
.catch(next)

---

Testing

run tests

npm test

run coverage

npm run coverage

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

Copyright (c) 2016 Chris Ludden. Licensed under the MIT License