diff --git a/doc/api/cli.md b/doc/api/cli.md index ced8cece1d57f0..1d3d9a4de27e8c 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -569,6 +569,23 @@ added: v2.4.0 Track heap object allocations for heap snapshots. +### `--unhandled-rejections=mode` + + +By default all unhandled rejections trigger a warning plus a deprecation warning +for the very first unhandled rejection in case no [`unhandledRejection`][] hook +is used. + +Using this flag allows to change what should happen when an unhandled rejection +occurs. One of three modes can be chosen: + +* `strict`: Raise the unhandled rejection as an uncaught exception. +* `warn`: Always trigger a warning, no matter if the [`unhandledRejection`][] + hook is set or not but do not print the deprecation warning. +* `none`: Silence all warnings. + ### `--use-bundled-ca`, `--use-openssl-ca` +* `err` {Error} The uncaught exception. +* `origin` {string} Indicates if the exception originates from an unhandled + rejection or from synchronous errors. Can either be `'uncaughtException'` or + `'unhandledRejection'`. + The `'uncaughtException'` event is emitted when an uncaught JavaScript exception bubbles all the way back to the event loop. By default, Node.js handles such exceptions by printing the stack trace to `stderr` and exiting @@ -217,12 +226,13 @@ behavior. Alternatively, change the [`process.exitCode`][] in the provided exit code. Otherwise, in the presence of such handler the process will exit with 0. -The listener function is called with the `Error` object passed as the only -argument. - ```js -process.on('uncaughtException', (err) => { - fs.writeSync(1, `Caught exception: ${err}\n`); +process.on('uncaughtException', (err, origin) => { + fs.writeSync( + process.stderr.fd, + `Caught exception: ${err}\n` + + `Exception origin: ${origin}` + ); }); setTimeout(() => { @@ -274,6 +284,10 @@ changes: a process warning. --> +* `reason` {Error|any} The object with which the promise was rejected + (typically an [`Error`][] object). +* `promise` {Promise} The rejected promise. + The `'unhandledRejection'` event is emitted whenever a `Promise` is rejected and no error handler is attached to the promise within a turn of the event loop. When programming with Promises, exceptions are encapsulated as "rejected @@ -282,15 +296,9 @@ are propagated through a `Promise` chain. The `'unhandledRejection'` event is useful for detecting and keeping track of promises that were rejected whose rejections have not yet been handled. -The listener function is called with the following arguments: - -* `reason` {Error|any} The object with which the promise was rejected - (typically an [`Error`][] object). -* `p` the `Promise` that was rejected. - ```js -process.on('unhandledRejection', (reason, p) => { - console.log('Unhandled Rejection at:', p, 'reason:', reason); +process.on('unhandledRejection', (reason, promise) => { + console.log('Unhandled Rejection at:', promise, 'reason:', reason); // Application specific logging, throwing an error, or other logic here }); @@ -317,7 +325,7 @@ as would typically be the case for other `'unhandledRejection'` events. To address such failures, a non-operational [`.catch(() => { })`][`promise.catch()`] handler may be attached to `resource.loaded`, which would prevent the `'unhandledRejection'` event from -being emitted. Alternatively, the [`'rejectionHandled'`][] event may be used. +being emitted. ### Event: 'warning'