diff options
author | James Ide <ide@users.noreply.github.com> | 2022-07-16 09:07:46 +0300 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-07-16 09:07:46 +0300 |
commit | e54ee80d0b04e5165ea3b0e01de17f58b497b6c9 (patch) | |
tree | e17061b7ccbd7de8daa696b49ded2a669c05133c /doc/api/errors.md | |
parent | b014266c33ec776bf42817a89c5488368094808c (diff) |
doc: document ES2022's Error "cause" property
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: https://github.com/nodejs/node/pull/43830
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Diffstat (limited to 'doc/api/errors.md')
-rw-r--r-- | doc/api/errors.md | 51 |
1 files changed, 49 insertions, 2 deletions
diff --git a/doc/api/errors.md b/doc/api/errors.md index 7cd8ae6aab4..e1c2810e1ef 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -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 @@ -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} @@ -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 |