Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: document ES2022's Error "cause" property #43830

Merged
merged 4 commits into from
Jul 16, 2022
Merged

doc: document ES2022's Error "cause" property #43830

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9683efb
doc: document ES2022's Error "cause" property
ide Jul 14, 2022
e747171
doc: reword when `cause` property is set
ide Jul 14, 2022
3e00efe
doc: second round of rewording
ide Jul 15, 2022
f6375a1
doc: reword when cause is set
ide Jul 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 48 additions & 5 deletions doc/api/errors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -191,16 +191,19 @@ 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
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
is generated by calling `message.toString()`. The `error.cause` property is set
to the optionally provided `cause`. The `error.stack` property will represent
ide marked this conversation as resolved.
Show resolved Hide resolved
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
given by the property `Error.stackTraceLimit`, whichever is smaller.

### `Error.captureStackTrace(targetObject[, constructorOpt])`
Expand Down Expand Up @@ -253,6 +256,45 @@ 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}

The `error.cause` property is the cause of the error, as set by calling
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggest we re-use the wording from https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause

Suggested change
The `error.cause` property is the cause of the error, as set by calling
The `cause` property indicates the specific original cause of an error.
It is used when catching and re-throwing an error with a more-specific or useful
error message in order to still have access to the the original error.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I updated the PR with wording that is consistent with the other properties in this page while explaining the intent and use of the property like the MDN docs but in a Node-centric way that mentions error codes.

`new Error(message, { cause })`. It is not set if the `cause` option is not
provided.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if properties that are set or not is obvious to all JS devs, so maybe instead we could with something simpler:

Suggested change
`new Error(message, { cause })`. It is not set if the `cause` option is not
provided.
Not all errors have a `cause` property.

Copy link
Member

@F3n67u F3n67u Jul 15, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IMO, I will prefer the original description, as a JS Dev, I can totally understand what it means clearly. "Not all errors have a cause property." is very obvious, I think we don't need to add this sentence.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kept most of the original wording but changed the first paragraph to start with, "If present, the error.cause property..." similar to how other optional properties are described on this page.


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 +3556,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