Skip to content

Commit

Permalink
doc: document ES2022's Error "cause" property
Browse files Browse the repository at this point in the history
ES2022 adds an `options` parameter to the `Error` constructor. If the
options argument contains a property named `cause`, the property's value
is assigned to a non-enumerable property named `cause` on the newly
created error. The `cause` property is not referenced anywhere else in
the ES2022/2023 specifications. It is for error-formatting software like
`util.inspect()` to consume.

The `cause` property was added in V8 9.3, which was added to Node
16.9.0.

Refs: https://tc39.es/ecma262/#sec-error-message
Refs: https://github.com/nodejs/node/blob/main/doc/changelogs/CHANGELOG_V16.md#error-cause

PR-URL: #43830
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
  • Loading branch information
ide authored and danielleadams committed Jul 26, 2022
1 parent aba9c8e commit 976093e
Showing 1 changed file with 49 additions and 2 deletions.
51 changes: 49 additions & 2 deletions doc/api/errors.md
Original file line number Diff line number Diff line change
Expand Up @@ -191,13 +191,16 @@ provide a text description of the error.
All errors generated by Node.js, including all system and JavaScript errors,
will either be instances of, or inherit from, the `Error` class.

### `new Error(message)`
### `new Error(message[, options])`

* `message` {string}
* `options` {Object}
* `cause` {any} The error that caused the newly created error.

Creates a new `Error` object and sets the `error.message` property to the
provided text message. If an object is passed as `message`, the text message
is generated by calling `message.toString()`. The `error.stack` property will
is generated by calling `String(message)`. If the `cause` option is provided,
it is assigned to the `error.cause` property. The `error.stack` property will
represent the point in the code at which `new Error()` was called. Stack traces
are dependent on [V8's stack trace API][]. Stack traces extend only to either
(a) the beginning of _synchronous code execution_, or (b) the number of frames
Expand Down Expand Up @@ -253,6 +256,49 @@ will affect any stack trace captured _after_ the value has been changed.
If set to a non-number value, or set to a negative number, stack traces will
not capture any frames.

### `error.cause`

<!-- YAML
added: v16.9.0
-->

* {any}

If present, the `error.cause` property is the underlying cause of the `Error`.
It is used when catching an error and throwing a new one with a different
message or code in order to still have access to the original error.

The `error.cause` property is typically set by calling
`new Error(message, { cause })`. It is not set by the constructor if the
`cause` option is not provided.

This property allows errors to be chained. When serializing `Error` objects,
[`util.inspect()`][] recursively serializes `error.cause` if it is set.

```js
const cause = new Error('The remote HTTP server responded with a 500 status');
const symptom = new Error('The message failed to send', { cause });

console.log(symptom);
// Prints:
// Error: The message failed to send
// at REPL2:1:17
// at Script.runInThisContext (node:vm:130:12)
// ... 7 lines matching cause stack trace ...
// at [_line] [as _line] (node:internal/readline/interface:886:18) {
// [cause]: Error: The remote HTTP server responded with a 500 status
// at REPL1:1:15
// at Script.runInThisContext (node:vm:130:12)
// at REPLServer.defaultEval (node:repl:574:29)
// at bound (node:domain:426:15)
// at REPLServer.runBound [as eval] (node:domain:437:12)
// at REPLServer.onLine (node:repl:902:10)
// at REPLServer.emit (node:events:549:35)
// at REPLServer.emit (node:domain:482:12)
// at [_onLine] [as _onLine] (node:internal/readline/interface:425:12)
// at [_line] [as _line] (node:internal/readline/interface:886:18)
```

### `error.code`

* {string}
Expand Down Expand Up @@ -3514,6 +3560,7 @@ The native call from `process.cpuUsage` could not be processed.
[`subprocess.send()`]: child_process.md#subprocesssendmessage-sendhandle-options-callback
[`url.parse()`]: url.md#urlparseurlstring-parsequerystring-slashesdenotehost
[`util.getSystemErrorName(error.errno)`]: util.md#utilgetsystemerrornameerr
[`util.inspect()`]: util.md#utilinspectobject-options
[`util.parseArgs()`]: util.md#utilparseargsconfig
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
[`zlib`]: zlib.md
Expand Down

0 comments on commit 976093e

Please sign in to comment.