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