capture rejections of promises

Stability: 1 - captureRejections is experimental.

Using async functions with event handlers is problematic, because it can lead to an unhandled rejection in case of a thrown exception:

const ee = new EventEmitter();
ee.on('something', async (value) => {
  throw new Error('kaboom');
});

The captureRejections option in the EventEmitter constructor or the global setting change this behavior, installing a .then(undefined, handler) handler on the Promise. This handler routes the exception asynchronously to the [Symbol.for('nodejs.rejection')][rejection] method if there is one, or to ['error'][error] event handler if there is none.

const ee1 = new EventEmitter({ captureRejections: true });
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});
ee1.on('error', console.log);
const ee2 = new EventEmitter({ captureRejections: true });
ee2.on('something', async (value) => {
  throw new Error('kaboom');
});
ee2[Symbol.for('nodejs.rejection')] = console.log;

Setting EventEmitter.captureRejections = true will change the default for all new instances of EventEmitter.

EventEmitter.captureRejections = true;
const ee1 = new EventEmitter();
ee1.on('something', async (value) => {
  throw new Error('kaboom');
});
ee1.on('error', console.log);

The 'error' events that are generated by the captureRejections behavior do not have a catch handler to avoid infinite error loops: the recommendation is to not use async functions as 'error' event handlers.