From 8af24109d98b68e14bb88940a8ddb6f808e764ab Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Fri, 3 Jan 2025 18:09:49 +0100
Subject: [PATCH 1/3] doc: correct customization hook types & clarify
 descriptions

---
 doc/api/module.md                           | 13 ++++----
 lib/internal/modules/customization_hooks.js | 33 +++++++++++++++++----
 2 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index bf0171fad54b31..c8f7bb6cb7df8c 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -1034,13 +1034,13 @@ changes:
 * `nextResolve` {Function} The subsequent `resolve` hook in the chain, or the
   Node.js default `resolve` hook after the last user-supplied `resolve` hook
   * `specifier` {string}
-  * `context` {Object}
+  * `context` {Object|undefined} When omitted, the defaults are provided. When provided, defaults
+    are merged in with preference to the provided properties.
 * Returns: {Object|Promise} The asynchronous version takes either an object containing the
   following properties, or a `Promise` that will resolve to such an object. The
   synchronous version only accepts an object returned synchronously.
-  * `format` {string|null|undefined} A hint to the load hook (it might be
-    ignored)
-    `'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'`
+  * `format` {string|null|undefined} A hint to the `load` hook (it might be ignored). It can be any
+    string value (`'css'`, `'yaml'`, etc).
   * `importAttributes` {Object|undefined} The import attributes to use when
     caching the module (optional; if excluded the input will be used)
   * `shortCircuit` {undefined|boolean} A signal that this hook intends to
@@ -1143,12 +1143,13 @@ changes:
 * `context` {Object}
   * `conditions` {string\[]} Export conditions of the relevant `package.json`
   * `format` {string|null|undefined} The format optionally supplied by the
-    `resolve` hook chain
+    `resolve` hook chain. This can be any string value, not necessarily a valid return value.
   * `importAttributes` {Object}
 * `nextLoad` {Function} The subsequent `load` hook in the chain, or the
   Node.js default `load` hook after the last user-supplied `load` hook
   * `url` {string}
-  * `context` {Object}
+  * `context` {Object|undefined} When omitted, defaults are provided. When provided, defaults are
+    merged in with preference to the provided properties.
 * Returns: {Object|Promise} The asynchronous version takes either an object containing the
   following properties, or a `Promise` that will resolve to such an object. The
   synchronous version only accepts an object returned synchronously.
diff --git a/lib/internal/modules/customization_hooks.js b/lib/internal/modules/customization_hooks.js
index c7a7a6d53dffd8..9570f52ddc5884 100644
--- a/lib/internal/modules/customization_hooks.js
+++ b/lib/internal/modules/customization_hooks.js
@@ -25,17 +25,40 @@ let debug = require('internal/util/debuglog').debuglog('module_hooks', (fn) => {
   debug = fn;
 });
 
-/** @typedef {import('internal/modules/cjs/loader.js').Module} Module */
 /**
- * @typedef {(specifier: string, context: ModuleResolveContext, nextResolve: ResolveHook)
- *            => ModuleResolveResult} ResolveHook
- * @typedef {(url: string, context: ModuleLoadContext, nextLoad: LoadHook)
- *            => ModuleLoadResult} LoadHook
+ * @typedef {import('internal/modules/cjs/loader.js').Module} Module
+ */
+/**
+ * @typedef {(
+ *   specifier: string,
+ *   context: Partial<ModuleResolveContext>,
+ * ) => ModuleResolveResult
+ * } NextResolve
+ * @typedef {(
+ *   specifier: string,
+ *   context: ModuleResolveContext,
+ *   nextResolve: NextResolve,
+ * ) => ModuleResolveResult
+ * } ResolveHook
+ * @typedef {(
+ *   url: string,
+ *   context: Partial<ModuleLoadContext>,
+ * ) => ModuleLoadResult
+ * } NextLoad
+ * @typedef {(
+ *   url: string,
+ *   context: ModuleLoadContext,
+ *   nextLoad: NextLoad,
+ * ) => ModuleLoadResult
+ * } LoadHook
  */
 
 // Use arrays for better insertion and iteration performance, we don't care
 // about deletion performance as much.
+
+/** @type {ResolveHook[]} */
 const resolveHooks = [];
+/** @type {LoadHook[]} */
 const loadHooks = [];
 const hookId = Symbol('kModuleHooksIdKey');
 let nextHookId = 0;

From f635aadf7ebbbc568be6ef94b62eb6f96a07ac91 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sat, 11 Jan 2025 18:17:02 +0100
Subject: [PATCH 2/3] fixup!: wordsmith `format` description

---
 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 c8f7bb6cb7df8c..d4873c4d60d97f 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -1039,8 +1039,9 @@ changes:
 * Returns: {Object|Promise} The asynchronous version takes either an object containing the
   following properties, or a `Promise` that will resolve to such an object. The
   synchronous version only accepts an object returned synchronously.
-  * `format` {string|null|undefined} A hint to the `load` hook (it might be ignored). It can be any
-    string value (`'css'`, `'yaml'`, etc).
+  * `format` {string|null|undefined} A hint to the `load` hook (it might be ignored). It can be a
+    module format (such as `'commonjs'` or `'module'`) or an arbitrary value like `'css'` or
+    `'yaml'`.
   * `importAttributes` {Object|undefined} The import attributes to use when
     caching the module (optional; if excluded the input will be used)
   * `shortCircuit` {undefined|boolean} A signal that this hook intends to

From 06bd263d7f89198852e880bc1ce3c0e75e95e1c5 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Mon, 13 Jan 2025 14:12:52 +0100
Subject: [PATCH 3/3] fixup!: wordsmith `LoadContext.resolve` description

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

diff --git a/doc/api/module.md b/doc/api/module.md
index d4873c4d60d97f..da9d149f2477db 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -1144,7 +1144,8 @@ changes:
 * `context` {Object}
   * `conditions` {string\[]} Export conditions of the relevant `package.json`
   * `format` {string|null|undefined} The format optionally supplied by the
-    `resolve` hook chain. This can be any string value, not necessarily a valid return value.
+    `resolve` hook chain. This can be any string value as an input; input values do not need to
+    conform to the list of acceptable return values described below.
   * `importAttributes` {Object}
 * `nextLoad` {Function} The subsequent `load` hook in the chain, or the
   Node.js default `load` hook after the last user-supplied `load` hook