You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

64 lines
3.8 KiB
Markdown

# 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.