82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# failure
|
|
|
|
[![Made by unshift][made-by]](http://unshift.io)[![Version npm][version]](http://browsenpm.org/package/failure)[![Build Status][build]](https://travis-ci.org/unshiftio/failure)[![Dependencies][david]](https://david-dm.org/unshiftio/failure)[![Coverage Status][cover]](https://coveralls.io/r/unshiftio/failure?branch=master)[![IRC channel][irc]](http://webchat.freenode.net/?channels=unshift)
|
|
|
|
[made-by]: https://img.shields.io/badge/made%20by-unshift-00ffcc.svg?style=flat-square
|
|
[version]: https://img.shields.io/npm/v/failure.svg?style=flat-square
|
|
[build]: https://img.shields.io/travis/unshiftio/failure/master.svg?style=flat-square
|
|
[david]: https://img.shields.io/david/unshiftio/failure.svg?style=flat-square
|
|
[cover]: https://img.shields.io/coveralls/unshiftio/failure/master.svg?style=flat-square
|
|
[irc]: https://img.shields.io/badge/IRC-irc.freenode.net%23unshift-00a8ff.svg?style=flat-square
|
|
|
|
Failure is a small helper library which allows you to easily generate custom
|
|
error objects which can hold addition properties which could be helpful for
|
|
debugging your application. In addition to that, it automatically adds a missing
|
|
`toJSON` function to the Error object so you can actually get the message and
|
|
stack trace once you `JSON.stringify` the error instance.
|
|
|
|
## Installation
|
|
|
|
The module is written with browsers and servers in mind and should run in any
|
|
environment that runs ES3. The module it self is released in the public npm
|
|
registry and can be installed using:
|
|
|
|
```
|
|
npm install --save failure
|
|
```
|
|
|
|
The `--save` flag tells npm to automatically add the installed version to your
|
|
`package.json` file as new dependency.
|
|
|
|
## Usage
|
|
|
|
First of all, start with including this module in your code:
|
|
|
|
```js
|
|
'use strict';
|
|
|
|
var failure = require('failure');
|
|
```
|
|
|
|
Now every time you want to pass or create a `new Error` instance, you can use
|
|
the `failure` function to generate the error for you. The failure method accepts
|
|
2 arguments:
|
|
|
|
1. An `Error` instance that just needs extra props, or a `string` that should be
|
|
transformed to an `Error`. Please do note that when using a string you will
|
|
have an extra trace in your stack trace as the stack trace will be made inside
|
|
the `failure` function instead of where you called the `failure` function.
|
|
2. An object with extra properties that should be introduced on the supplied or
|
|
generated `Error` instance. These properties will not override existing
|
|
properties on the `Error` instance.
|
|
|
|
Before the function returns the generated `Error` instance it checks if it also
|
|
needs to add the missing `.toJSON` method.
|
|
|
|
Below is a small usage example on how you could use this to provide extra
|
|
information when things start failing when you make an HTTP request somewhere.
|
|
If request something with an incorrect status code, you might want to know what
|
|
statusCode was received, so we can easily add that to the Error object. Same as
|
|
parse errors for JSON, you probably want to know what you received and failed.
|
|
|
|
```js
|
|
request('https://googlllll.com', function (err, res, body) {
|
|
if (err) return next(err);
|
|
if (res.statusCode !== 200) return next(failure('Invalid statusCode'), {
|
|
statusCode: res.statusCode
|
|
});
|
|
|
|
try { body = JSON.parse(body); }
|
|
catch (e) {
|
|
return next(failure(e, {
|
|
body: body
|
|
}));
|
|
}
|
|
|
|
next(undefined, body);
|
|
})
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|