From df5db768f8c71ab4c533f558c6ad81ab556320a8 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 27 Dec 2021 16:05:35 +0100
Subject: [PATCH 1/6] doc: clarify `uncaughtException` `origin` for ESM

Fixes: https://github.com/nodejs/node/issues/41328
---
 doc/api/process.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/doc/api/process.md b/doc/api/process.md
index 1af45fe0240830..5558842729a221 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -337,7 +337,7 @@ changes:
   rejection or from an synchronous error. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection.
+  an unhandled rejection, or when the entry point is an ES module.
 
 The `'uncaughtException'` event is emitted when an uncaught JavaScript
 exception bubbles all the way back to the event loop. By default, Node.js
@@ -365,6 +365,8 @@ setTimeout(() => {
 }, 500);
 
 // Intentionally cause an exception, but don't catch it.
+// Because the exception happens when evaluating an ES module, this is
+// undistinguishable from a Promise rejection, and will be reported as such.
 nonexistentFunc();
 console.log('This will not run.');
 ```
@@ -433,7 +435,7 @@ added:
   rejection or from synchronous errors. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection.
+  an unhandled rejection, or when the entry point is an ES module.
 
 The `'uncaughtExceptionMonitor'` event is emitted before an
 `'uncaughtException'` event is emitted or a hook installed via
@@ -451,6 +453,8 @@ process.on('uncaughtExceptionMonitor', (err, origin) => {
 });
 
 // Intentionally cause an exception, but don't catch it.
+// Because the exception happens when evaluating an ES module, this is
+// undistinguishable from a Promise rejection, and will be reported as such.
 nonexistentFunc();
 // Still crashes Node.js
 ```
@@ -503,7 +507,7 @@ process.on('unhandledRejection', (reason, promise) => {
 
 somePromise.then((res) => {
   return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
-}); // No `.catch()` or `.then()`
+}); // No `.catch()` or `.then()` or `await`.
 ```
 
 ```cjs
@@ -531,7 +535,7 @@ function SomeResource() {
 }
 
 const resource = new SomeResource();
-// no .catch or .then on resource.loaded for at least a turn
+// no await, .catch, or .then on resource.loaded for at least a turn
 ```
 
 ```cjs

From c3b26924c7287f95f769a70f6884f9b260733ffa Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 27 Dec 2021 18:20:35 +0100
Subject: [PATCH 2/6] fixup! doc: clarify `uncaughtException` `origin` for ESM

---
 doc/api/cli.md     | 3 +++
 doc/api/process.md | 8 +++++---
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 70a22ad50387fb..43c6103ef923ec 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1262,6 +1262,9 @@ occurs. One of the following modes can be chosen:
   set, trigger a warning, and set the process exit code to 1.
 * `none`: Silence all warnings.
 
+If a rejection happen in the ES module static loading phase, it will always raise
+it as an uncaught exception.
+
 ### `--use-bundled-ca`, `--use-openssl-ca`
 
 <!-- YAML
diff --git a/doc/api/process.md b/doc/api/process.md
index 5558842729a221..bb0214b2c42984 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -337,7 +337,8 @@ changes:
   rejection or from an synchronous error. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when the entry point is an ES module.
+  an unhandled rejection, or when a rejection happens in the ES module static
+  loading phase.
 
 The `'uncaughtException'` event is emitted when an uncaught JavaScript
 exception bubbles all the way back to the event loop. By default, Node.js
@@ -435,7 +436,8 @@ added:
   rejection or from synchronous errors. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when the entry point is an ES module.
+  an unhandled rejection, or when a rejection happens in the ES module static
+  loading phase.
 
 The `'uncaughtExceptionMonitor'` event is emitted before an
 `'uncaughtException'` event is emitted or a hook installed via
@@ -535,7 +537,7 @@ function SomeResource() {
 }
 
 const resource = new SomeResource();
-// no await, .catch, or .then on resource.loaded for at least a turn
+// No await, .catch, or .then on resource.loaded for at least a turn.
 ```
 
 ```cjs

From 61eb69ad4c1e7499b57fa1e7cc209379fd4d10f0 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 27 Dec 2021 18:22:37 +0100
Subject: [PATCH 3/6] fixup! doc: clarify `uncaughtException` `origin` for ESM

---
 doc/api/process.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/doc/api/process.md b/doc/api/process.md
index bb0214b2c42984..65822d9bf69182 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -455,8 +455,6 @@ process.on('uncaughtExceptionMonitor', (err, origin) => {
 });
 
 // Intentionally cause an exception, but don't catch it.
