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: #43830 Reviewed-By: Benjamin Gruenbaum <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

Author: ide

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
+constcause=newError('The remote HTTP server responded with a 500 status');
+constsymptom=newError('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