commit

node_modules/failure/README.md

@@ -0,0 +1,82 @@
+# 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