Skip to content

Commit 22cf503

Browse files
committed
doc: add DOMException section to errors API reference
Document DOMException on the Errors page (with a Globals cross-link) and clarify AbortError vs DOMException for AbortSignal users. Builds on nodejs#64236 review feedback. Fixes nodejs#40789. Signed-off-by: Avocado <[email protected]>
1 parent cb9bb66 commit 22cf503

1 file changed

Lines changed: 33 additions & 0 deletions

File tree

‎doc/api/errors.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -397,6 +397,32 @@ error object, such as a {Proxy}.
397397
Indicates the failure of an assertion. For details, see
398398
[`Class: assert.AssertionError`][].
399399

400+
## Class: `DOMException`
401+
402+
<!-- YAML
403+
added: v17.0.0
404+
-->
405+
406+
* Extends: {errors.Error}
407+
408+
The Web IDL {DOMException} class. These errors are thrown by web-platform APIs
409+
in Node.js such as [`fetch()`][], {AbortController}, {AbortSignal}, and Web
410+
Streams. For details, see also [`Class: DOMException`][] on the Globals page.
411+
412+
The [`domException.name`][] property identifies the type of the exception (for
413+
example, `'AbortError'`). Unlike most errors in Node.js, the
414+
[`domException.code`][] property is a number that corresponds to a
415+
[legacy error code name][Web IDL error names] (for example, `20` for
416+
`ABORT_ERR`).
417+
418+
Node.js-specific APIs that support {AbortSignal} (such as
419+
[`events.once()`][]) throw a Node.js `AbortError` (a native {errors.Error} with
420+
`name` of `'AbortError'` and `code` of [`'ABORT_ERR'`][]) rather than a
421+
{DOMException}. To identify abort errors in either case, checking
422+
`err?.name === 'AbortError'` is sufficient.
423+
424+
See also [`ABORT_ERR`][].
425+
400426
## Class: `RangeError`
401427

402428
* Extends: {errors.Error}
@@ -4640,6 +4666,7 @@ An error occurred trying to allocate memory. This should never happen.
46404666
[V8's stack trace API]: https://v8.dev/docs/stack-trace-api
46414667
[WHATWG Supported Encodings]: util.md#whatwg-supported-encodings
46424668
[WHATWG URL API]: url.md#the-whatwg-url-api
4669+
[Web IDL error names]: https://webidl.spec.whatwg.org/#dfn-error-names-table
46434670
[`"exports"`]: packages.md#exports
46444671
[`"imports"`]: packages.md#imports
46454672
[`'uncaughtException'`]: process.md#event-uncaughtexception
@@ -4648,6 +4675,9 @@ An error occurred trying to allocate memory. This should never happen.
46484675
[`--no-addons`]: cli.md#--no-addons
46494676
[`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
46504677
[`BoundSocket`]: net.md#class-netboundsocket
4678+
[`'ABORT_ERR'`]: #abort_err
4679+
[`ABORT_ERR`]: #abort_err
4680+
[`Class: DOMException`]: globals.md#class-domexception
46514681
[`Class: assert.AssertionError`]: assert.md#class-assertassertionerror
46524682
[`ERR_INCOMPATIBLE_OPTION_PAIR`]: #err_incompatible_option_pair
46534683
[`ERR_INVALID_ARG_TYPE`]: #err_invalid_arg_type
@@ -4676,10 +4706,13 @@ An error occurred trying to allocate memory. This should never happen.
46764706
[`dgram.createSocket()`]: dgram.md#dgramcreatesocketoptions-callback
46774707
[`dgram.disconnect()`]: dgram.md#socketdisconnect
46784708
[`dgram.remoteAddress()`]: dgram.md#socketremoteaddress
4709+
[`domException.code`]: https://developer.mozilla.org/en-US/docs/Web/API/DOMException/code
46794710
[`domException.name`]: https://developer.mozilla.org/en-US/docs/Web/API/DOMException/name
46804711
[`errno`(3) man page]: https://man7.org/linux/man-pages/man3/errno.3.html
46814712
[`error.code`]: #errorcode
46824713
[`error.message`]: #errormessage
4714+
[`events.once()`]: events.md#eventsonceemitter-name-options
4715+
[`fetch()`]: globals.md#fetch
46834716
[`fs.Dir`]: fs.md#class-fsdir
46844717
[`fs.cp()`]: fs.md#fscpsrc-dest-options-callback
46854718
[`fs.readFileSync`]: fs.md#fsreadfilesyncpath-options

0 commit comments

Comments
 (0)