From b7c936697910b5a5ce64f549305a298b4a88caef Mon Sep 17 00:00:00 2001 From: Benjamin Gruenbaum Date: Sun, 7 Feb 2021 14:25:35 +0200 Subject: [PATCH] doc: discourage error event PR-URL: https://github.com/nodejs/node/pull/37264 Refs: https://github.com/nodejs/node/pull/37237 Reviewed-By: Anna Henningsen Reviewed-By: Matteo Collina Reviewed-By: Rich Trott --- doc/api/events.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/api/events.md b/doc/api/events.md index 446dd1eb30264d..3d9bfdf28b47fe 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -1238,12 +1238,21 @@ target.addEventListener('foo', handler4, { once: true }); ### `EventTarget` error handling When a registered event listener throws (or returns a Promise that rejects), -by default the error is forwarded to the `process.on('error')` event -on `process.nextTick()`. Throwing within an event listener will *not* stop -the other registered handlers from being invoked. +by default the error is treated as an uncaught exception on +`process.nextTick()`. This means uncaught exceptions in `EventTarget`s will +terminate the Node.js process by default. -The `EventTarget` does not implement any special default handling for -`'error'` type events. +Throwing within an event listener will *not* stop the other registered handlers +from being invoked. + +The `EventTarget` does not implement any special default handling for `'error'` +type events like `EventEmitter`. + +Currently errors are first forwarded to the `process.on('error')` event +before reaching `process.on('uncaughtException')`. This behavior is +deprecated and will change in a future release to align `EventTarget` with +other Node.js APIs. Any code relying on the `process.on('error')` event should +be aligned with the new behavior. ### Class: `Event`