-// Because the exception happens when evaluating an ES module, this is
-// undistinguishable from a Promise rejection, and will be reported as such.
 nonexistentFunc();
 // Still crashes Node.js
 ```
@@ -509,7 +507,7 @@ process.on('unhandledRejection', (reason, promise) => {
 
 somePromise.then((res) => {
   return reportToUser(JSON.pasre(res)); // Note the typo (`pasre`)
-}); // No `.catch()` or `.then()` or `await`.
+}); // No `.catch()` or `.then()`
 ```
 
 ```cjs
@@ -537,7 +535,7 @@ function SomeResource() {
 }
 
 const resource = new SomeResource();
-// No await, .catch, or .then on resource.loaded for at least a turn.
+// no .catch or .then on resource.loaded for at least a turn
 ```
 
 ```cjs

From ffe2656ecf729f1be41216667d2ca1799bf6df10 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 27 Dec 2021 18:30:15 +0100
Subject: [PATCH 4/6] fixup! doc: clarify `uncaughtException` `origin` for ESM

---
 doc/api/cli.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 43c6103ef923ec..8eefb6262a70b5 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1262,8 +1262,8 @@ occurs. One of the following modes can be chosen:
   set, trigger a warning, and set the process exit code to 1.
 * `none`: Silence all warnings.
 
-If a rejection happen in the ES module static loading phase, it will always raise
-it as an uncaught exception.
+If a rejection happen in the ES module static loading phase, it will always
+raise it as an uncaught exception.
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
 

From c8d24544883c40d59a26e6a0f3caa3d0fff81d02 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Mon, 27 Dec 2021 18:32:28 +0100
Subject: [PATCH 5/6] fixup! doc: clarify `uncaughtException` `origin` for ESM

---
 doc/api/cli.md     | 2 +-
 doc/api/process.md | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 8eefb6262a70b5..6f1cb05c20df66 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1262,7 +1262,7 @@ occurs. One of the following modes can be chosen:
   set, trigger a warning, and set the process exit code to 1.
 * `none`: Silence all warnings.
 
-If a rejection happen in the ES module static loading phase, it will always
+If a rejection happens during the ES module static loading phase, it will always
 raise it as an uncaught exception.
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
diff --git a/doc/api/process.md b/doc/api/process.md
index 65822d9bf69182..30ed65104650a7 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -337,8 +337,8 @@ changes:
   rejection or from an synchronous error. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when a rejection happens in the ES module static
-  loading phase.
+  an unhandled rejection, or when a rejection happens during the ES module
+  static loading phase.
 
 The `'uncaughtException'` event is emitted when an uncaught JavaScript
 exception bubbles all the way back to the event loop. By default, Node.js
@@ -436,8 +436,8 @@ added:
   rejection or from synchronous errors. Can either be `'uncaughtException'` or
   `'unhandledRejection'`. The latter is only used in conjunction with the
   [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when a rejection happens in the ES module static
-  loading phase.
+  an unhandled rejection, or when a rejection happens during the ES module
+  static loading phase.
 
 The `'uncaughtExceptionMonitor'` event is emitted before an
 `'uncaughtException'` event is emitted or a hook installed via

From b589d69ae12541c4b31db041fef837c50d86a893 Mon Sep 17 00:00:00 2001
From: Antoine du Hamel <duhamelantoine1995@gmail.com>
Date: Tue, 28 Dec 2021 16:45:21 +0100
Subject: [PATCH 6/6] fixup! doc: clarify `uncaughtException` `origin` for ESM

---
 doc/api/cli.md     |  4 ++--
 doc/api/process.md | 20 ++++++++++----------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/doc/api/cli.md b/doc/api/cli.md
index 6f1cb05c20df66..16686e417a9931 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -1262,8 +1262,8 @@ occurs. One of the following modes can be chosen:
   set, trigger a warning, and set the process exit code to 1.
 * `none`: Silence all warnings.
 
-If a rejection happens during the ES module static loading phase, it will always
-raise it as an uncaught exception.
+If a rejection happens during the command line entry point's ES module static
+loading phase, it will always raise it as an uncaught exception.
 
 ### `--use-bundled-ca`, `--use-openssl-ca`
 
diff --git a/doc/api/process.md b/doc/api/process.md
index 30ed65104650a7..c222feefeef2a2 100644
--- a/doc/api/process.md
+++ b/doc/api/process.md
@@ -335,10 +335,11 @@ changes:
 * `err` {Error} The uncaught exception.
 * `origin` {string} Indicates if the exception originates from an unhandled
   rejection or from an synchronous error. Can either be `'uncaughtException'` or
-  `'unhandledRejection'`. The latter is only used in conjunction with the
-  [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when a rejection happens during the ES module
-  static loading phase.
+  `'unhandledRejection'`. The latter is used when in an exception happens in a
+  `Promise` based async context (or if a `Promise` is rejected) and
+  [`--unhandled-rejections`][] flag set to `strict` or `throw` (which is the
+  default) and the rejection is not handled, or when a rejection happens during
+  the command line entry point's ES module static loading phase.
 
 The `'uncaughtException'` event is emitted when an uncaught JavaScript
 exception bubbles all the way back to the event loop. By default, Node.js
@@ -366,8 +367,6 @@ setTimeout(() => {
 }, 500);
 
 // Intentionally cause an exception, but don't catch it.
-// Because the exception happens when evaluating an ES module, this is
-// undistinguishable from a Promise rejection, and will be reported as such.
 nonexistentFunc();
 console.log('This will not run.');
 ```
@@ -434,10 +433,11 @@ added:
 * `err` {Error} The uncaught exception.
 * `origin` {string} Indicates if the exception originates from an unhandled
   rejection or from synchronous errors. Can either be `'uncaughtException'` or
-  `'unhandledRejection'`. The latter is only used in conjunction with the
-  [`--unhandled-rejections`][] flag set to `strict` or `throw` and
-  an unhandled rejection, or when a rejection happens during the ES module
-  static loading phase.
+  `'unhandledRejection'`. The latter is used when in an exception happens in a
+  `Promise` based async context (or if a `Promise` is rejected) and
+  [`--unhandled-rejections`][] flag set to `strict` or `throw` (which is the
+  default) and the rejection is not handled, or when a rejection happens during
+  the command line entry point's ES module static loading phase.
 
 The `'uncaughtExceptionMonitor'` event is emitted before an
 `'uncaughtException'` event is emitted or a hook installed via