From fc11189cbd2708811570f3db0b2be32c55f8f05e Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 14 Jan 2025 15:24:41 +0100
Subject: [PATCH] doc: correct customization hook types & clarify descriptions

PR-URL: https://github.com/nodejs/node/pull/56454
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
---
 doc/api/module.md                           | 15 ++++++----
 lib/internal/modules/customization_hooks.js | 33 +++++++++++++++++----
 2 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/doc/api/module.md b/doc/api/module.md
index 3ce481fbf6b3b4..6f399fb07a44ee 100644
--- a/doc/api/module.md
+++ b/doc/api/module.md
@@ -1036,13 +1036,14 @@ 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 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
@@ -1145,12 +1146,14 @@ 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 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
   * `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;