unhandled-error

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

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

License

WTFPL or CC0, 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!

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

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.