From c3a221953bd7834ecf54c064cb97e81f138f179f Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Mon, 26 Feb 2024 15:36:23 +0100
Subject: [PATCH 1/5] doc,module: clarify hook chain execution sequence

---
 doc/api/module.md | 24 +++++++++++++-----------
 1 file changed, 13 insertions(+), 11 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index e1097c1a48da3d..4edeb012065905 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -274,8 +274,8 @@ It's possible to call `register` more than once:
 // entrypoint.mjs
 import { register } from 'node:module';
 
-register('./first.mjs', import.meta.url);
-register('./second.mjs', import.meta.url);
+register('./foo.mjs', import.meta.url);
+register('./bar.mjs', import.meta.url);
 await import('./my-app.mjs');
 ```
 
@@ -285,20 +285,22 @@ const { register } = require('node:module');
 const { pathToFileURL } = require('node:url');
 
 const parentURL = pathToFileURL(__filename);
-register('./first.mjs', parentURL);
-register('./second.mjs', parentURL);
+register('./foo.mjs', parentURL);
+register('./bar.mjs', parentURL);
 import('./my-app.mjs');
 ```
 
-In this example, the registered hooks will form chains. If both `first.mjs` and
-`second.mjs` define a `resolve` hook, both will be called, in the order they
-were registered. The same applies to all the other hooks.
+In this example, the registered hooks will form chains. These chains run
+last-in, first out (LIFO). If both `foo.mjs` and `bar.mjs` define a `resolve`
+hook, they will be called like so (note the right-to-left):
+node's default ← `./foo.mjs` ← `./bar.mjs`. The same applies to all the other
+hooks.
 
 The registered hooks also affect `register` itself. In this example,
-`second.mjs` will be resolved and loaded per the hooks registered by
-`first.mjs`. This allows for things like writing hooks in non-JavaScript
-languages, so long as an earlier registered loader is one that transpiles into
-JavaScript.
+`bar.mjs` will be resolved and loaded via the hooks registered by `foo.mjs`
+(because `foo`'s hooks will have already been added to the chain). This allows
+for things like writing hooks in non-JavaScript languages, so long as an
+earlier registered loader is one that transpiles into JavaScript.
 
 The `register` method cannot be called from within the module that defines the
 hooks.

From d1b4e768a8ece24c59f2bd327c922ddf629c9946 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Wed, 28 Feb 2024 21:51:26 +0100
Subject: [PATCH 2/5] fixup! doc,module: clarify hook chain execution sequence

link to chaining from hooks & mention LIFO
---
 doc/api/module.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 4edeb012065905..662886812982f4 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -375,11 +375,11 @@ export async function load(url, context, nextLoad) {
 }
 ```
 
-Hooks are part of a chain, even if that chain consists of only one custom
-(user-provided) hook and the default hook, which is always present. Hook
+Hooks are part of a [chain][], even if that chain consists of only one
+custom (user-provided) hook and the default hook, which is always present. Hook
 functions nest: each one must always return a plain object, and chaining happens
 as a result of each function calling `next<hookName>()`, which is a reference to
-the subsequent loader's hook.
+the subsequent loader's hook (in LIFO order).
 
 A hook that returns a value lacking a required property triggers an exception. A
 hook that returns without calling `next<hookName>()` _and_ without returning
@@ -1062,6 +1062,7 @@ returned object contains the following keys:
 [`register`]: #moduleregisterspecifier-parenturl-options
 [`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
 [`util.TextDecoder`]: util.md#class-utiltextdecoder
+[chain]: #chaining
 [hooks]: #customization-hooks
 [load hook]: #loadurl-context-nextload
 [module wrapper]: modules.md#the-module-wrapper

From 3d93d9252dc9a7af3f3d0ed73e4c9baf28e8ffd1 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Fri, 1 Mar 2024 18:23:48 +0100
Subject: [PATCH 3/5] gild the lily

---
 doc/api/module.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 662886812982f4..2a155dd964d7d5 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -293,8 +293,9 @@ import('./my-app.mjs');
 In this example, the registered hooks will form chains. These chains run
 last-in, first out (LIFO). If both `foo.mjs` and `bar.mjs` define a `resolve`
 hook, they will be called like so (note the right-to-left):
-node's default ← `./foo.mjs` ← `./bar.mjs`. The same applies to all the other
-hooks.
+node's default ← `./foo.mjs` ← `./bar.mjs`
+(starting with `./bar.mjs`, then `./foo.mjs`, then node's default).
+The same applies to all the other hooks.
 
 The registered hooks also affect `register` itself. In this example,
 `bar.mjs` will be resolved and loaded via the hooks registered by `foo.mjs`

From f59a6a8dfe5515ced920f4040b7be1786bb7e278 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Fri, 1 Mar 2024 20:10:09 +0100
Subject: [PATCH 4/5] wordsmithing

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>
---
 doc/api/module.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 2a155dd964d7d5..8a065a370e53d9 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -294,7 +294,7 @@ In this example, the registered hooks will form chains. These chains run
 last-in, first out (LIFO). If both `foo.mjs` and `bar.mjs` define a `resolve`
 hook, they will be called like so (note the right-to-left):
 node's default ← `./foo.mjs` ← `./bar.mjs`
-(starting with `./bar.mjs`, then `./foo.mjs`, then node's default).
+(starting with `./bar.mjs`, then `./foo.mjs`, then the Node.js default).
 The same applies to all the other hooks.
 
 The registered hooks also affect `register` itself. In this example,

From d960816d0080a489413ab0766a41381d6b0ce9d5 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Fri, 1 Mar 2024 20:34:08 +0100
Subject: [PATCH 5/5] =?UTF-8?q?loader=20=E2=86=92=20hooks?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: Geoffrey Booth <webadmin@geoffreybooth.com>
---
 doc/api/module.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 8a065a370e53d9..b62cb55a094f59 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -300,8 +300,8 @@ The same applies to all the other hooks.
 The registered hooks also affect `register` itself. In this example,
 `bar.mjs` will be resolved and loaded via the hooks registered by `foo.mjs`
 (because `foo`'s hooks will have already been added to the chain). This allows
-for things like writing hooks in non-JavaScript languages, so long as an
-earlier registered loader is one that transpiles into JavaScript.
+for things like writing hooks in non-JavaScript languages, so long as
+earlier registered hooks transpile into JavaScript.
 
 The `register` method cannot be called from within the module that defines the
 hooks.