node-unhandled-rejection/README.md

# unhandled-rejection

Unfortunately, there's quite a bit of variation between different Promises implementations and environments, in how you are supposed to (globally) detect unhandled rejections. This can make it tricky to reliably log such errors, *especially* in browsers.

This module provides a single unified API for detecting unhandled rejections (and their subsequent handling, if any). It works in Browserified/Webpacked environments as well, as long as the Promises implementations support it.

__Don't ignore unhandled errors.__ This module is meant to be used for implementing *log-and-crash* logic - once an unexpected error (ie. bug) occurs, it is *not safe to continue*, as your application is now in an unpredictable state. You should instead let your application crash after logging the error, to start over with a 'clean slate'.

## Supported implementations

If your favourite Promises implementation or environment is not (correctly) supported by this module yet, please open a ticket!

|                         | Node.js | WebWorkers | Modern browsers | Old browsers |
|-------------------------|---------|------------|-----------------|--------------|
| Bluebird (> 2.7.0)      | ✓       | ✓          | ✓               | ✓            |
| ES6 Promises (Node.js)¹ | ✓       | n/a        | n/a             | n/a          |
| ES6 Promises (WHATWG)²  | n/a     | ✓          | ✓               | n/a          |
| Q                       | ✓       | ✗          | ✗               | ✗            |
| WhenJS                  | ✓       | ✓⁴         | ✓⁴              | ✗            |
| Yaku                    | ✓       | ✓          | ✓               | ✓            |
| es6-promise             | ✗       | ✗          | ✗               | ✗            |
| then/promise            | ✗       | ✗          | ✗               | ✗            |
| (other, per spec)³      | ✓       | n/a        | n/a             | n/a          |

| Symbol | Meaning                                      |
|--------|----------------------------------------------|
| ✓      | Implemented and supported.                   |
| ✗      | Not implemented - library does not support global rejection events in this environment. |
| n/a    | Specification does not cover this environment. |
| ¹      | [Node.js implementation](https://nodejs.org/api/process.html#process_event_rejectionhandled) |
| ²      | [WHATWG specification](https://html.spec.whatwg.org/multipage/webappapis.html#unhandled-promise-rejections) |
| ³      | [@benjamingr's specification](https://gist.github.com/benjamingr/0237932cee84712951a2) |
| ⁴      | Implementation exists, but is currently completely broken in bundled environments, such as Webpack and Browserify. ([issue](https://github.com/cujojs/when/issues/490)) |

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

__Make sure to read the `implementation-details.md` beforehand.__ The various `unhandledRejection` APIs are extremely finicky, and it's tricky to work out exactly how you can make everything play together nicely. When making a pull request, make sure to *intensively check* that you haven't broken anything in the process.

## Usage


```javascript
const unhandledRejection = require("unhandled-rejection");

// Assuming `loggingServer` is some kind of logging API...

let rejectionEmitter = unhandledRejection({
	timeout: 20
});

rejectionEmitter.on("unhandledRejection", (error, promise) => {
	loggingServer.registerError(error);
});

rejectionEmitter.on("rejectionHandled", (error, promise) => {
	loggingServer.registerHandled(error);
})
```

## Rejections and timeouts

Due to the asynchronous nature of Promises, it's never *completely* certain that a rejection is unhandled - for example, a handler may be attached at a later point. For this reason, many Promise implementations provide a `rejectionHandled` event that essentially 'rectifies' an earlier `unhandledRejection` event, indicating that it was handled after all.

Because not all of these APIs are consistent, this module has to internally keep track of unhandled promises that it has encountered. The problem is that this means it has to keep a reference to every `Error` that it encounters, which in turn will get in the way of the garbage collector - eventually creating a memory leak.

To prevent this, you can configure a `timeout` setting (defaulting to `60` seconds), after which the module will consider a rejection to have been 'final', so that it can remove it from its internal list, thereby freeing up memory. If a `rejectionHandled` for the error comes in *after* this timeout, it will be silently ignored.

Situations where it takes more than 60 seconds to attach a `.catch` handler are rare, but *if* you run into such a situation, you can increase the `timeout` value to accommodate that.

## API

### unhandledRejection(options)

Returns a new `emitter`.

* __options__:
	* __timeout:__ *Defaults to `60`.* The amount of time after which an unhandled rejection should be considered 'final'. See the "Timeout" section above for more information.
	
### emitter.on("unhandledRejection", callback)

Emitted whenever an unhandled rejection is encountered. The `callback` arguments are as follows:

* __error:__ The Error object (or other error value) that the rejection occurred with.
* __promise:__ The Promise for which the error occurred.

### emitter.on("rejectionHandled", callback)

Emitted when a previously 'unhandled' rejection was handled after all (within the timeout). The `callback` arguments are as follows:

* __error:__ The Error object (or other error value) that the original rejection occurred with.
* __promise:__ The Promise for which the error originally occurred.