# unhandled-error

A small utility for tracking unhandled errors of all varieties.

* Catches all unhandled Promise rejections.
* Catches all uncaught synchronous exceptions.
* Allows for reporting errors manually.
* Automatically crashes your process to prevent data loss or corruption.

This library __only__ takes care of collecting errors. If you want to receive e-mail notifications when an unhandled error occurs, you'll probably want to use the higher-level [`report-errors`](https://www.npmjs.com/package/report-errors) tool instead.

This library does not yet support browser usage, but this is planned for a future version.

## License

[WTFPL](http://www.wtfpl.net/txt/copying/) or [CC0](https://creativecommons.org/publicdomain/zero/1.0/), whichever you prefer. A donation and/or attribution are appreciated, but not required.

## Donate

Maintaining open-source projects takes a lot of time, and the more donations I receive, the more time I can dedicate to open-source. If this module is useful to you, consider [making a donation](http://cryto.net/~joepie91/donate.html)!

You can donate using Bitcoin, PayPal, Flattr, cash-in-mail, SEPA transfers, and pretty much anything else. Thank you!

## Contributing

Pull requests welcome. Please make sure your modifications are in line with the overall code style, and ensure that you're editing the files in `src/`, not those in `lib/`.

Build tool of choice is `gulp`; simply run `gulp` while developing, and it will watch for changes.

Be aware that by making a pull request, you agree to release your modifications under the licenses stated above.

## Usage

```javascript
const unhandledError = require("unhandled-error");

let errorReporter = unhandledError((error, context) => {
    logSomehow(error, context);
});
```

## API

### unhandledError(handler, [options])

Automatically collects all unhandled errors, and forwards them to the specified `handler` before crashing the process.

* __handler:__ The callback to call for every unhandled error. This callback should somehow log the error, so that you can review it later. __To ensure safe operation, this callback *must* be fully synchronous.__ The handler callback receives the following callback arguments:
    * __error:__ The actual error object that was reported. This will be unmodified.
    * __context:__ The "context" in which the error occurs. This is an object that can contain *any* set of keys/values, or none at all - it's specified by the reporter. The one standard context value is `promise`, which is included for unhandled Promise rejections and indicates the Promise that the error originated from. You'll usually want to store the context verbatim, for later inspection.
* __options:__
    * __doNotCrash:__ If set to `true`, it prevents the library from crashing your process after an error is reported. This is *extremely dangerous*, and you should only use it if you are fully aware of the consequences. Defaults to `false`.

Returns a new `errorReporter`, that you can report errors on.

__WARNING:__ Note that *as soon as you call `unhandledError`*, it will start intercepting errors, and things like the default `uncaughtException` handler will no longer fire!

### errorReporter.report(error, [context])

Manually reports an `error` with the given `context`. It will be treated the same as any automatically caught errors.

* __error:__ The error to report. *Must* be an Error object or descendant thereof.
* __context:__ Any data associated with the context in which the error occurred. For example, when reporting an unhandled error from your Express error-handling middleware, you might want to include `req` and `res` here. There is no standard set of keys/values to use here - include whatever information you feel is important to reproduce the error, as long as it's JSON-serializable; circular references are fine.