From 800591537a438a1a3813221ca2011eb1e1183055 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sat, 30 Apr 2022 14:19:48 +0200
Subject: [PATCH 01/24] esm: add chaining to loaders

---
 doc/api/errors.md                             |  11 +
 doc/api/esm.md                                | 214 ++++++-----
 lib/internal/errors.js                        |   7 +
 lib/internal/modules/esm/loader.js            | 345 +++++++++++++-----
 lib/internal/process/esm_loader.js            |   8 +-
 lib/internal/util/types.js                    |   2 +-
 src/node_options.cc                           |   2 +-
 src/node_options.h                            |   2 +-
 .../test-esm-experimental-warnings.mjs        |  27 +-
 test/es-module/test-esm-loader-chaining.mjs   | 305 ++++++++++++++++
 test/es-module/test-esm-loader-hooks.mjs      |  17 +-
 .../es-module/test-esm-loader-invalid-url.mjs |   4 +-
 test/es-module/test-esm-tla-unfinished.mjs    |  34 +-
 .../builtin-named-exports-loader.mjs          |   2 +
 .../es-module-loaders/example-loader.mjs      |   2 +
 .../es-module-loaders/hooks-custom.mjs        |   6 +
 .../loader-invalid-format.mjs                 |   4 +-
 .../es-module-loaders/loader-invalid-url.mjs  |   1 +
 .../loader-load-bad-next-context.mjs          |   3 +
 .../loader-load-bad-next-url.mjs              |   3 +
 .../loader-load-foo-or-42.mjs                 |  11 +
 .../loader-load-impersonating-next-url.mjs    |   3 +
 .../loader-load-incomplete.mjs                |   6 +
 .../loader-load-passing-modified-context.mjs  |   6 +
 .../loader-load-passthru.mjs                  |   4 +
 ...loader-load-receiving-modified-context.mjs |   4 +
 .../es-module-loaders/loader-resolve-42.mjs   |   4 +
 .../loader-resolve-bad-next-context.mjs       |   3 +
 .../loader-resolve-bad-next-specifier.mjs     |   3 +
 .../es-module-loaders/loader-resolve-foo.mjs  |   4 +
 .../loader-resolve-incomplete.mjs             |   5 +
 ...oader-resolve-passing-modified-context.mjs |   6 +
 .../loader-resolve-passthru.mjs               |   4 +
 ...der-resolve-receiving-modified-context.mjs |   4 +
 .../loader-resolve-shortcircuit.mjs           |   6 +
 .../es-module-loaders/mock-loader.mjs         |   5 +
 .../es-module-loaders/string-sources.mjs      |   7 +-
 test/parallel/test-module-main-fail.js        |   5 +-
 .../test-module-parent-deprecation.js         |   2 +-
 39 files changed, 881 insertions(+), 210 deletions(-)
 create mode 100644 test/es-module/test-esm-loader-chaining.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-bad-next-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-bad-next-url.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-foo-or-42.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-impersonating-next-url.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-incomplete.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-passing-modified-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-passthru.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-load-receiving-modified-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-42.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-bad-next-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-bad-next-specifier.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-foo.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-incomplete.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-passing-modified-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-passthru.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-receiving-modified-context.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-shortcircuit.mjs

diff --git a/doc/api/errors.md b/doc/api/errors.md
index b174db7b6151b6..bb92e76624c35f 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -2092,6 +2092,17 @@ An attempt was made to open an IPC communication channel with a synchronously
 forked Node.js process. See the documentation for the [`child_process`][] module
 for more information.
 
+<a id="ERR_LOADER_CHAIN_INCOMPLETE"></a>
+
+### `ERR_LOADER_CHAIN_INCOMPLETE`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+An ESM loader hook returned without calling `next()` and without explicitly
+signaling a short circuit.
+
 <a id="ERR_MANIFEST_ASSERT_INTEGRITY"></a>
 
 ### `ERR_MANIFEST_ASSERT_INTEGRITY`
diff --git a/doc/api/esm.md b/doc/api/esm.md
index 3d09cc03bba696..4ed878d30a25ca 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -7,6 +7,10 @@
 <!-- YAML
 added: v8.5.0
 changes:
+  - version:
+    - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42623
+    description: Add support for chaining loaders.
   - version:
     - v17.1.0
     - v16.14.0
@@ -693,12 +697,38 @@ provided via a `--experimental-loader ./loader-name.mjs` argument to Node.js.
 When hooks are used they apply to the entry point and all `import` calls. They
 won't apply to `require` calls; those still follow [CommonJS][] rules.
 
+Loaders follow the pattern of `--require`:
+
+```console
+node \
+  --experimental-loader unpkg \
+  --experimental-loader http-to-https \
+  --experimental-loader cache-buster
+```
+
+These are called in the following sequence: `cache-buster` calls
+`http-to-https` which calls `unpkg`.
+
 ### Hooks
 
-#### `resolve(specifier, context, defaultResolve)`
+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()`, which is a reference to the
+subsequent loader’s hook.
+
+A hook that fails to return triggers an exception. A hook that returns without
+calling `next()` and without returning `shortCircuit: true` also triggers an
+exception. These errors are to help prevent unintentional breaks in the chain.
+
+#### `resolve(specifier, context, next)`
 
 <!-- YAML
 changes:
+  - version:
+    - REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42623
+    description: Add support for chaining loaders.
   - version:
     - v17.1.0
     - v16.14.0
@@ -711,26 +741,35 @@ changes:
 
 * `specifier` {string}
 * `context` {Object}
-  * `conditions` {string\[]}
+  * `conditions` {string\[]} Export conditions of the relevant `package.json`
   * `importAssertions` {Object}
-  * `parentURL` {string|undefined}
-* `defaultResolve` {Function} The Node.js default resolver.
+  * `parentURL` {string|undefined} The module importing this one, or undefined
+    if this is the Node.js entry point
+* `next` {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}
 * Returns: {Object}
-  * `format` {string|null|undefined}
+  * `format` {string|null|undefined} A hint to the load hook (it might be
+    ignored)
     `'builtin' | 'commonjs' | 'json' | 'module' | 'wasm'`
-  * `url` {string} The absolute url to the import target (such as `file://…`)
-
-The `resolve` hook returns the resolved file URL for a given module specifier
-and parent URL, and optionally its format (such as `'module'`) as a hint to the
-`load` hook. If a format is specified, the `load` hook is ultimately responsible
-for providing the final `format` value (and it is free to ignore the hint
-provided by `resolve`); if `resolve` provides a `format`, a custom `load`
-hook is required even if only to pass the value to the Node.js default `load`
-hook.
+  * `shortCircuit` {undefined|boolean} A signal that this hook intends to
+    terminate the chain of `resolve` hooks. **Default:** `false`
+  * `url` {string} The absolute URL to which this input resolves
+
+The `resolve` hook chain is responsible for resolving file URL for a given
+module specifier and parent URL, and optionally its format (such as `'module'`)
+as a hint to the `load` hook. If a format is specified, the `load` hook is
+ultimately responsible for providing the final `format` value (and it is free to
+ignore the hint provided by `resolve`); if `resolve` provides a `format`, a
+custom `load` hook is required even if only to pass the value to the Node.js
+default `load` hook.
 
 The module specifier is the string in an `import` statement or
-`import()` expression, and the parent URL is the URL of the module that imported
-this one, or `undefined` if this is the main entry point for the application.
+`import()` expression.
+
+The parent URL is the URL of the module that imported this one, or `undefined`
+if this is the main entry point for the application.
 
 The `conditions` property in `context` is an array of conditions for
 [package exports conditions][Conditional Exports] that apply to this resolution
@@ -744,40 +783,36 @@ Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
 `context.conditions` array originally passed into the `resolve` hook.
 
 ```js
-/**
- * @param {string} specifier
- * @param {{
- *   conditions: string[],
- *   parentURL: string | undefined,
- * }} context
- * @param {Function} defaultResolve
- * @returns {Promise<{ url: string }>}
- */
-export async function resolve(specifier, context, defaultResolve) {
+export async function resolve(specifier, context, next) {
   const { parentURL = null } = context;
+
   if (Math.random() > 0.5) { // Some condition.
     // For some or all specifiers, do some custom logic for resolving.
     // Always return an object of the form {url: <string>}.
     return {
+      shortCircuit: true,
       url: parentURL ?
         new URL(specifier, parentURL).href :
         new URL(specifier).href,
     };
   }
+
   if (Math.random() < 0.5) { // Another condition.
     // When calling `defaultResolve`, the arguments can be modified. In this
     // case it's adding another value for matching conditional exports.
-    return defaultResolve(specifier, {
+    return next(specifier, {
       ...context,
       conditions: [...context.conditions, 'another-condition'],
     });
   }
-  // Defer to Node.js for all other specifiers.
-  return defaultResolve(specifier, context, defaultResolve);
+
+  // Defer to the next hook in the chain, which would be the
+  // Node.js default resolve if this is the last user-specified loader.
+  return next(specifier, context);
 }
 ```
 
-#### `load(url, context, defaultLoad)`
+#### `load(url, context, next)`
 
 > The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
@@ -785,15 +820,21 @@ export async function resolve(specifier, context, defaultResolve) {
 > In a previous version of this API, this was split across 3 separate, now
 > deprecated, hooks (`getFormat`, `getSource`, and `transformSource`).
 
-* `url` {string}
+* `url` {string} The URL returned by the `resolve` chain
 * `context` {Object}
+  * `conditions` {string\[]} Export conditions of the relevant `package.json`
   * `format` {string|null|undefined} The format optionally supplied by the
-    `resolve` hook.
+    `resolve` hook chain
   * `importAssertions` {Object}
-* `defaultLoad` {Function}
+* `next` {Function} The subsequent `load` hook in the chain, or the Node.js
+  default `load` hook after the last user-supplied `load` hook
+  * `specifier` {string}
+  * `context` {Object}
 * Returns: {Object}
   * `format` {string}
-  * `source` {string|ArrayBuffer|TypedArray}
+  * `shortCircuit` {undefined|boolean} A signal that this hook intends to
+    terminate the chain of `resolve` hooks. **Default:** `false`
+  * `source` {string|ArrayBuffer|TypedArray} The source for Node.js to evaluate
 
 The `load` hook provides a way to define a custom method of determining how
 a URL should be interpreted, retrieved, and parsed. It is also in charge of
@@ -834,20 +875,10 @@ avoid reading files from disk. It could also be used to map an unrecognized
 format to a supported one, for example `yaml` to `module`.
 
 ```js
-/**
- * @param {string} url
- * @param {{
-    format: string,
-  }} context If resolve settled with a `format`, that value is included here.
- * @param {Function} defaultLoad
- * @returns {Promise<{
-    format: string,
-    source: string | ArrayBuffer | SharedArrayBuffer | Uint8Array,
-  }>}
- */
-export async function load(url, context, defaultLoad) {
+export async function load(url, context, next) {
   const { format } = context;
-  if (Math.random() > 0.5) { // Some condition.
+
+  if (Math.random() > 0.5) { // Some condition
     /*
       For some or all URLs, do some custom logic for retrieving the source.
       Always return an object of the form {
@@ -857,11 +888,13 @@ export async function load(url, context, defaultLoad) {
     */
     return {
       format,
+      shortCircuit: true,
       source: '...',
     };
   }
-  // Defer to Node.js for all other URLs.
-  return defaultLoad(url, context, defaultLoad);
+
+  // Defer to the next hook in the chain.
+  return next(url, context);
 }
 ```
 
@@ -876,7 +909,9 @@ source to a supported one (see [Examples](#examples) below).
 > In a previous version of this API, this hook was named
 > `getGlobalPreloadCode`.
 
-* Returns: {string}
+* `context` {Object} Information to assist the preload code
+  * `port` {MessagePort}
+* Returns: {string} Code to run before application startup
 
 Sometimes it might be necessary to run some code inside of the same global
 scope that the application runs in. This hook allows the return of a string
@@ -890,13 +925,7 @@ If the code needs more advanced `require` features, it has to construct
 its own `require` using  `module.createRequire()`.
 
 ```js
-/**
- * @param {{
-     port: MessagePort,
-   }} utilities Things that preload code might find useful
- * @returns {string} Code to run before application startup
- */
-export function globalPreload(utilities) {
+export function globalPreload(context) {
   return `\
 globalThis.someInjectedProperty = 42;
 console.log('I just set some globals!');
@@ -921,10 +950,6 @@ close normally.
 /**
  * This example has the application context send a message to the loader
  * and sends the message back to the application context
- * @param {{
-     port: MessagePort,
-   }} utilities Things that preload code might find useful
- * @returns {string} Code to run before application startup
  */
 export function globalPreload({ port }) {
   port.onmessage = (evt) => {
@@ -946,9 +971,11 @@ customizations of Node.js’ code loading and evaluation behaviors.
 
 #### HTTPS loader
 
-In current Node.js, specifiers starting with `https://` are unsupported. The
-loader below registers hooks to enable rudimentary support for such specifiers.
-While this may seem like a significant improvement to Node.js core
+In current Node.js, specifiers starting with `https://` are experimental (see
+[HTTPS and HTTP imports][]).
+
+The loader below registers hooks to enable rudimentary support for such
+specifiers. While this may seem like a significant improvement to Node.js core
 functionality, there are substantial downsides to actually using this loader:
 performance is much slower than loading files from disk, there is no caching,
 and there is no security.
@@ -957,7 +984,7 @@ and there is no security.
 // https-loader.mjs
 import { get } from 'node:https';
 
-export function resolve(specifier, context, defaultResolve) {
+export function resolve(specifier, context, next) {
   const { parentURL = null } = context;
 
   // Normally Node.js would error on specifiers starting with 'https://', so
@@ -965,19 +992,21 @@ export function resolve(specifier, context, defaultResolve) {
   // passed along to the later hooks below.
   if (specifier.startsWith('https://')) {
     return {
+      shortCircuit: true,
       url: specifier
     };
   } else if (parentURL && parentURL.startsWith('https://')) {
     return {
-      url: new URL(specifier, parentURL).href
+      shortCircuit: true,
+      url: new URL(specifier, parentURL).href,
     };
   }
 
   // Let Node.js handle all other specifiers.
-  return defaultResolve(specifier, context, defaultResolve);
+  return next(specifier, context);
 }
 
-export function load(url, context, defaultLoad) {
+export function load(url, context, next) {
   // For JavaScript to be loaded over the network, we need to fetch and
   // return it.
   if (url.startsWith('https://')) {
@@ -989,6 +1018,7 @@ export function load(url, context, defaultLoad) {
           // This example assumes all network-provided JavaScript is ES module
           // code.
           format: 'module',
+          shortCircuit: true,
           source: data,
         }));
       }).on('error', (err) => reject(err));
@@ -996,11 +1026,11 @@ export function load(url, context, defaultLoad) {
   }
 
   // Let Node.js handle all other URLs.
-  return defaultLoad(url, context, defaultLoad);
+  return next(url, context);
 }
 ```
 
-```js
+```mjs
 // main.mjs
 import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffeescript.js';
 
@@ -1036,27 +1066,29 @@ const baseURL = pathToFileURL(`${cwd()}/`).href;
 // CoffeeScript files end in .coffee, .litcoffee or .coffee.md.
 const extensionsRegex = /\.coffee$|\.litcoffee$|\.coffee\.md$/;
 
-export async function resolve(specifier, context, defaultResolve) {
-  const { parentURL = baseURL } = context;
-
-  // Node.js normally errors on unknown file extensions, so return a URL for
-  // specifiers ending in the CoffeeScript file extensions.
+export async function resolve(specifier, context, next) {
   if (extensionsRegex.test(specifier)) {
+    const { parentURL = baseURL } = context;
+
+    // Node.js normally errors on unknown file extensions, so return a URL for
+    // specifiers ending in the CoffeeScript file extensions.
     return {
+      shortCircuit: true,
       url: new URL(specifier, parentURL).href
     };
   }
 
   // Let Node.js handle all other specifiers.
-  return defaultResolve(specifier, context, defaultResolve);
+  return next(specifier, context);
 }
 
-export async function load(url, context, defaultLoad) {
-  // Now that we patched resolve to let CoffeeScript URLs through, we need to
-  // tell Node.js what format such URLs should be interpreted as. Because
-  // CoffeeScript transpiles into JavaScript, it should be one of the two
-  // JavaScript formats: 'commonjs' or 'module'.
+export async function load(url, context, next) {
   if (extensionsRegex.test(url)) {
+    // Now that we patched resolve to let CoffeeScript URLs through, we need to
+    // tell Node.js what format such URLs should be interpreted as. Because
+    // CoffeeScript transpiles into JavaScript, it should be one of the two
+    // JavaScript formats: 'commonjs' or 'module'.
+
     // CoffeeScript files can be either CommonJS or ES modules, so we want any
     // CoffeeScript file to be treated by Node.js the same as a .js file at the
     // same location. To determine how Node.js would interpret an arbitrary .js
@@ -1069,25 +1101,26 @@ export async function load(url, context, defaultLoad) {
     // loader. Avoiding the need for a separate CommonJS handler is a future
     // enhancement planned for ES module loaders.
     if (format === 'commonjs') {
-      return { format };
+      return {
+        format,
+        shortCircuit: true,
+      };
     }
 
-    const { source: rawSource } = await defaultLoad(url, { format });
+    const { source: rawSource } = await next(url, { ...context, format });
     // This hook converts CoffeeScript source code into JavaScript source code
     // for all imported CoffeeScript files.
-    const transformedSource = CoffeeScript.compile(rawSource.toString(), {
-      bare: true,
-      filename: url,
-    });
+    const transformedSource = coffeeCompile(rawSource.toString(), url);
 
     return {
       format,
+      shortCircuit: true,
       source: transformedSource,
     };
   }
 
   // Let Node.js handle all other URLs.
-  return defaultLoad(url, context, defaultLoad);
+  return next(url, context);
 }
 
 async function getPackageType(url) {
@@ -1495,6 +1528,7 @@ success!
 [Determining module system]: packages.md#determining-module-system
 [Dynamic `import()`]: https://wiki.developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import#Dynamic_Imports
 [ES Module Integration Proposal for WebAssembly]: https://github.com/webassembly/esm-integration
+[HTTPS and HTTP imports]: #https-and-http-imports
 [Import Assertions]: #import-assertions
 [Import Assertions proposal]: https://github.com/tc39/proposal-import-assertions
 [JSON modules]: #json-modules
@@ -1525,9 +1559,9 @@ success!
 [`util.TextDecoder`]: util.md#class-utiltextdecoder
 [cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer/tree/1.2.2
 [custom https loader]: #https-loader
-[load hook]: #loadurl-context-defaultload
+[load hook]: #loadurl-context-next
 [percent-encoded]: url.md#percent-encoding-in-urls
-[resolve hook]: #resolvespecifier-context-defaultresolve
+[resolve hook]: #resolvespecifier-context-next
 [special scheme]: https://url.spec.whatwg.org/#special-scheme
 [status code]: process.md#exit-codes
 [the official standard format]: https://tc39.github.io/ecma262/#sec-modules
diff --git a/lib/internal/errors.js b/lib/internal/errors.js
index 2185e43a87988b..0afe58843aec5e 100644
--- a/lib/internal/errors.js
+++ b/lib/internal/errors.js
@@ -1359,6 +1359,13 @@ E('ERR_IPC_CHANNEL_CLOSED', 'Channel closed', Error);
 E('ERR_IPC_DISCONNECTED', 'IPC channel is already disconnected', Error);
 E('ERR_IPC_ONE_PIPE', 'Child process can have only one IPC pipe', Error);
 E('ERR_IPC_SYNC_FORK', 'IPC cannot be used with synchronous forks', Error);
+E(
+  'ERR_LOADER_CHAIN_INCOMPLETE',
+  'The "%s" hook from %s did not call the next hook in its chain and did not' +
+  ' explicitly signal a short circuit. If this is intentional, include' +
+  ' `shortCircuit: true` in the hook\'s return.',
+  Error
+);
 E('ERR_MANIFEST_ASSERT_INTEGRITY',
   (moduleURL, realIntegrities) => {
     let msg = `The content of "${
diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 39f8ebca59e9df..9329198890945d 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -23,12 +23,13 @@ const {
 const { MessageChannel } = require('internal/worker/io');
 
 const {
+  ERR_LOADER_CHAIN_INCOMPLETE,
   ERR_INTERNAL_ASSERTION,
   ERR_INVALID_ARG_TYPE,
   ERR_INVALID_ARG_VALUE,
   ERR_INVALID_RETURN_PROPERTY_VALUE,
   ERR_INVALID_RETURN_VALUE,
-  ERR_UNKNOWN_MODULE_FORMAT
+  ERR_UNKNOWN_MODULE_FORMAT,
 } = require('internal/errors').codes;
 const { pathToFileURL, isURLInstance, URL } = require('internal/url');
 const { emitExperimentalWarning } = require('internal/util');
@@ -36,6 +37,10 @@ const {
   isAnyArrayBuffer,
   isArrayBufferView,
 } = require('internal/util/types');
+const {
+  validateObject,
+  validateString,
+} = require('internal/validators');
 const ModuleMap = require('internal/modules/esm/module_map');
 const ModuleJob = require('internal/modules/esm/module_job');
 
@@ -56,10 +61,37 @@ const {
 
 
 /**
- * Prevent the specifier resolution warning from being printed twice
+ * @typedef {object} ExportedHooks
+ * @property {Function} globalPreload
+ * @property {Function} resolve
+ * @property {Function} load
+ */
+
+/**
+ * @typedef {Record<string, any>} ModuleExports
+ */
+
+/**
+ * @typedef {object} KeyedExports
+ * @property {ModuleExports} exports
+ * @property {URL['href']} url
+ */
+
+/**
+ * @typedef {object} KeyedHook
+ * @property {Function} fn
+ * @property {URL['href']} url
+ */
+
+/**
+ * @typedef {'builtin'|'commonjs'|'json'|'module'|'wasm'} ModuleFormat
+ */
+
+/**
+ * @typedef {ArrayBuffer|TypedArray|string} ModuleSource
  */
-let emittedSpecifierResolutionWarning = false;
 
+// [2] `validate...()`s throw the wrong error
 
 /**
  * An ESMLoader instance is used as the main entry point for loading ES modules.
@@ -70,27 +102,35 @@ class ESMLoader {
   /**
    * Prior to ESM loading. These are called once before any modules are started.
    * @private
-   * @property {Function[]} globalPreloaders First-in-first-out list of
-   * preload hooks.
+   * @property {KeyedHook[]} globalPreloaders Last-in-first-out
+   *  list of preload hooks.
    */
   #globalPreloaders = [];
 
   /**
    * Phase 2 of 2 in ESM loading.
    * @private
-   * @property {Function[]} loaders First-in-first-out list of loader hooks.
+   * @property {KeyedHook[]} loaders Last-in-first-out
+   *  collection of loader hooks.
    */
   #loaders = [
-    defaultLoad,
+    {
+      fn: defaultLoad,
+      url: 'node:lib/internal/modules/esm/load.js',
+    },
   ];
 
   /**
    * Phase 1 of 2 in ESM loading.
    * @private
-   * @property {Function[]} resolvers First-in-first-out list of resolver hooks
+   * @property {KeyedHook[]} resolvers Last-in-first-out
+   *  collection of resolver hooks.
    */
   #resolvers = [
-    defaultResolve,
+    {
+      fn: defaultResolve,
+      url: 'node:lib/internal/modules/esm/resolve.js',
+    },
   ];
 
   #importMetaInitializer = initializeImportMeta;
@@ -115,22 +155,28 @@ class ESMLoader {
    */
   translators = translators;
 
-  constructor() {
-    if (getOptionValue('--experimental-loader')) {
+  constructor({ isInternal = false } = ObjectCreate(null)) {
+    if (isInternal) return;
+
+    if (getOptionValue('--experimental-loader')?.length) {
       emitExperimentalWarning('Custom ESM Loaders');
     }
     if (getOptionValue('--experimental-network-imports')) {
       emitExperimentalWarning('Network Imports');
     }
-    if (getOptionValue('--experimental-specifier-resolution') === 'node' && !emittedSpecifierResolutionWarning) {
+    if (getOptionValue('--experimental-specifier-resolution') === 'node') {
       process.emitWarning(
         'The Node.js specifier resolution flag is experimental. It could change or be removed at any time.',
         'ExperimentalWarning'
       );
-      emittedSpecifierResolutionWarning = true;
     }
   }
 
+  /**
+   *
+   * @param {ModuleExports} exports
+   * @returns {ExportedHooks}
+   */
   static pluckHooks({
     globalPreload,
     resolve,
@@ -194,34 +240,51 @@ class ESMLoader {
   /**
    * Collect custom/user-defined hook(s). After all hooks have been collected,
    * calls global preload hook(s).
-   * @param {object | object[]} customLoaders A list of exports from
-   * user-defined loaders (as returned by ESMLoader.import()).
+   * @param {KeyedExports} customLoaders
+   *  A list of exports from user-defined loaders (as returned by
+   *  ESMLoader.import()).
    */
   async addCustomLoaders(
     customLoaders = [],
   ) {
-    if (!ArrayIsArray(customLoaders)) customLoaders = [customLoaders];
-
     for (let i = 0; i < customLoaders.length; i++) {
-      const exports = customLoaders[i];
+      const {
+        exports,
+        url,
+      } = customLoaders[i];
       const {
         globalPreloader,
         resolver,
         loader,
       } = ESMLoader.pluckHooks(exports);
 
-      if (globalPreloader) ArrayPrototypePush(
-        this.#globalPreloaders,
-        FunctionPrototypeBind(globalPreloader, null), // [1]
-      );
-      if (resolver) ArrayPrototypePush(
-        this.#resolvers,
-        FunctionPrototypeBind(resolver, null), // [1]
-      );
-      if (loader) ArrayPrototypePush(
-        this.#loaders,
-        FunctionPrototypeBind(loader, null), // [1]
-      );
+      if (globalPreloader) {
+        ArrayPrototypePush(
+          this.#globalPreloaders,
+          {
+            fn: FunctionPrototypeBind(globalPreloader), // [1]
+            url,
+          },
+        );
+      }
+      if (resolver) {
+        ArrayPrototypePush(
+          this.#resolvers,
+          {
+            fn: FunctionPrototypeBind(resolver), // [1]
+            url,
+          },
+        );
+      }
+      if (loader) {
+        ArrayPrototypePush(
+          this.#loaders,
+          {
+            fn: FunctionPrototypeBind(loader), // [1]
+            url,
+          },
+        );
+      }
     }
 
     // [1] ensure hook function is not bound to ESMLoader instance
@@ -286,7 +349,7 @@ class ESMLoader {
       // immediately and synchronously
       url = fetchModule(new URL(url), { parentURL: url }).resolvedHREF;
       // This should only occur if the module hasn't been fetched yet
-      if (typeof url !== 'string') {
+      if (typeof url !== 'string') { // [2]
         throw new ERR_INTERNAL_ASSERTION(`Base url for module ${url} not loaded.`);
       }
     }
@@ -308,12 +371,16 @@ class ESMLoader {
    */
   async getModuleJob(specifier, parentURL, importAssertions) {
     let importAssertionsForResolve;
+
     if (this.#loaders.length !== 1) {
-      // We can skip cloning if there are no user provided loaders because
+      // We can skip cloning if there are no user-provided loaders because
       // the Node.js default resolve hook does not use import assertions.
-      importAssertionsForResolve =
-        ObjectAssign(ObjectCreate(null), importAssertions);
+      importAssertionsForResolve = ObjectAssign(
+        ObjectCreate(null),
+        importAssertions,
+      );
     }
+
     const { format, url } =
       await this.resolve(specifier, parentURL, importAssertionsForResolve);
 
@@ -391,7 +458,8 @@ class ESMLoader {
    * @param {string} parentURL Path of the parent importing the module.
    * @param {Record<string, string>} importAssertions Validations for the
    *                                                  module import.
-   * @returns {Promise<object | object[]>} A list of module export(s).
+   * @returns {Promise<ExportedHooks | KeyedExports[]>}
+   *  A collection of module export(s).
    */
   async import(specifiers, parentURL, importAssertions) {
     const wasArr = ArrayIsArray(specifiers);
@@ -408,41 +476,96 @@ class ESMLoader {
 
     const namespaces = await PromiseAll(new SafeArrayIterator(jobs));
 
-    return wasArr ?
-      namespaces :
-      namespaces[0];
+    if (!wasArr) return namespaces[0];
+
+    for (let i = 0; i < count; i++) {
+      const namespace = ObjectCreate(null);
+      namespace.url = specifiers[i];
+      namespace.exports = namespaces[i];
+
+      namespaces[i] = namespace;
+    }
+
+    return namespaces;
   }
 
   /**
    * Provide source that is understood by one of Node's translators.
    *
-   * The internals of this WILL change when chaining is implemented,
-   * depending on the resolution/consensus from #36954
-   * @param {string} url The URL/path of the module to be loaded
+   * @param {URL['href']} url The URL/path of the module to be loaded
    * @param {object} context Metadata about the module
-   * @returns {object}
+   * @returns {{ format: ModuleFormat, source: ModuleSource }}
    */
   async load(url, context = {}) {
-    const defaultLoader = this.#loaders[0];
+    const loaders = this.#loaders;
+    let i = loaders.length - 1;
+    let {
+      fn: loader,
+      url: loaderFilePath,
+    } = loaders[i];
+    let chainFinished = i === 0;
+
+    function next(nextUrl, ctx = context) {
+      ({
+        fn: loader,
+        url: loaderFilePath,
+      } = loaders[--i]);
+
+      if (i === 0) chainFinished = true;
+
+      const hookErrIdentifier = `${loaderFilePath} "load"`;
+
+      if (typeof nextUrl !== 'string') {
+        // non-strings can be coerced to a url string
+        // validateString() throws a less-specific error
+        throw new ERR_INVALID_ARG_TYPE(
+          `${hookErrIdentifier} next(url)`,
+          'a url string',
+          nextUrl,
+        );
+      }
+
+      try {
+        new URL(nextUrl);
+      } catch {
+        throw new ERR_INVALID_ARG_VALUE(
+          `${hookErrIdentifier} next(url)`,
+          nextUrl,
+          'should be a url string',
+        );
+      }
+
+      validateObject(ctx, `${hookErrIdentifier} next(, context)`);
+
+      return loader(nextUrl, ctx, next);
+    }
 
-    const loader = this.#loaders.length === 1 ?
-      defaultLoader :
-      this.#loaders[1];
-    const loaded = await loader(url, context, defaultLoader);
+    const loaded = await loader(
+      url,
+      context,
+      next,
+    );
+
+    const hookErrIdentifier = `${loaderFilePath} load`;
 
-    if (typeof loaded !== 'object') {
+    if (typeof loaded !== 'object') { // [2]
       throw new ERR_INVALID_RETURN_VALUE(
-        'object',
-        'loader load',
+        'an object',
+        hookErrIdentifier,
         loaded,
       );
     }
 
     const {
       format,
+      shortCircuit,
       source,
     } = loaded;
 
+    if (!chainFinished && !shortCircuit) {
+      throw new ERR_LOADER_CHAIN_INCOMPLETE('load', loaderFilePath);
+    }
+
     if (format == null) {
       const dataUrl = RegExpPrototypeExec(
         /^data:([^/]+\/[^;,]+)(?:[^,]*?)(;base64)?,/,
@@ -454,10 +577,10 @@ class ESMLoader {
         url);
     }
 
-    if (typeof format !== 'string') {
+    if (typeof format !== 'string') { // [2]
       throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
-        'string',
-        'loader resolve',
+        'a string',
+        hookErrIdentifier,
         'format',
         format,
       );
@@ -469,8 +592,8 @@ class ESMLoader {
       !isAnyArrayBuffer(source) &&
       !isArrayBufferView(source)
     ) throw ERR_INVALID_RETURN_PROPERTY_VALUE(
-      'string, an ArrayBuffer, or a TypedArray',
-      'loader load',
+      'a string, an ArrayBuffer, or a TypedArray',
+      hookErrIdentifier,
       'source',
       source
     );
@@ -482,10 +605,7 @@ class ESMLoader {
   }
 
   preload() {
-    const count = this.#globalPreloaders.length;
-    if (!count) return;
-
-    for (let i = 0; i < count; i++) {
+    for (let i = this.#globalPreloaders.length - 1; i > -1; i--) {
       const channel = new MessageChannel();
       const {
         port1: insidePreload,
@@ -495,16 +615,23 @@ class ESMLoader {
       insidePreload.unref();
       insideLoader.unref();
 
-      const preload = this.#globalPreloaders[i]({
-        port: insideLoader
+      const {
+        fn: preloader,
+        url: specifier,
+      } = this.#globalPreloaders[i];
+
+      const preload = preloader({
+        port: insideLoader,
       });
 
       if (preload == null) return;
 
-      if (typeof preload !== 'string') {
+      const hookErrIdentifier = `${specifier} globalPreload`;
+
+      if (typeof preload !== 'string') { // [2]
         throw new ERR_INVALID_RETURN_VALUE(
-          'string',
-          'loader globalPreloadCode',
+          'a string',
+          hookErrIdentifier,
           preload,
         );
       }
@@ -576,7 +703,7 @@ class ESMLoader {
    * @param {string} [parentURL] The URL path of the module's parent.
    * @param {ImportAssertions} [importAssertions] Assertions from the import
    *                                              statement or expression.
-   * @returns {{ url: string }}
+   * @returns {{ format: string, url: URL['href'] }}
    */
   async resolve(
     originalSpecifier,
@@ -594,56 +721,100 @@ class ESMLoader {
       ['string', 'URL'],
       parentURL,
     );
+    const resolvers = this.#resolvers;
 
-    const conditions = DEFAULT_CONDITIONS;
+    let i = resolvers.length - 1;
+    let {
+      url: resolverFilePath,
+      fn: resolver,
+    } = resolvers[i];
+    let chainFinished = i === 0;
 
-    const defaultResolver = this.#resolvers[0];
+    const context = {
+      conditions: DEFAULT_CONDITIONS,
+      importAssertions,
+      parentURL,
+    };
+
+    function next(suppliedSpecifier, ctx = context) {
+      ({
+        fn: resolver,
+        url: resolverFilePath,
+      } = resolvers[--i]);
+
+      if (i === 0) chainFinished = true;
+
+      const hookErrIdentifier = `${resolverFilePath} "resolve"`;
+
+      validateString(
+        suppliedSpecifier,
+        `${hookErrIdentifier} next(specifier)`,
+      ); // non-strings can be coerced to a url string
+
+      validateObject(ctx, `${hookErrIdentifier} next(, context)`);
+
+      return resolver(suppliedSpecifier, ctx, next);
+    }
 
-    const resolver = this.#resolvers.length === 1 ?
-      defaultResolver :
-      this.#resolvers[1];
     const resolution = await resolver(
       originalSpecifier,
-      {
-        conditions,
-        importAssertions,
-        parentURL,
-      },
-      defaultResolver,
+      context,
+      next,
     );
 
-    if (typeof resolution !== 'object') {
+    const hookErrIdentifier = `${resolverFilePath} resolve`;
+
+    if (typeof resolution !== 'object') { // [2]
       throw new ERR_INVALID_RETURN_VALUE(
-        'object',
-        'loader resolve',
+        'an object',
+        hookErrIdentifier,
         resolution,
       );
     }
 
-    const { format, url } = resolution;
+    const {
+      format,
+      shortCircuit,
+      url,
+    } = resolution;
+
+    if (!chainFinished && !shortCircuit) {
+      throw new ERR_LOADER_CHAIN_INCOMPLETE('resolve', resolverFilePath);
+    }
 
     if (
       format != null &&
-      typeof format !== 'string'
+      typeof format !== 'string' // [2]
     ) {
       throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
-        'string',
-        'loader resolve',
+        'a string',
+        hookErrIdentifier,
         'format',
         format,
       );
     }
 
-    if (typeof url !== 'string') { // non-strings can be coerced to a url string
+    if (typeof url !== 'string') {
+      // non-strings can be coerced to a url string
+      // validateString() throws a less-specific error
       throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
-        'string',
-        'loader resolve',
+        'a url string',
+        hookErrIdentifier,
         'url',
         url,
       );
     }
 
-    new URL(url); // Intentionally trigger error if `url` is invalid
+    try {
+      new URL(url);
+    } catch (err) { // eslint-disable-line no-unused-vars
+      throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
+        'a url string',
+        hookErrIdentifier,
+        'url',
+        url,
+      );
+    }
 
     return {
       format,
diff --git a/lib/internal/process/esm_loader.js b/lib/internal/process/esm_loader.js
index 20021134ce40f3..51661ba7e754dd 100644
--- a/lib/internal/process/esm_loader.js
+++ b/lib/internal/process/esm_loader.js
@@ -49,8 +49,6 @@ exports.esmLoader = esmLoader;
  */
 async function initializeLoader() {
   const { getOptionValue } = require('internal/options');
-  // customLoaders CURRENTLY can be only 1 (a string)
-  // Once chaining is implemented, it will be string[]
   const customLoaders = getOptionValue('--experimental-loader');
 
   if (!customLoaders.length) return;
@@ -65,10 +63,10 @@ async function initializeLoader() {
   // A separate loader instance is necessary to avoid cross-contamination
   // between internal Node.js and userland. For example, a module with internal
   // state (such as a counter) should be independent.
-  const internalEsmLoader = new ESMLoader();
+  const internalEsmLoader = new ESMLoader({ isInternal: true });
 
   // Importation must be handled by internal loader to avoid poluting userland
-  const exports = await internalEsmLoader.import(
+  const keyedExportsList = await internalEsmLoader.import(
     customLoaders,
     pathToFileURL(cwd).href,
     ObjectCreate(null),
@@ -76,7 +74,7 @@ async function initializeLoader() {
 
   // Hooks must then be added to external/public loader
   // (so they're triggered in userland)
-  await esmLoader.addCustomLoaders(exports);
+  await esmLoader.addCustomLoaders(keyedExportsList);
 }
 
 exports.loadESM = async function loadESM(callback) {
diff --git a/lib/internal/util/types.js b/lib/internal/util/types.js
index aca7dbc4b2f2b6..6671e87b66dd08 100644
--- a/lib/internal/util/types.js
+++ b/lib/internal/util/types.js
@@ -68,7 +68,7 @@ module.exports = {
   isFloat32Array,
   isFloat64Array,
   isBigInt64Array,
-  isBigUint64Array
+  isBigUint64Array,
 };
 
 let isCryptoKey;
diff --git a/src/node_options.cc b/src/node_options.cc
index 8341724089a3a1..d94662c68ff0b8 100644
--- a/src/node_options.cc
+++ b/src/node_options.cc
@@ -346,7 +346,7 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("--experimental-json-modules", "", NoOp{}, kAllowedInEnvironment);
   AddOption("--experimental-loader",
             "use the specified module as a custom loader",
-            &EnvironmentOptions::userland_loader,
+            &EnvironmentOptions::userland_loaders,
             kAllowedInEnvironment);
   AddAlias("--loader", "--experimental-loader");
   AddOption("--experimental-modules", "", NoOp{}, kAllowedInEnvironment);
diff --git a/src/node_options.h b/src/node_options.h
index a3937900b41201..f5b738157ecfa2 100644
--- a/src/node_options.h
+++ b/src/node_options.h
@@ -161,7 +161,7 @@ class EnvironmentOptions : public Options {
   bool trace_warnings = false;
   bool extra_info_on_fatal_exception = true;
   std::string unhandled_rejections;
-  std::string userland_loader;
+  std::vector<std::string> userland_loaders;
   bool verify_base_objects =
 #ifdef DEBUG
       true;
diff --git a/test/es-module/test-esm-experimental-warnings.mjs b/test/es-module/test-esm-experimental-warnings.mjs
index bf92b158e485eb..bc56d88f204015 100644
--- a/test/es-module/test-esm-experimental-warnings.mjs
+++ b/test/es-module/test-esm-experimental-warnings.mjs
@@ -1,10 +1,33 @@
 import { mustCall } from '../common/index.mjs';
 import { fileURL } from '../common/fixtures.mjs';
-import { match, strictEqual } from 'assert';
+import { doesNotMatch, match, strictEqual } from 'assert';
 import { spawn } from 'child_process';
 import { execPath } from 'process';
 
-// Verify experimental warnings are printed
+// Verify no warnings are printed when no experimental features are enabled
+{
+  const input = `import ${JSON.stringify(fileURL('es-module-loaders', 'module-named-exports.mjs'))}`;
+  const child = spawn(execPath, [
+    '--input-type=module',
+    '--eval',
+    input,
+  ]);
+
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (data) => { stderr += data; });
+  child.on('close', mustCall((code, signal) => {
+    strictEqual(code, 0);
+    strictEqual(signal, null);
+    doesNotMatch(
+      stderr,
+      /ExperimentalWarning/,
+      new Error('No experimental warning(s) should be emitted when no experimental feature is enabled')
+    );
+  }));
+}
+
+// Verify experimental warning is printed when experimental feature is enabled
 for (
   const [experiment, arg] of [
     [/Custom ESM Loaders/, `--experimental-loader=${fileURL('es-module-loaders', 'hooks-custom.mjs')}`],
diff --git a/test/es-module/test-esm-loader-chaining.mjs b/test/es-module/test-esm-loader-chaining.mjs
new file mode 100644
index 00000000000000..9f89b4e2cf8aea
--- /dev/null
+++ b/test/es-module/test-esm-loader-chaining.mjs
@@ -0,0 +1,305 @@
+import '../common/index.mjs';
+import fixtures from '../common/fixtures.js';
+import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+
+const setupArgs = [
+  '--no-warnings',
+  '--input-type=module',
+  '-e',
+];
+const commonInput = 'import fs from "node:fs"; console.log(fs)';
+const commonArgs = [
+  ...setupArgs,
+  commonInput,
+];
+
+{ // Verify unadulterated source is loaded when there are no loaders
+  const { status, stdout } = spawnSync(
+    process.execPath,
+    [
+      ...setupArgs,
+      'import fs from "node:fs"; console.log(typeof fs?.constants?.F_OK )',
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 0);
+  assert.match(stdout, /number/); // node:fs is an object
+}
+
+{ // Verify loaded source is properly different when only load changes something
+  const { status, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /load passthru/);
+  assert.match(stdout, /resolve passthru/);
+  assert.strictEqual(status, 0);
+  assert.match(stdout, /foo/);
+}
+
+{ // Verify multiple changes from hooks result in proper output
+  const { status, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-foo.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /resolve 42/); // It did go thru resolve-42
+  assert.strictEqual(status, 0);
+  assert.match(stdout, /foo/); // LIFO, so resolve-foo won
+}
+
+{ // Verify modifying context within resolve chain is respected
+  const { status, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-receiving-modified-context.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passing-modified-context.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /bar/);
+  assert.strictEqual(status, 0);
+}
+
+{ // Verify multiple changes from hooks result in proper output
+  const { status, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-foo.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /resolve foo/); // It did go thru resolve-foo
+  assert.strictEqual(status, 0);
+  assert.match(stdout, /42/); // LIFO, so resolve-42 won
+}
+
+{ // Verify error thrown for incomplete resolve chain, citing errant loader & hook
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-incomplete.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /resolve passthru/);
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_LOADER_CHAIN_INCOMPLETE/);
+  assert.match(stderr, /loader-resolve-incomplete\.mjs/);
+  assert.match(stderr, /"resolve"/);
+}
+
+{ // Verify chain does break and throws appropriately
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-incomplete.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.doesNotMatch(stdout, /resolve passthru/);
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_LOADER_CHAIN_INCOMPLETE/);
+  assert.match(stderr, /loader-resolve-incomplete\.mjs/);
+  assert.match(stderr, /"resolve"/);
+}
+
+{ // Verify error thrown for incomplete load chain, citing errant loader & hook
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-incomplete.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.match(stdout, /load passthru/);
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_LOADER_CHAIN_INCOMPLETE/);
+  assert.match(stderr, /loader-load-incomplete\.mjs/);
+  assert.match(stderr, /"load"/);
+}
+
+{ // Verify chain does break and throws appropriately
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-incomplete.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.doesNotMatch(stdout, /load passthru/);
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_LOADER_CHAIN_INCOMPLETE/);
+  assert.match(stderr, /loader-load-incomplete\.mjs/);
+  assert.match(stderr, /"load"/);
+}
+
+{ // Verify error thrown when invalid `specifier` argument passed to `resolve…next`
+  const { status, stderr } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-bad-next-specifier.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
+  assert.match(stderr, /loader-resolve-bad-next-specifier\.mjs/);
+  assert.match(stderr, /"resolve"/);
+  assert.match(stderr, /next\(specifier\)/);
+}
+
+{ // Verify error thrown when invalid `context` argument passed to `resolve…next`
+  const { status, stderr } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-bad-next-context.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
+  assert.match(stderr, /loader-resolve-bad-next-context\.mjs/);
+  assert.match(stderr, /"resolve"/);
+  assert.match(stderr, /next\(, context\)/);
+}
+
+{ // Verify error thrown when invalid `url` argument passed to `load…next`
+  const { status, stderr } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-bad-next-url.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
+  assert.match(stderr, /loader-load-bad-next-url\.mjs/);
+  assert.match(stderr, /"load"/);
+  assert.match(stderr, /next\(url\)/);
+}
+
+{ // Verify error thrown when invalid `url` argument passed to `load…next`
+  const { status, stderr } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-impersonating-next-url.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_INVALID_ARG_VALUE/);
+  assert.match(stderr, /loader-load-impersonating-next-url\.mjs/);
+  assert.match(stderr, /"load"/);
+  assert.match(stderr, /next\(url\)/);
+}
+
+{ // Verify error thrown when invalid `context` argument passed to `load…next`
+  const { status, stderr } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-bad-next-context.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(status, 1);
+  assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
+  assert.match(stderr, /loader-load-bad-next-context\.mjs/);
+  assert.match(stderr, /"load"/);
+  assert.match(stderr, /next\(, context\)/);
+}
diff --git a/test/es-module/test-esm-loader-hooks.mjs b/test/es-module/test-esm-loader-hooks.mjs
index 57a203342ac49c..7e6ea6793e227b 100644
--- a/test/es-module/test-esm-loader-hooks.mjs
+++ b/test/es-module/test-esm-loader-hooks.mjs
@@ -35,6 +35,7 @@ const { ESMLoader } = esmLoaderModule;
 
     return {
       format: suggestedFormat,
+      shortCircuit: true,
       url: resolvedURL,
     };
   }
@@ -54,15 +55,21 @@ const { ESMLoader } = esmLoaderModule;
     // This doesn't matter (just to avoid errors)
     return {
       format: 'module',
+      shortCircuit: true,
       source: '',
     };
   }
 
-  const customLoader = {
-    // Ensure ESMLoader actually calls the custom hooks
-    resolve: mustCall(resolve),
-    load: mustCall(load),
-  };
+  const customLoader = [
+    {
+      exports: {
+        // Ensure ESMLoader actually calls the custom hooks
+        resolve: mustCall(resolve),
+        load: mustCall(load),
+      },
+      url: 'node:test/es-module/test-esm-loader-hooks.mjs',
+    },
+  ];
 
   esmLoader.addCustomLoaders(customLoader);
 
diff --git a/test/es-module/test-esm-loader-invalid-url.mjs b/test/es-module/test-esm-loader-invalid-url.mjs
index 6294e57404c8bb..1ba7c621f7e92a 100644
--- a/test/es-module/test-esm-loader-invalid-url.mjs
+++ b/test/es-module/test-esm-loader-invalid-url.mjs
@@ -4,7 +4,7 @@ import assert from 'assert';
 
 import('../fixtures/es-modules/test-esm-ok.mjs')
 .then(assert.fail, (error) => {
-  expectsError({ code: 'ERR_INVALID_URL' })(error);
-  assert.strictEqual(error.input, '../fixtures/es-modules/test-esm-ok.mjs');
+  expectsError({ code: 'ERR_INVALID_RETURN_PROPERTY_VALUE' })(error);
+  assert.match(error.message, /loader-invalid-url\.mjs/);
 })
 .then(mustCall());
diff --git a/test/es-module/test-esm-tla-unfinished.mjs b/test/es-module/test-esm-tla-unfinished.mjs
index d7658c19e98e1c..a7b6e620d0620a 100644
--- a/test/es-module/test-esm-tla-unfinished.mjs
+++ b/test/es-module/test-esm-tla-unfinished.mjs
@@ -3,11 +3,17 @@ import assert from 'assert';
 import child_process from 'child_process';
 import fixtures from '../common/fixtures.js';
 
+const commonArgs = [
+  '--no-warnings',
+  '--input-type=module',
+  '--eval',
+];
+
 {
   // Unresolved TLA promise, --eval
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    ['--input-type=module', '--eval', 'await new Promise(() => {})'],
+    [...commonArgs, 'await new Promise(() => {})'],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [13, '', '']);
 }
@@ -16,7 +22,7 @@ import fixtures from '../common/fixtures.js';
   // Rejected TLA promise, --eval
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    ['--input-type=module', '-e', 'await Promise.reject(new Error("Xyz"))'],
+    [...commonArgs, 'await Promise.reject(new Error("Xyz"))'],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout], [1, '']);
   assert.match(stderr, /Error: Xyz/);
@@ -26,8 +32,10 @@ import fixtures from '../common/fixtures.js';
   // Unresolved TLA promise with explicit exit code, --eval
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    ['--input-type=module', '--eval',
-     'process.exitCode = 42;await new Promise(() => {})'],
+    [
+      ...commonArgs,
+      'process.exitCode = 42;await new Promise(() => {})',
+    ],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [42, '', '']);
 }
@@ -36,8 +44,10 @@ import fixtures from '../common/fixtures.js';
   // Rejected TLA promise with explicit exit code, --eval
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    ['--input-type=module', '-e',
-     'process.exitCode = 42;await Promise.reject(new Error("Xyz"))'],
+    [
+      ...commonArgs,
+      'process.exitCode = 42;await Promise.reject(new Error("Xyz"))',
+    ],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout], [1, '']);
   assert.match(stderr, /Error: Xyz/);
@@ -47,7 +57,7 @@ import fixtures from '../common/fixtures.js';
   // Unresolved TLA promise, module file
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/unresolved.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/unresolved.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [13, '', '']);
 }
@@ -56,7 +66,7 @@ import fixtures from '../common/fixtures.js';
   // Rejected TLA promise, module file
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/rejected.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/rejected.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout], [1, '']);
   assert.match(stderr, /Error: Xyz/);
@@ -66,7 +76,7 @@ import fixtures from '../common/fixtures.js';
   // Unresolved TLA promise, module file
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/unresolved-withexitcode.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/unresolved-withexitcode.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [42, '', '']);
 }
@@ -75,7 +85,7 @@ import fixtures from '../common/fixtures.js';
   // Rejected TLA promise, module file
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/rejected-withexitcode.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/rejected-withexitcode.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout], [1, '']);
   assert.match(stderr, /Error: Xyz/);
@@ -85,7 +95,7 @@ import fixtures from '../common/fixtures.js';
   // Calling process.exit() in .mjs should return status 0
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/process-exit.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/process-exit.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [0, '', '']);
 }
@@ -94,7 +104,7 @@ import fixtures from '../common/fixtures.js';
   // Calling process.exit() in worker thread shouldn't influence main thread
   const { status, stdout, stderr } = child_process.spawnSync(
     process.execPath,
-    [fixtures.path('es-modules/tla/unresolved-with-worker-process-exit.mjs')],
+    ['--no-warnings', fixtures.path('es-modules/tla/unresolved-with-worker-process-exit.mjs')],
     { encoding: 'utf8' });
   assert.deepStrictEqual([status, stdout, stderr], [13, '', '']);
 }
diff --git a/test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs b/test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs
index 8790811c7e7bd6..e303ec196f6c6d 100644
--- a/test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs
+++ b/test/fixtures/es-module-loaders/builtin-named-exports-loader.mjs
@@ -18,6 +18,7 @@ export async function resolve(specifier, context, next) {
 
   if (def.url.startsWith('node:')) {
     return {
+      shortCircuit: true,
       url: `custom-${def.url}`,
       importAssertions: context.importAssertions,
     };
@@ -29,6 +30,7 @@ export function load(url, context, next) {
   if (url.startsWith('custom-node:')) {
     const urlObj = new URL(url);
     return {
+      shortCircuit: true,
       source: generateBuiltinModule(urlObj.pathname),
       format: 'module',
     };
diff --git a/test/fixtures/es-module-loaders/example-loader.mjs b/test/fixtures/es-module-loaders/example-loader.mjs
index be4808738035f9..f87054c8b70502 100644
--- a/test/fixtures/es-module-loaders/example-loader.mjs
+++ b/test/fixtures/es-module-loaders/example-loader.mjs
@@ -11,6 +11,7 @@ baseURL.pathname = process.cwd() + '/';
 export function resolve(specifier, { parentURL = baseURL }, defaultResolve) {
   if (builtinModules.includes(specifier)) {
     return {
+      shortCircuit: true,
       url: 'node:' + specifier
     };
   }
@@ -22,6 +23,7 @@ export function resolve(specifier, { parentURL = baseURL }, defaultResolve) {
   }
   const resolved = new URL(specifier, parentURL);
   return {
+    shortCircuit: true,
     url: resolved.href
   };
 }
diff --git a/test/fixtures/es-module-loaders/hooks-custom.mjs b/test/fixtures/es-module-loaders/hooks-custom.mjs
index 5173b97387905a..4c4014db01ef3f 100644
--- a/test/fixtures/es-module-loaders/hooks-custom.mjs
+++ b/test/fixtures/es-module-loaders/hooks-custom.mjs
@@ -29,25 +29,30 @@ export function load(url, context, next) {
 
   if (url.endsWith('esmHook/badReturnFormatVal.mjs')) return {
     format: Array(0),
+    shortCircuit: true,
     source: '',
   }
   if (url.endsWith('esmHook/unsupportedReturnFormatVal.mjs')) return {
     format: 'foo', // Not one of the allowable inputs: no translator named 'foo'
+    shortCircuit: true,
     source: '',
   }
 
   if (url.endsWith('esmHook/badReturnSourceVal.mjs')) return {
     format: 'module',
+    shortCircuit: true,
     source: Array(0),
   }
 
   if (url.endsWith('esmHook/preknownFormat.pre')) return {
     format: context.format,
+    shortCircuit: true,
     source: `const msg = 'hello world'; export default msg;`
   };
 
   if (url.endsWith('esmHook/virtual.mjs')) return {
     format: 'module',
+    shortCircuit: true,
     source: `export const message = 'Woohoo!'.toUpperCase();`,
   };
 
@@ -63,6 +68,7 @@ export function resolve(specifier, context, next) {
 
   if (specifier.startsWith('esmHook')) return {
     format,
+    shortCircuit: true,
     url: pathToFileURL(specifier).href,
     importAssertions: context.importAssertions,
   };
diff --git a/test/fixtures/es-module-loaders/loader-invalid-format.mjs b/test/fixtures/es-module-loaders/loader-invalid-format.mjs
index 0210f73b554382..438d50dacba433 100644
--- a/test/fixtures/es-module-loaders/loader-invalid-format.mjs
+++ b/test/fixtures/es-module-loaders/loader-invalid-format.mjs
@@ -1,7 +1,8 @@
 export async function resolve(specifier, { parentURL, importAssertions }, defaultResolve) {
   if (parentURL && specifier === '../fixtures/es-modules/test-esm-ok.mjs') {
     return {
-      url: 'file:///asdf'
+      shortCircuit: true,
+      url: 'file:///asdf',
     };
   }
   return defaultResolve(specifier, {parentURL, importAssertions}, defaultResolve);
@@ -11,6 +12,7 @@ export async function load(url, context, next) {
   if (url === 'file:///asdf') {
     return {
       format: 'esm',
+      shortCircuit: true,
       source: '',
     }
   }
diff --git a/test/fixtures/es-module-loaders/loader-invalid-url.mjs b/test/fixtures/es-module-loaders/loader-invalid-url.mjs
index a7cefeca3da37a..87d1a6a564b461 100644
--- a/test/fixtures/es-module-loaders/loader-invalid-url.mjs
+++ b/test/fixtures/es-module-loaders/loader-invalid-url.mjs
@@ -1,6 +1,7 @@
 export async function resolve(specifier, { parentURL, importAssertions }, defaultResolve) {
   if (parentURL && specifier === '../fixtures/es-modules/test-esm-ok.mjs') {
     return {
+      shortCircuit: true,
       url: specifier,
       importAssertions,
     };
diff --git a/test/fixtures/es-module-loaders/loader-load-bad-next-context.mjs b/test/fixtures/es-module-loaders/loader-load-bad-next-context.mjs
new file mode 100644
index 00000000000000..fe38da04f9ff91
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-bad-next-context.mjs
@@ -0,0 +1,3 @@
+export async function load(url, context, next) {
+  return next(url, []);
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-bad-next-url.mjs b/test/fixtures/es-module-loaders/loader-load-bad-next-url.mjs
new file mode 100644
index 00000000000000..4f53b695327dd1
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-bad-next-url.mjs
@@ -0,0 +1,3 @@
+export async function load(url, context, next) {
+  return next([], context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-foo-or-42.mjs b/test/fixtures/es-module-loaders/loader-load-foo-or-42.mjs
new file mode 100644
index 00000000000000..8d408223e66a0a
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-foo-or-42.mjs
@@ -0,0 +1,11 @@
+export async function load(url) {
+  const val = url.includes('42')
+    ? '42'
+    : '"foo"';
+
+  return {
+    format: 'module',
+    shortCircuit: true,
+    source: `export default ${val}`,
+  };
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-impersonating-next-url.mjs b/test/fixtures/es-module-loaders/loader-load-impersonating-next-url.mjs
new file mode 100644
index 00000000000000..f98b091c8b9ff5
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-impersonating-next-url.mjs
@@ -0,0 +1,3 @@
+export async function load(url, context, next) {
+  return next('not/a/url', context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-incomplete.mjs b/test/fixtures/es-module-loaders/loader-load-incomplete.mjs
new file mode 100644
index 00000000000000..d6242488e5738e
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-incomplete.mjs
@@ -0,0 +1,6 @@
+export async function load() {
+  return {
+    format: 'module',
+    source: 'export default 42',
+  };
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-passing-modified-context.mjs b/test/fixtures/es-module-loaders/loader-load-passing-modified-context.mjs
new file mode 100644
index 00000000000000..7676be766af575
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-passing-modified-context.mjs
@@ -0,0 +1,6 @@
+export async function load(url, context, next) {
+  return next(url, {
+    ...context,
+    foo: 'bar',
+  });
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-passthru.mjs b/test/fixtures/es-module-loaders/loader-load-passthru.mjs
new file mode 100644
index 00000000000000..8cfbcb6a3a5d0b
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-passthru.mjs
@@ -0,0 +1,4 @@
+export async function load(url, context, next) {
+  console.log('load passthru'); // This log is deliberate
+  return next(url, context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-load-receiving-modified-context.mjs b/test/fixtures/es-module-loaders/loader-load-receiving-modified-context.mjs
new file mode 100644
index 00000000000000..2d7bc350bd8775
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-receiving-modified-context.mjs
@@ -0,0 +1,4 @@
+export async function load(url, context, next) {
+  console.log(context.foo); // This log is deliberate
+  return next(url, context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-42.mjs b/test/fixtures/es-module-loaders/loader-resolve-42.mjs
new file mode 100644
index 00000000000000..f4dffd70fc94ad
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-42.mjs
@@ -0,0 +1,4 @@
+export async function resolve(specifier, context, next) {
+  console.log('resolve 42'); // This log is deliberate
+  return next('file:///42.mjs', context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-bad-next-context.mjs b/test/fixtures/es-module-loaders/loader-resolve-bad-next-context.mjs
new file mode 100644
index 00000000000000..881f5875dd0206
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-bad-next-context.mjs
@@ -0,0 +1,3 @@
+export async function resolve(specifier, context, next) {
+  return next(specifier, []);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-bad-next-specifier.mjs b/test/fixtures/es-module-loaders/loader-resolve-bad-next-specifier.mjs
new file mode 100644
index 00000000000000..a23785d3d956db
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-bad-next-specifier.mjs
@@ -0,0 +1,3 @@
+export async function resolve(specifier, context, next) {
+  return next([], context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-foo.mjs b/test/fixtures/es-module-loaders/loader-resolve-foo.mjs
new file mode 100644
index 00000000000000..595385e12a0cf7
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-foo.mjs
@@ -0,0 +1,4 @@
+export async function resolve(specifier, context, next) {
+  console.log('resolve foo'); // This log is deliberate
+  return next('file:///foo.mjs', context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-incomplete.mjs b/test/fixtures/es-module-loaders/loader-resolve-incomplete.mjs
new file mode 100644
index 00000000000000..9eb1617f30130e
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-incomplete.mjs
@@ -0,0 +1,5 @@
+export async function resolve() {
+  return {
+    url: 'file:///incomplete-resolve-chain.js',
+  };
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-passing-modified-context.mjs b/test/fixtures/es-module-loaders/loader-resolve-passing-modified-context.mjs
new file mode 100644
index 00000000000000..6a92a6cd8f6a8e
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-passing-modified-context.mjs
@@ -0,0 +1,6 @@
+export async function resolve(specifier, context, next) {
+  return next(specifier, {
+    ...context,
+    foo: 'bar',
+  });
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-passthru.mjs b/test/fixtures/es-module-loaders/loader-resolve-passthru.mjs
new file mode 100644
index 00000000000000..1a373bab90ba57
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-passthru.mjs
@@ -0,0 +1,4 @@
+export async function resolve(specifier, context, next) {
+  console.log('resolve passthru'); // This log is deliberate
+  return next(specifier, context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-receiving-modified-context.mjs b/test/fixtures/es-module-loaders/loader-resolve-receiving-modified-context.mjs
new file mode 100644
index 00000000000000..83aa83104e96e4
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-receiving-modified-context.mjs
@@ -0,0 +1,4 @@
+export async function resolve(specifier, context, next) {
+  console.log(context.foo); // This log is deliberate
+  return next(specifier, context);
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-shortcircuit.mjs b/test/fixtures/es-module-loaders/loader-resolve-shortcircuit.mjs
new file mode 100644
index 00000000000000..d886b3dfcbf237
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-shortcircuit.mjs
@@ -0,0 +1,6 @@
+export async function resolve(specifier) {
+  return {
+    shortCircuit: true,
+    url: specifier,
+  }
+}
diff --git a/test/fixtures/es-module-loaders/mock-loader.mjs b/test/fixtures/es-module-loaders/mock-loader.mjs
index 7c4592aca96834..062be39603e851 100644
--- a/test/fixtures/es-module-loaders/mock-loader.mjs
+++ b/test/fixtures/es-module-loaders/mock-loader.mjs
@@ -171,6 +171,7 @@ export function globalPreload({port}) {
 export async function resolve(specifier, context, defaultResolve) {
   if (specifier === 'node:mock') {
     return {
+      shortCircuit: true,
       url: specifier
     };
   }
@@ -180,10 +181,12 @@ export async function resolve(specifier, context, defaultResolve) {
     // Do nothing, let it get the "real" module
   } else if (mockedModuleExports.has(def.url)) {
     return {
+      shortCircuit: true,
       url: `mock-facade:${currentMockVersion}:${encodeURIComponent(def.url)}`
     };
   };
   return {
+    shortCircuit: true,
     url: def.url,
   };
 }
@@ -196,6 +199,7 @@ export async function load(url, context, defaultLoad) {
      * channel with preloadCode
      */
     return {
+      shortCircuit: true,
       source: 'export default import.meta.doMock',
       format: 'module'
     };
@@ -210,6 +214,7 @@ export async function load(url, context, defaultLoad) {
       decodeURIComponent(encodedTargetURL)
     ));
     return {
+      shortCircuit: true,
       source: ret,
       format: 'module'
     };
diff --git a/test/fixtures/es-module-loaders/string-sources.mjs b/test/fixtures/es-module-loaders/string-sources.mjs
index 384098d6d9e822..1fc2b7a8d6f7e3 100644
--- a/test/fixtures/es-module-loaders/string-sources.mjs
+++ b/test/fixtures/es-module-loaders/string-sources.mjs
@@ -22,7 +22,11 @@ const SOURCES = {
 }
 export function resolve(specifier, context, next) {
   if (specifier.startsWith('test:')) {
-    return { url: specifier, importAssertions: context.importAssertions };
+    return {
+      importAssertions: context.importAssertions,
+      shortCircuit: true,
+      url: specifier,
+    };
   }
   return next(specifier, context);
 }
@@ -31,6 +35,7 @@ export function load(href, context, next) {
   if (href.startsWith('test:')) {
     return {
       format: 'module',
+      shortCircuit: true,
       source: SOURCES[href],
     };
   }
diff --git a/test/parallel/test-module-main-fail.js b/test/parallel/test-module-main-fail.js
index c66b6f2f7a843f..31859a0d580ba4 100644
--- a/test/parallel/test-module-main-fail.js
+++ b/test/parallel/test-module-main-fail.js
@@ -10,7 +10,10 @@ for (const entryPoint of entryPoints) {
   try {
     execFileSync(node, [entryPoint], { stdio: 'pipe' });
   } catch (e) {
-    assert(e.toString().match(/Error: Cannot find module/));
+    const error = e.toString();
+    assert(error.match(/ERR_MODULE_NOT_FOUND/));
+    assert(error.match(/Cannot find module/));
+    assert(error.match(entryPoint));
     continue;
   }
   assert.fail('Executing node with inexistent entry point should ' +
diff --git a/test/parallel/test-module-parent-deprecation.js b/test/parallel/test-module-parent-deprecation.js
index e2533f87d417d0..839298bb46d89e 100644
--- a/test/parallel/test-module-parent-deprecation.js
+++ b/test/parallel/test-module-parent-deprecation.js
@@ -11,4 +11,4 @@ common.expectWarning(
   'DEP0144'
 );
 
-assert.strictEqual(module.parent, null);
+assert.strictEqual(module.parent, undefined);

From 1ad975bb338532acb87c664d3d46449585bc9d28 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C3=ABl=20Zasso?= <targos@protonmail.com>
Date: Sat, 30 Apr 2022 14:32:07 +0200
Subject: [PATCH 02/24] fix: --experimental-loader is an array

---
 lib/internal/modules/esm/loader.js              | 6 ++----
 lib/internal/modules/run_main.js                | 2 +-
 lib/internal/process/esm_loader.js              | 4 ++--
 test/parallel/test-module-main-fail.js          | 6 +++---
 test/parallel/test-module-parent-deprecation.js | 2 +-
 5 files changed, 9 insertions(+), 11 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 9329198890945d..fb0e6c2224100b 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -155,10 +155,8 @@ class ESMLoader {
    */
   translators = translators;
 
-  constructor({ isInternal = false } = ObjectCreate(null)) {
-    if (isInternal) return;
-
-    if (getOptionValue('--experimental-loader')?.length) {
+  constructor() {
+    if (getOptionValue('--experimental-loader').length > 0) {
       emitExperimentalWarning('Custom ESM Loaders');
     }
     if (getOptionValue('--experimental-network-imports')) {
diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index 924c4836bb2aa2..99bb289d1e2020 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -29,7 +29,7 @@ function resolveMainPath(main) {
 
 function shouldUseESMLoader(mainPath) {
   const userLoader = getOptionValue('--experimental-loader');
-  if (userLoader)
+  if (userLoader.length > 0)
     return true;
   const esModuleSpecifierResolution =
     getOptionValue('--experimental-specifier-resolution');
diff --git a/lib/internal/process/esm_loader.js b/lib/internal/process/esm_loader.js
index 51661ba7e754dd..4634ff5a9f5101 100644
--- a/lib/internal/process/esm_loader.js
+++ b/lib/internal/process/esm_loader.js
@@ -51,7 +51,7 @@ async function initializeLoader() {
   const { getOptionValue } = require('internal/options');
   const customLoaders = getOptionValue('--experimental-loader');
 
-  if (!customLoaders.length) return;
+  if (customLoaders.length === 0) return;
 
   let cwd;
   try {
@@ -63,7 +63,7 @@ async function initializeLoader() {
   // A separate loader instance is necessary to avoid cross-contamination
   // between internal Node.js and userland. For example, a module with internal
   // state (such as a counter) should be independent.
-  const internalEsmLoader = new ESMLoader({ isInternal: true });
+  const internalEsmLoader = new ESMLoader();
 
   // Importation must be handled by internal loader to avoid poluting userland
   const keyedExportsList = await internalEsmLoader.import(
diff --git a/test/parallel/test-module-main-fail.js b/test/parallel/test-module-main-fail.js
index 31859a0d580ba4..2b6f188dd4cbee 100644
--- a/test/parallel/test-module-main-fail.js
+++ b/test/parallel/test-module-main-fail.js
@@ -11,9 +11,9 @@ for (const entryPoint of entryPoints) {
     execFileSync(node, [entryPoint], { stdio: 'pipe' });
   } catch (e) {
     const error = e.toString();
-    assert(error.match(/ERR_MODULE_NOT_FOUND/));
-    assert(error.match(/Cannot find module/));
-    assert(error.match(entryPoint));
+    assert.match(error, /MODULE_NOT_FOUND/);
+    assert.match(error, /Cannot find module/);
+    assert(error.includes(entryPoint));
     continue;
   }
   assert.fail('Executing node with inexistent entry point should ' +
diff --git a/test/parallel/test-module-parent-deprecation.js b/test/parallel/test-module-parent-deprecation.js
index 839298bb46d89e..e2533f87d417d0 100644
--- a/test/parallel/test-module-parent-deprecation.js
+++ b/test/parallel/test-module-parent-deprecation.js
@@ -11,4 +11,4 @@ common.expectWarning(
   'DEP0144'
 );
 
-assert.strictEqual(module.parent, undefined);
+assert.strictEqual(module.parent, null);

From 3f4dfab57cdb2b922794af6d4d6470dfed0a719a Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 16:01:58 +0200
Subject: [PATCH 03/24] fixup: add breaking change warning to ESM loaders
 section

---
 doc/api/esm.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 4ed878d30a25ca..849e5d71da946b 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -679,6 +679,11 @@ of Node.js applications.
 <!-- YAML
 added: v8.8.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42623
+    description: Add support for loader chaining. This introduces a breaking
+      change, wherein a hook that does not call the next (or the default) hook
+      MUST include a `shortCircuit` flag.
   - version: v16.12.0
     pr-url: https://github.com/nodejs/node/pull/37468
     description: Removed `getFormat`, `getSource`, `transformSource`, and

From fa0cf39afd681a70b333505aa984350f9af85bd1 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 16:03:30 +0200
Subject: [PATCH 04/24] fixup: doc `userLoaders` within `shouldUseESMLoader()`

---
 lib/internal/modules/run_main.js | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index 99bb289d1e2020..b05f6e0b367363 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -28,8 +28,12 @@ function resolveMainPath(main) {
 }
 
 function shouldUseESMLoader(mainPath) {
-  const userLoader = getOptionValue('--experimental-loader');
-  if (userLoader.length > 0)
+  /**
+   * @var {string[]} userLoaders A list of custom loaders registered by the user
+   * (or an empty list when none have been registered).
+   */
+  const userLoaders = getOptionValue('--experimental-loader');
+  if (userLoaders.length > 0)
     return true;
   const esModuleSpecifierResolution =
     getOptionValue('--experimental-specifier-resolution');

From 7d6b80be71f41a527b93517b38ab6836d07afdc2 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 16:03:56 +0200
Subject: [PATCH 05/24] fixup: tidy tests

---
 test/es-module/test-esm-experimental-warnings.mjs | 2 +-
 test/es-module/test-esm-loader-chaining.mjs       | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/test/es-module/test-esm-experimental-warnings.mjs b/test/es-module/test-esm-experimental-warnings.mjs
index bc56d88f204015..b6ef757a88302e 100644
--- a/test/es-module/test-esm-experimental-warnings.mjs
+++ b/test/es-module/test-esm-experimental-warnings.mjs
@@ -4,7 +4,7 @@ import { doesNotMatch, match, strictEqual } from 'assert';
 import { spawn } from 'child_process';
 import { execPath } from 'process';
 
-// Verify no warnings are printed when no experimental features are enabled
+// Verify no warnings are printed when no experimental features are enabled or used
 {
   const input = `import ${JSON.stringify(fileURL('es-module-loaders', 'module-named-exports.mjs'))}`;
   const child = spawn(execPath, [
diff --git a/test/es-module/test-esm-loader-chaining.mjs b/test/es-module/test-esm-loader-chaining.mjs
index 9f89b4e2cf8aea..66c6ff10aa16b1 100644
--- a/test/es-module/test-esm-loader-chaining.mjs
+++ b/test/es-module/test-esm-loader-chaining.mjs
@@ -6,7 +6,7 @@ import { spawnSync } from 'node:child_process';
 const setupArgs = [
   '--no-warnings',
   '--input-type=module',
-  '-e',
+  '--eval',
 ];
 const commonInput = 'import fs from "node:fs"; console.log(fs)';
 const commonArgs = [

From 8cc538d7380fb60420912c731f8c0d3912c3f10b Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 16:05:01 +0200
Subject: [PATCH 06/24] fixup: tidy node internal paths for default hooks

---
 lib/internal/modules/esm/loader.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index fb0e6c2224100b..0df979cc7a066c 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -116,7 +116,7 @@ class ESMLoader {
   #loaders = [
     {
       fn: defaultLoad,
-      url: 'node:lib/internal/modules/esm/load.js',
+      url: 'node:internal/modules/esm/load',
     },
   ];
 
@@ -129,7 +129,7 @@ class ESMLoader {
   #resolvers = [
     {
       fn: defaultResolve,
-      url: 'node:lib/internal/modules/esm/resolve.js',
+      url: 'node:internal/modules/esm/resolve',
     },
   ];
 

From a20dc14ba81048f24584098f5152d724641131a1 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 22:58:37 +0200
Subject: [PATCH 07/24] fixup: restore `emittedSpecifierResolutionWarning`

---
 lib/internal/modules/esm/loader.js | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 0df979cc7a066c..51f18cc3244554 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -93,6 +93,8 @@ const {
 
 // [2] `validate...()`s throw the wrong error
 
+let emittedSpecifierResolutionWarning = false;
+
 /**
  * An ESMLoader instance is used as the main entry point for loading ES modules.
  * Currently, this is a singleton -- there is only one used for loading
@@ -162,11 +164,15 @@ class ESMLoader {
     if (getOptionValue('--experimental-network-imports')) {
       emitExperimentalWarning('Network Imports');
     }
-    if (getOptionValue('--experimental-specifier-resolution') === 'node') {
+    if (
+      !emittedSpecifierResolutionWarning &&
+      getOptionValue('--experimental-specifier-resolution') === 'node'
+    ) {
       process.emitWarning(
         'The Node.js specifier resolution flag is experimental. It could change or be removed at any time.',
         'ExperimentalWarning'
       );
+      emittedSpecifierResolutionWarning = true;
     }
   }
 

From 06803f134d1f44daa9942d9fab4b70ad375e472f Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Sun, 1 May 2022 23:18:10 +0200
Subject: [PATCH 08/24] fixup: doc ESMLoader hook methods

---
 lib/internal/modules/esm/loader.js | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 51f18cc3244554..ea7550ec09e5b8 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -376,6 +376,7 @@ class ESMLoader {
   async getModuleJob(specifier, parentURL, importAssertions) {
     let importAssertionsForResolve;
 
+    // By default, `this.#loaders` contains just the Node default load hook
     if (this.#loaders.length !== 1) {
       // We can skip cloning if there are no user-provided loaders because
       // the Node.js default resolve hook does not use import assertions.
@@ -496,6 +497,10 @@ class ESMLoader {
   /**
    * Provide source that is understood by one of Node's translators.
    *
+   * Internally, this behaves like a backwards iterator, wherein the stack of
+   * hooks starts at the top and each call to `next()` moves down 1 step until
+   * it reaches the bottom or short-circuits.
+   *
    * @param {URL['href']} url The URL/path of the module to be loaded
    * @param {object} context Metadata about the module
    * @returns {{ format: ModuleFormat, source: ModuleSource }}
@@ -700,8 +705,10 @@ class ESMLoader {
   /**
    * Resolve the location of the module.
    *
-   * The internals of this WILL change when chaining is implemented,
-   * depending on the resolution/consensus from #36954.
+   * Internally, this behaves like a backwards iterator, wherein the stack of
+   * hooks starts at the top and each call to `next()` moves down 1 step until
+   * it reaches the bottom or short-circuits.
+   *
    * @param {string} originalSpecifier The specified URL path of the module to
    *                                   be resolved.
    * @param {string} [parentURL] The URL path of the module's parent.

From db4f4eedc68d951ec9e3cfbb9206ee1ed9d666ef Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <webadmin@geoffreybooth.com>
Date: Sun, 1 May 2022 20:32:10 -0700
Subject: [PATCH 09/24] fixup: use correct JSDoc tag

---
 lib/internal/modules/run_main.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/internal/modules/run_main.js b/lib/internal/modules/run_main.js
index b05f6e0b367363..5a50d5d6afab6e 100644
--- a/lib/internal/modules/run_main.js
+++ b/lib/internal/modules/run_main.js
@@ -29,7 +29,7 @@ function resolveMainPath(main) {
 
 function shouldUseESMLoader(mainPath) {
   /**
-   * @var {string[]} userLoaders A list of custom loaders registered by the user
+   * @type {string[]} userLoaders A list of custom loaders registered by the user
    * (or an empty list when none have been registered).
    */
   const userLoaders = getOptionValue('--experimental-loader');

From 7588a2f7c99fc4bf853a66b3c87fd351fee0e415 Mon Sep 17 00:00:00 2001
From: Geoffrey Booth <456802+GeoffreyBooth@users.noreply.github.com>
Date: Mon, 2 May 2022 00:39:05 -0700
Subject: [PATCH 10/24] fixup: tidy code styles & clarify var names (#1)

* fixup: eslint curly for new code in esm/loader.js
* fixup: nit: 0 > -1
* fixup: rename i to hookIndex
* fixup: function assignment syntax
* fixup: more explicit decrement
---
 lib/internal/modules/esm/loader.js | 68 +++++++++++++++++-------------
 1 file changed, 39 insertions(+), 29 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index ea7550ec09e5b8..e0f203122e5ce8 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -468,7 +468,7 @@ class ESMLoader {
    */
   async import(specifiers, parentURL, importAssertions) {
     const wasArr = ArrayIsArray(specifiers);
-    if (!wasArr) specifiers = [specifiers];
+    if (!wasArr) { specifiers = [specifiers]; }
 
     const count = specifiers.length;
     const jobs = new Array(count);
@@ -481,7 +481,7 @@ class ESMLoader {
 
     const namespaces = await PromiseAll(new SafeArrayIterator(jobs));
 
-    if (!wasArr) return namespaces[0];
+    if (!wasArr) { return namespaces[0]; }
 
     for (let i = 0; i < count; i++) {
       const namespace = ObjectCreate(null);
@@ -507,20 +507,23 @@ class ESMLoader {
    */
   async load(url, context = {}) {
     const loaders = this.#loaders;
-    let i = loaders.length - 1;
+    let hookIndex = loaders.length - 1;
     let {
       fn: loader,
       url: loaderFilePath,
-    } = loaders[i];
-    let chainFinished = i === 0;
+    } = loaders[hookIndex];
+    let chainFinished = hookIndex === 0;
+
+    const next = (nextUrl, ctx = context) => {
+      // `next` has been called, so decrement our pointer
+      --hookIndex;
 
-    function next(nextUrl, ctx = context) {
       ({
         fn: loader,
         url: loaderFilePath,
-      } = loaders[--i]);
+      } = loaders[hookIndex]);
 
-      if (i === 0) chainFinished = true;
+      if (hookIndex === 0) { chainFinished = true; }
 
       const hookErrIdentifier = `${loaderFilePath} "load"`;
 
@@ -547,7 +550,7 @@ class ESMLoader {
       validateObject(ctx, `${hookErrIdentifier} next(, context)`);
 
       return loader(nextUrl, ctx, next);
-    }
+    };
 
     const loaded = await loader(
       url,
@@ -600,12 +603,14 @@ class ESMLoader {
       typeof source !== 'string' &&
       !isAnyArrayBuffer(source) &&
       !isArrayBufferView(source)
-    ) throw ERR_INVALID_RETURN_PROPERTY_VALUE(
-      'a string, an ArrayBuffer, or a TypedArray',
-      hookErrIdentifier,
-      'source',
-      source
-    );
+    ) {
+      throw ERR_INVALID_RETURN_PROPERTY_VALUE(
+        'a string, an ArrayBuffer, or a TypedArray',
+        hookErrIdentifier,
+        'source',
+        source
+      );
+    }
 
     return {
       format,
@@ -614,7 +619,7 @@ class ESMLoader {
   }
 
   preload() {
-    for (let i = this.#globalPreloaders.length - 1; i > -1; i--) {
+    for (let i = this.#globalPreloaders.length - 1; i >= 0; i--) {
       const channel = new MessageChannel();
       const {
         port1: insidePreload,
@@ -633,7 +638,7 @@ class ESMLoader {
         port: insideLoader,
       });
 
-      if (preload == null) return;
+      if (preload == null) { return; }
 
       const hookErrIdentifier = `${specifier} globalPreload`;
 
@@ -727,19 +732,21 @@ class ESMLoader {
       !isMain &&
       typeof parentURL !== 'string' &&
       !isURLInstance(parentURL)
-    ) throw new ERR_INVALID_ARG_TYPE(
-      'parentURL',
-      ['string', 'URL'],
-      parentURL,
-    );
+    ) {
+      throw new ERR_INVALID_ARG_TYPE(
+        'parentURL',
+        ['string', 'URL'],
+        parentURL,
+      );
+    }
     const resolvers = this.#resolvers;
 
-    let i = resolvers.length - 1;
+    let hookIndex = resolvers.length - 1;
     let {
       url: resolverFilePath,
       fn: resolver,
-    } = resolvers[i];
-    let chainFinished = i === 0;
+    } = resolvers[hookIndex];
+    let chainFinished = hookIndex === 0;
 
     const context = {
       conditions: DEFAULT_CONDITIONS,
@@ -747,13 +754,16 @@ class ESMLoader {
       parentURL,
     };
 
-    function next(suppliedSpecifier, ctx = context) {
+    const next = (suppliedSpecifier, ctx = context) => {
+      // `next` has been called, so decrement our pointer
+      --hookIndex;
+
       ({
         fn: resolver,
         url: resolverFilePath,
-      } = resolvers[--i]);
+      } = resolvers[hookIndex]);
 
-      if (i === 0) chainFinished = true;
+      if (hookIndex === 0) { chainFinished = true; }
 
       const hookErrIdentifier = `${resolverFilePath} "resolve"`;
 
@@ -765,7 +775,7 @@ class ESMLoader {
       validateObject(ctx, `${hookErrIdentifier} next(, context)`);
 
       return resolver(suppliedSpecifier, ctx, next);
-    }
+    };
 
     const resolution = await resolver(
       originalSpecifier,

From 859fd8873f55439a3b8dce2abf4e32decb17a06f Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Mon, 2 May 2022 20:59:45 +0200
Subject: [PATCH 11/24] =?UTF-8?q?fixup:=20`next`=20=E2=86=92=20`nextResolv?=
 =?UTF-8?q?e`=20&=20`nextLoad`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 doc/api/esm.md | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 849e5d71da946b..f9b04afbb88550 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -726,7 +726,7 @@ A hook that fails to return triggers an exception. A hook that returns without
 calling `next()` and without returning `shortCircuit: true` also triggers an
 exception. These errors are to help prevent unintentional breaks in the chain.
 
-#### `resolve(specifier, context, next)`
+#### `resolve(specifier, context, nextResolve)`
 
 <!-- YAML
 changes:
@@ -750,8 +750,8 @@ changes:
   * `importAssertions` {Object}
   * `parentURL` {string|undefined} The module importing this one, or undefined
     if this is the Node.js entry point
-* `next` {Function} The subsequent `resolve` hook in the chain, or the Node.js
-  default `resolve` hook after the last user-supplied `resolve` hook
+* `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}
 * Returns: {Object}
@@ -788,7 +788,7 @@ Node.js module specifier resolution behavior_ when calling `defaultResolve`, the
 `context.conditions` array originally passed into the `resolve` hook.
 
 ```js
-export async function resolve(specifier, context, next) {
+export async function resolve(specifier, context, nextResolve) {
   const { parentURL = null } = context;
 
   if (Math.random() > 0.5) { // Some condition.
@@ -805,7 +805,7 @@ export async function resolve(specifier, context, next) {
   if (Math.random() < 0.5) { // Another condition.
     // When calling `defaultResolve`, the arguments can be modified. In this
     // case it's adding another value for matching conditional exports.
-    return next(specifier, {
+    return nextResolve(specifier, {
       ...context,
       conditions: [...context.conditions, 'another-condition'],
     });
@@ -813,11 +813,11 @@ export async function resolve(specifier, context, next) {
 
   // Defer to the next hook in the chain, which would be the
   // Node.js default resolve if this is the last user-specified loader.
-  return next(specifier, context);
+  return nextResolve(specifier, context);
 }
 ```
 
-#### `load(url, context, next)`
+#### `load(url, context, nextLoad)`
 
 > The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
@@ -831,8 +831,8 @@ export async function resolve(specifier, context, next) {
   * `format` {string|null|undefined} The format optionally supplied by the
     `resolve` hook chain
   * `importAssertions` {Object}
-* `next` {Function} The subsequent `load` hook in the chain, or the Node.js
-  default `load` hook after the last user-supplied `load` hook
+* `nextLoad` {Function} The subsequent `load` hook in the chain, or the
+  Node.js default `load` hook after the last user-supplied `load` hook
   * `specifier` {string}
   * `context` {Object}
 * Returns: {Object}
@@ -880,7 +880,7 @@ avoid reading files from disk. It could also be used to map an unrecognized
 format to a supported one, for example `yaml` to `module`.
 
 ```js
-export async function load(url, context, next) {
+export async function load(url, context, nextLoad) {
   const { format } = context;
 
   if (Math.random() > 0.5) { // Some condition
@@ -899,7 +899,7 @@ export async function load(url, context, next) {
   }
 
   // Defer to the next hook in the chain.
-  return next(url, context);
+  return nextLoad(url, context);
 }
 ```
 
@@ -989,7 +989,7 @@ and there is no security.
 // https-loader.mjs
 import { get } from 'node:https';
 
-export function resolve(specifier, context, next) {
+export function resolve(specifier, context, nextResolve) {
   const { parentURL = null } = context;
 
   // Normally Node.js would error on specifiers starting with 'https://', so
@@ -1008,10 +1008,10 @@ export function resolve(specifier, context, next) {
   }
 
   // Let Node.js handle all other specifiers.
-  return next(specifier, context);
+  return nextResolve(specifier, context);
 }
 
-export function load(url, context, next) {
+export function load(url, context, nextLoad) {
   // For JavaScript to be loaded over the network, we need to fetch and
   // return it.
   if (url.startsWith('https://')) {
@@ -1031,7 +1031,7 @@ export function load(url, context, next) {
   }
 
   // Let Node.js handle all other URLs.
-  return next(url, context);
+  return nextLoad(url, context);
 }
 ```
 
@@ -1071,7 +1071,7 @@ const baseURL = pathToFileURL(`${cwd()}/`).href;
 // CoffeeScript files end in .coffee, .litcoffee or .coffee.md.
 const extensionsRegex = /\.coffee$|\.litcoffee$|\.coffee\.md$/;
 
-export async function resolve(specifier, context, next) {
+export async function resolve(specifier, context, nextResolve) {
   if (extensionsRegex.test(specifier)) {
     const { parentURL = baseURL } = context;
 
@@ -1084,10 +1084,10 @@ export async function resolve(specifier, context, next) {
   }
 
   // Let Node.js handle all other specifiers.
-  return next(specifier, context);
+  return nextResolve(specifier, context);
 }
 
-export async function load(url, context, next) {
+export async function load(url, context, nextLoad) {
   if (extensionsRegex.test(url)) {
     // Now that we patched resolve to let CoffeeScript URLs through, we need to
     // tell Node.js what format such URLs should be interpreted as. Because
@@ -1112,7 +1112,7 @@ export async function load(url, context, next) {
       };
     }
 
-    const { source: rawSource } = await next(url, { ...context, format });
+    const { source: rawSource } = await nextLoad(url, { ...context, format });
     // This hook converts CoffeeScript source code into JavaScript source code
     // for all imported CoffeeScript files.
     const transformedSource = coffeeCompile(rawSource.toString(), url);
@@ -1125,7 +1125,7 @@ export async function load(url, context, next) {
   }
 
   // Let Node.js handle all other URLs.
-  return next(url, context);
+  return nextLoad(url, context);
 }
 
 async function getPackageType(url) {

From cea547386165b5f3b3eebd8bcef2b03ec8aa5aa0 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Mon, 2 May 2022 22:22:10 +0200
Subject: [PATCH 12/24] fixup: account for nested hook short-circuiting

---
 lib/internal/modules/esm/loader.js            | 48 +++++++++-------
 test/es-module/test-esm-loader-chaining.mjs   | 57 +++++++++++++++++--
 .../loader-load-next-modified.mjs             | 11 ++++
 .../loader-resolve-next-modified.mjs          | 11 ++++
 4 files changed, 103 insertions(+), 24 deletions(-)
 create mode 100644 test/fixtures/es-module-loaders/loader-load-next-modified.mjs
 create mode 100644 test/fixtures/es-module-loaders/loader-resolve-next-modified.mjs

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index e0f203122e5ce8..c79f26c770f153 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -513,10 +513,10 @@ class ESMLoader {
       url: loaderFilePath,
     } = loaders[hookIndex];
     let chainFinished = hookIndex === 0;
+    let shortCircuited = false;
 
-    const next = (nextUrl, ctx = context) => {
-      // `next` has been called, so decrement our pointer
-      --hookIndex;
+    const next = async (nextUrl, ctx = context) => {
+      --hookIndex; // `next` has been called, so decrement our pointer
 
       ({
         fn: loader,
@@ -549,7 +549,11 @@ class ESMLoader {
 
       validateObject(ctx, `${hookErrIdentifier} next(, context)`);
 
-      return loader(nextUrl, ctx, next);
+      const output = await loader(nextUrl, ctx, next);
+
+      if (output?.shortCircuit === true) { shortCircuited = true; }
+
+      return output;
     };
 
     const loaded = await loader(
@@ -568,16 +572,17 @@ class ESMLoader {
       );
     }
 
+    if (loaded?.shortCircuit === true) { shortCircuited = true; }
+
+    if (!chainFinished && !shortCircuited) {
+      throw new ERR_LOADER_CHAIN_INCOMPLETE('load', loaderFilePath);
+    }
+
     const {
       format,
-      shortCircuit,
       source,
     } = loaded;
 
-    if (!chainFinished && !shortCircuit) {
-      throw new ERR_LOADER_CHAIN_INCOMPLETE('load', loaderFilePath);
-    }
-
     if (format == null) {
       const dataUrl = RegExpPrototypeExec(
         /^data:([^/]+\/[^;,]+)(?:[^,]*?)(;base64)?,/,
@@ -743,10 +748,11 @@ class ESMLoader {
 
     let hookIndex = resolvers.length - 1;
     let {
-      url: resolverFilePath,
       fn: resolver,
+      url: resolverFilePath,
     } = resolvers[hookIndex];
     let chainFinished = hookIndex === 0;
+    let shortCircuited = false;
 
     const context = {
       conditions: DEFAULT_CONDITIONS,
@@ -754,9 +760,8 @@ class ESMLoader {
       parentURL,
     };
 
-    const next = (suppliedSpecifier, ctx = context) => {
-      // `next` has been called, so decrement our pointer
-      --hookIndex;
+    const next = async (suppliedSpecifier, ctx = context) => {
+      --hookIndex; // `next` has been called, so decrement our pointer
 
       ({
         fn: resolver,
@@ -774,7 +779,11 @@ class ESMLoader {
 
       validateObject(ctx, `${hookErrIdentifier} next(, context)`);
 
-      return resolver(suppliedSpecifier, ctx, next);
+      const output = await resolver(suppliedSpecifier, ctx, next);
+
+      if (output?.shortCircuit === true) { shortCircuited = true; }
+
+      return output;
     };
 
     const resolution = await resolver(
@@ -793,16 +802,17 @@ class ESMLoader {
       );
     }
 
+    if (resolution?.shortCircuit === true) { shortCircuited = true; }
+
+    if (!chainFinished && !shortCircuited) {
+      throw new ERR_LOADER_CHAIN_INCOMPLETE('resolve', resolverFilePath);
+    }
+
     const {
       format,
-      shortCircuit,
       url,
     } = resolution;
 
-    if (!chainFinished && !shortCircuit) {
-      throw new ERR_LOADER_CHAIN_INCOMPLETE('resolve', resolverFilePath);
-    }
-
     if (
       format != null &&
       typeof format !== 'string' // [2]
diff --git a/test/es-module/test-esm-loader-chaining.mjs b/test/es-module/test-esm-loader-chaining.mjs
index 66c6ff10aa16b1..8f20d202033c04 100644
--- a/test/es-module/test-esm-loader-chaining.mjs
+++ b/test/es-module/test-esm-loader-chaining.mjs
@@ -15,7 +15,7 @@ const commonArgs = [
 ];
 
 { // Verify unadulterated source is loaded when there are no loaders
-  const { status, stdout } = spawnSync(
+  const { status, stderr, stdout } = spawnSync(
     process.execPath,
     [
       ...setupArgs,
@@ -24,12 +24,13 @@ const commonArgs = [
     { encoding: 'utf8' },
   );
 
+  assert.strictEqual(stderr, '');
   assert.strictEqual(status, 0);
   assert.match(stdout, /number/); // node:fs is an object
 }
 
 { // Verify loaded source is properly different when only load changes something
-  const { status, stdout } = spawnSync(
+  const { status, stderr, stdout } = spawnSync(
     process.execPath,
     [
       '--loader',
@@ -43,6 +44,7 @@ const commonArgs = [
     { encoding: 'utf8' },
   );
 
+  assert.strictEqual(stderr, '');
   assert.match(stdout, /load passthru/);
   assert.match(stdout, /resolve passthru/);
   assert.strictEqual(status, 0);
@@ -50,7 +52,7 @@ const commonArgs = [
 }
 
 { // Verify multiple changes from hooks result in proper output
-  const { status, stdout } = spawnSync(
+  const { status, stderr, stdout } = spawnSync(
     process.execPath,
     [
       '--loader',
@@ -66,13 +68,14 @@ const commonArgs = [
     { encoding: 'utf8' },
   );
 
+  assert.strictEqual(stderr, '');
   assert.match(stdout, /resolve 42/); // It did go thru resolve-42
   assert.strictEqual(status, 0);
   assert.match(stdout, /foo/); // LIFO, so resolve-foo won
 }
 
 { // Verify modifying context within resolve chain is respected
-  const { status, stdout } = spawnSync(
+  const { status, stderr, stdout } = spawnSync(
     process.execPath,
     [
       '--loader',
@@ -90,12 +93,13 @@ const commonArgs = [
     { encoding: 'utf8' },
   );
 
+  assert.strictEqual(stderr, '');
   assert.match(stdout, /bar/);
   assert.strictEqual(status, 0);
 }
 
 { // Verify multiple changes from hooks result in proper output
-  const { status, stdout } = spawnSync(
+  const { status, stderr, stdout } = spawnSync(
     process.execPath,
     [
       '--loader',
@@ -111,6 +115,7 @@ const commonArgs = [
     { encoding: 'utf8' },
   );
 
+  assert.strictEqual(stderr, '');
   assert.match(stdout, /resolve foo/); // It did go thru resolve-foo
   assert.strictEqual(status, 0);
   assert.match(stdout, /42/); // LIFO, so resolve-42 won
@@ -138,6 +143,48 @@ const commonArgs = [
   assert.match(stderr, /"resolve"/);
 }
 
+{ // Verify error NOT thrown when nested resolve hook signaled a short circuit
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-next-modified.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(stderr, '');
+  assert.strictEqual(stdout.trim(), 'foo');
+  assert.strictEqual(status, 0);
+}
+
+{ // Verify error NOT thrown when nested load hook signaled a short circuit
+  const { status, stderr, stdout } = spawnSync(
+    process.execPath,
+    [
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      '--loader',
+      fixtures.path('es-module-loaders/loader-load-next-modified.mjs'),
+      ...commonArgs,
+    ],
+    { encoding: 'utf8' },
+  );
+
+  assert.strictEqual(stderr, '');
+  assert.match(stdout, /421/);
+  assert.strictEqual(status, 0);
+}
+
 { // Verify chain does break and throws appropriately
   const { status, stderr, stdout } = spawnSync(
     process.execPath,
diff --git a/test/fixtures/es-module-loaders/loader-load-next-modified.mjs b/test/fixtures/es-module-loaders/loader-load-next-modified.mjs
new file mode 100644
index 00000000000000..1f2382467f7122
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-load-next-modified.mjs
@@ -0,0 +1,11 @@
+export async function load(url, context, next) {
+  const {
+    format,
+    source,
+  } = await next(url, context);
+
+  return {
+    format,
+    source: source + 1,
+  };
+}
diff --git a/test/fixtures/es-module-loaders/loader-resolve-next-modified.mjs b/test/fixtures/es-module-loaders/loader-resolve-next-modified.mjs
new file mode 100644
index 00000000000000..a973345a82ff21
--- /dev/null
+++ b/test/fixtures/es-module-loaders/loader-resolve-next-modified.mjs
@@ -0,0 +1,11 @@
+export async function resolve(url, context, next) {
+  const {
+    format,
+    url: nextUrl,
+  } = await next(url, context);
+
+  return {
+    format,
+    url: `${nextUrl}?foo`,
+  };
+}

From b56112f52756a9065232b66be0fa50cdbdd6558c Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Mon, 2 May 2022 22:31:38 +0200
Subject: [PATCH 13/24] fixup: optimise loadNext's internal validity check on
 `url`

---
 lib/internal/modules/esm/loader.js | 21 ++++++++++++---------
 1 file changed, 12 insertions(+), 9 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index c79f26c770f153..1bb75356734abc 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -537,14 +537,17 @@ class ESMLoader {
         );
       }
 
-      try {
-        new URL(nextUrl);
-      } catch {
-        throw new ERR_INVALID_ARG_VALUE(
-          `${hookErrIdentifier} next(url)`,
-          nextUrl,
-          'should be a url string',
-        );
+      // Try to avoid expensive URL instantiation for known-good urls
+      if (!this.moduleMap.has(nextUrl)) {
+        try {
+          new URL(nextUrl);
+        } catch {
+          throw new ERR_INVALID_ARG_VALUE(
+            `${hookErrIdentifier} next(url)`,
+            nextUrl,
+            'should be a url string',
+          );
+        }
       }
 
       validateObject(ctx, `${hookErrIdentifier} next(, context)`);
@@ -838,7 +841,7 @@ class ESMLoader {
 
     try {
       new URL(url);
-    } catch (err) { // eslint-disable-line no-unused-vars
+    } catch {
       throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
         'a url string',
         hookErrIdentifier,

From 7cc33e42da03fc78266b3e0d67041e2f0075ced5 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:00:35 +0200
Subject: [PATCH 14/24] fixup: tidy ESM doc & add changelog info

---
 doc/api/esm.md | 41 +++++++++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index f9b04afbb88550..59c1de4ca729e8 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -679,11 +679,10 @@ of Node.js applications.
 <!-- YAML
 added: v8.8.0
 changes:
-  - version: REPLACEME
+  - version:
+    - REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for loader chaining. This introduces a breaking
-      change, wherein a hook that does not call the next (or the default) hook
-      MUST include a `shortCircuit` flag.
+    description: Add support for chaining loaders.
   - version: v16.12.0
     pr-url: https://github.com/nodejs/node/pull/37468
     description: Removed `getFormat`, `getSource`, `transformSource`, and
@@ -719,21 +718,23 @@ These are called in the following sequence: `cache-buster` calls
 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()`, which is a reference to the
-subsequent loader’s hook.
+as a result of each function calling `next<hookName>()`, which is a reference
+to the subsequent loader’s hook.
 
 A hook that fails to return triggers an exception. A hook that returns without
-calling `next()` and without returning `shortCircuit: true` also triggers an
-exception. These errors are to help prevent unintentional breaks in the chain.
+calling `next<hookName>()` and without returning `shortCircuit: true` also
+triggers an exception. These errors are to help prevent unintentional breaks in
+the chain.
 
 #### `resolve(specifier, context, nextResolve)`
 
 <!-- YAML
 changes:
-  - version:
-    - REPLACEME
+  - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining loaders.
+    description: Add support for chaining resolve hooks. This introduces a
+      breaking change, wherein a hook that does not call `nextResolve()` MUST
+      include a `shortCircuit` flag in its return.
   - version:
     - v17.1.0
     - v16.14.0
@@ -819,6 +820,15 @@ export async function resolve(specifier, context, nextResolve) {
 
 #### `load(url, context, nextLoad)`
 
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42623
+    description: Add support for chaining load hooks. This introduces a
+      breaking change, wherein a hook that does not call `nextLoad()` MUST
+      include a `shortCircuit` flag in its return.
+-->
+
 > The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
@@ -908,6 +918,13 @@ source to a supported one (see [Examples](#examples) below).
 
 #### `globalPreload()`
 
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/42623
+    description: Add support for chaining globalPreload hooks.
+-->
+
 > The loaders API is being redesigned. This hook may disappear or its
 > signature may change. Do not rely on the API described below.
 
@@ -1035,7 +1052,7 @@ export function load(url, context, nextLoad) {
 }
 ```
 
-```mjs
+```js
 // main.mjs
 import { VERSION } from 'https://coffeescript.org/browser-compiler-modern/coffeescript.js';
 

From 6bb5359d70de192bd82c42a43947f59939d8ff05 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:02:32 +0200
Subject: [PATCH 15/24] =?UTF-8?q?fixup:=20update=20internals=20for=20`next?=
 =?UTF-8?q?()`=20=E2=86=92=20`next<hookName>()`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/internal/modules/esm/loader.js          | 32 ++++++++++-----------
 test/es-module/test-esm-loader-chaining.mjs | 10 +++----
 2 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 1bb75356734abc..cfd4b3410f965c 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -498,8 +498,8 @@ class ESMLoader {
    * Provide source that is understood by one of Node's translators.
    *
    * Internally, this behaves like a backwards iterator, wherein the stack of
-   * hooks starts at the top and each call to `next()` moves down 1 step until
-   * it reaches the bottom or short-circuits.
+   * hooks starts at the top and each call to `nextLoad()` moves down 1 step
+   * until it reaches the bottom or short-circuits.
    *
    * @param {URL['href']} url The URL/path of the module to be loaded
    * @param {object} context Metadata about the module
@@ -515,7 +515,7 @@ class ESMLoader {
     let chainFinished = hookIndex === 0;
     let shortCircuited = false;
 
-    const next = async (nextUrl, ctx = context) => {
+    const nextLoad = async (nextUrl, ctx = context) => {
       --hookIndex; // `next` has been called, so decrement our pointer
 
       ({
@@ -531,7 +531,7 @@ class ESMLoader {
         // non-strings can be coerced to a url string
         // validateString() throws a less-specific error
         throw new ERR_INVALID_ARG_TYPE(
-          `${hookErrIdentifier} next(url)`,
+          `${hookErrIdentifier} nextLoad(url)`,
           'a url string',
           nextUrl,
         );
@@ -543,16 +543,16 @@ class ESMLoader {
           new URL(nextUrl);
         } catch {
           throw new ERR_INVALID_ARG_VALUE(
-            `${hookErrIdentifier} next(url)`,
+            `${hookErrIdentifier} nextLoad(url)`,
             nextUrl,
             'should be a url string',
           );
         }
       }
 
-      validateObject(ctx, `${hookErrIdentifier} next(, context)`);
+      validateObject(ctx, `${hookErrIdentifier} nextLoad(, context)`);
 
-      const output = await loader(nextUrl, ctx, next);
+      const output = await loader(nextUrl, ctx, nextLoad);
 
       if (output?.shortCircuit === true) { shortCircuited = true; }
 
@@ -562,7 +562,7 @@ class ESMLoader {
     const loaded = await loader(
       url,
       context,
-      next,
+      nextLoad,
     );
 
     const hookErrIdentifier = `${loaderFilePath} load`;
@@ -719,8 +719,8 @@ class ESMLoader {
    * Resolve the location of the module.
    *
    * Internally, this behaves like a backwards iterator, wherein the stack of
-   * hooks starts at the top and each call to `next()` moves down 1 step until
-   * it reaches the bottom or short-circuits.
+   * hooks starts at the top and each call to `nextResolve()` moves down 1 step
+   * until it reaches the bottom or short-circuits.
    *
    * @param {string} originalSpecifier The specified URL path of the module to
    *                                   be resolved.
@@ -763,8 +763,8 @@ class ESMLoader {
       parentURL,
     };
 
-    const next = async (suppliedSpecifier, ctx = context) => {
-      --hookIndex; // `next` has been called, so decrement our pointer
+    const nextResolve = async (suppliedSpecifier, ctx = context) => {
+      --hookIndex; // `nextResolve` has been called, so decrement our pointer
 
       ({
         fn: resolver,
@@ -777,12 +777,12 @@ class ESMLoader {
 
       validateString(
         suppliedSpecifier,
-        `${hookErrIdentifier} next(specifier)`,
+        `${hookErrIdentifier} nextResolve(specifier)`,
       ); // non-strings can be coerced to a url string
 
-      validateObject(ctx, `${hookErrIdentifier} next(, context)`);
+      validateObject(ctx, `${hookErrIdentifier} nextResolve(, context)`);
 
-      const output = await resolver(suppliedSpecifier, ctx, next);
+      const output = await resolver(suppliedSpecifier, ctx, nextResolve);
 
       if (output?.shortCircuit === true) { shortCircuited = true; }
 
@@ -792,7 +792,7 @@ class ESMLoader {
     const resolution = await resolver(
       originalSpecifier,
       context,
-      next,
+      nextResolve,
     );
 
     const hookErrIdentifier = `${resolverFilePath} resolve`;
diff --git a/test/es-module/test-esm-loader-chaining.mjs b/test/es-module/test-esm-loader-chaining.mjs
index 8f20d202033c04..42369c732d068e 100644
--- a/test/es-module/test-esm-loader-chaining.mjs
+++ b/test/es-module/test-esm-loader-chaining.mjs
@@ -268,7 +268,7 @@ const commonArgs = [
   assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
   assert.match(stderr, /loader-resolve-bad-next-specifier\.mjs/);
   assert.match(stderr, /"resolve"/);
-  assert.match(stderr, /next\(specifier\)/);
+  assert.match(stderr, /nextResolve\(specifier\)/);
 }
 
 { // Verify error thrown when invalid `context` argument passed to `resolve…next`
@@ -288,7 +288,7 @@ const commonArgs = [
   assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
   assert.match(stderr, /loader-resolve-bad-next-context\.mjs/);
   assert.match(stderr, /"resolve"/);
-  assert.match(stderr, /next\(, context\)/);
+  assert.match(stderr, /nextResolve\(, context\)/);
 }
 
 { // Verify error thrown when invalid `url` argument passed to `load…next`
@@ -308,7 +308,7 @@ const commonArgs = [
   assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
   assert.match(stderr, /loader-load-bad-next-url\.mjs/);
   assert.match(stderr, /"load"/);
-  assert.match(stderr, /next\(url\)/);
+  assert.match(stderr, /nextLoad\(url\)/);
 }
 
 { // Verify error thrown when invalid `url` argument passed to `load…next`
@@ -328,7 +328,7 @@ const commonArgs = [
   assert.match(stderr, /ERR_INVALID_ARG_VALUE/);
   assert.match(stderr, /loader-load-impersonating-next-url\.mjs/);
   assert.match(stderr, /"load"/);
-  assert.match(stderr, /next\(url\)/);
+  assert.match(stderr, /nextLoad\(url\)/);
 }
 
 { // Verify error thrown when invalid `context` argument passed to `load…next`
@@ -348,5 +348,5 @@ const commonArgs = [
   assert.match(stderr, /ERR_INVALID_ARG_TYPE/);
   assert.match(stderr, /loader-load-bad-next-context\.mjs/);
   assert.match(stderr, /"load"/);
-  assert.match(stderr, /next\(, context\)/);
+  assert.match(stderr, /nextLoad\(, context\)/);
 }

From 9fc7ba5326ab68e3e6afea3f00f831e2a62ee603 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:03:20 +0200
Subject: [PATCH 16/24] =?UTF-8?q?fixup:=20`fixtures.path()`=20=E2=86=92=20?=
 =?UTF-8?q?`fixtures.fileURL()`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 test/es-module/test-esm-loader-chaining.mjs | 90 ++++++++++-----------
 1 file changed, 45 insertions(+), 45 deletions(-)

diff --git a/test/es-module/test-esm-loader-chaining.mjs b/test/es-module/test-esm-loader-chaining.mjs
index 42369c732d068e..1055c44a156a77 100644
--- a/test/es-module/test-esm-loader-chaining.mjs
+++ b/test/es-module/test-esm-loader-chaining.mjs
@@ -34,11 +34,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -56,13 +56,13 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-shortcircuit.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-foo.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-foo.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -79,15 +79,15 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-shortcircuit.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-receiving-modified-context.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-receiving-modified-context.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passing-modified-context.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passing-modified-context.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -103,13 +103,13 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-shortcircuit.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-foo.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-foo.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -126,11 +126,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-incomplete.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-incomplete.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -148,11 +148,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-shortcircuit.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-next-modified.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-next-modified.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -168,13 +168,13 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-shortcircuit.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-shortcircuit.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-next-modified.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-next-modified.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -190,11 +190,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-incomplete.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-incomplete.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-foo-or-42.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-foo-or-42.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -212,11 +212,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-incomplete.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-incomplete.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -234,11 +234,11 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-incomplete.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-incomplete.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -256,9 +256,9 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-bad-next-specifier.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-bad-next-specifier.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -276,9 +276,9 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-resolve-bad-next-context.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-resolve-bad-next-context.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -296,9 +296,9 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-bad-next-url.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-bad-next-url.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -316,9 +316,9 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-impersonating-next-url.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-impersonating-next-url.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },
@@ -336,9 +336,9 @@ const commonArgs = [
     process.execPath,
     [
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-passthru.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-passthru.mjs'),
       '--loader',
-      fixtures.path('es-module-loaders/loader-load-bad-next-context.mjs'),
+      fixtures.fileURL('es-module-loaders', 'loader-load-bad-next-context.mjs'),
       ...commonArgs,
     ],
     { encoding: 'utf8' },

From 1c712e99817a0697478818bd376b398acc9e5d73 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:04:12 +0200
Subject: [PATCH 17/24] =?UTF-8?q?fixup:=20code=20doc=20for=20ESMLoader::im?=
 =?UTF-8?q?port()=20=E2=80=A6=20namespaces?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/internal/modules/esm/loader.js | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index cfd4b3410f965c..26f29a043203d0 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -464,9 +464,18 @@ class ESMLoader {
    * @param {Record<string, string>} importAssertions Validations for the
    *                                                  module import.
    * @returns {Promise<ExportedHooks | KeyedExports[]>}
-   *  A collection of module export(s).
+   *  A collection of module export(s) or a list of collections of module
+   *  export(s).
    */
   async import(specifiers, parentURL, importAssertions) {
+    // For loaders, `import` is passed multiple things to process, it returns a
+    // list pairing the url and exports collected. This is especially useful for
+    // error messaging, to identity from where an export came. But, in most
+    // cases, only a single url is being "imported" (ex `import()`), so there is
+    // only 1 possible url from which the exports were collected and it is
+    // already known to the caller. Nesting that in a list would only ever
+    // create redundant work for the caller, so it is later popped off the
+    // internal list.
     const wasArr = ArrayIsArray(specifiers);
     if (!wasArr) { specifiers = [specifiers]; }
 
@@ -481,7 +490,7 @@ class ESMLoader {
 
     const namespaces = await PromiseAll(new SafeArrayIterator(jobs));
 
-    if (!wasArr) { return namespaces[0]; }
+    if (!wasArr) { return namespaces[0]; } // We can skip the pairing below
 
     for (let i = 0; i < count; i++) {
       const namespace = ObjectCreate(null);

From 21bd600f158b4d98219741793d037509f46d9988 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:10:18 +0200
Subject: [PATCH 18/24] fixup: update manual anchor links

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

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 59c1de4ca729e8..2f94dcc3f3501b 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -1581,9 +1581,9 @@ success!
 [`util.TextDecoder`]: util.md#class-utiltextdecoder
 [cjs-module-lexer]: https://github.com/nodejs/cjs-module-lexer/tree/1.2.2
 [custom https loader]: #https-loader
-[load hook]: #loadurl-context-next
+[load hook]: #loadurl-context-nextload
 [percent-encoded]: url.md#percent-encoding-in-urls
-[resolve hook]: #resolvespecifier-context-next
+[resolve hook]: #resolvespecifier-context-nextresolve
 [special scheme]: https://url.spec.whatwg.org/#special-scheme
 [status code]: process.md#exit-codes
 [the official standard format]: https://tc39.github.io/ecma262/#sec-modules

From c81ad323c1e56861163aaf032a8d0fffb320af2a Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:35:45 +0200
Subject: [PATCH 19/24] fixup: tweak ESM doc `resolve` & `load` hooks'
 changelogs

---
 doc/api/esm.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 2f94dcc3f3501b..7564877eaa530a 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -732,9 +732,9 @@ the chain.
 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining resolve hooks. This introduces a
-      breaking change, wherein a hook that does not call `nextResolve()` MUST
-      include a `shortCircuit` flag in its return.
+    description: Add support for chaining resolve hooks. Each hook that does
+      not call `nextResolve()` MUST include a `shortCircuit` property set to
+      `true` in its return.
   - version:
     - v17.1.0
     - v16.14.0
@@ -824,9 +824,9 @@ export async function resolve(specifier, context, nextResolve) {
 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining load hooks. This introduces a
-      breaking change, wherein a hook that does not call `nextLoad()` MUST
-      include a `shortCircuit` flag in its return.
+    description: Add support for chaining load hooks. Each hook that does
+      not call `nextLoad()` MUST include a `shortCircuit` property set to `true`
+      in its return.
 -->
 
 > The loaders API is being redesigned. This hook may disappear or its

From 96acd20f65bb92edda0c73c29b375a8d4568cd08 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 19:44:09 +0200
Subject: [PATCH 20/24] fixup: wordsmith ESM hooks' changelogs

---
 doc/api/esm.md | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 7564877eaa530a..1e519f599eca7b 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -732,9 +732,9 @@ the chain.
 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining resolve hooks. Each hook that does
-      not call `nextResolve()` MUST include a `shortCircuit` property set to
-      `true` in its return.
+    description: Add support for chaining resolve hooks. Each hook must either
+      call `nextResolve()` or include a `shortCircuit` property set to `true`
+      in its return.
   - version:
     - v17.1.0
     - v16.14.0
@@ -824,9 +824,9 @@ export async function resolve(specifier, context, nextResolve) {
 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining load hooks. Each hook that does
-      not call `nextLoad()` MUST include a `shortCircuit` property set to `true`
-      in its return.
+    description: Add support for chaining load hooks.  Each hook must either
+      call `nextLoad()` or include a `shortCircuit` property set to `true` in
+      its return.
 -->
 
 > The loaders API is being redesigned. This hook may disappear or its

From 4169efb3f660a76b150c5b60231096d8f2fc24dd Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 13:48:58 -0400
Subject: [PATCH 21/24] fixup: remove extra whitespace character

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/api/esm.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/esm.md b/doc/api/esm.md
index 1e519f599eca7b..a82ed54b6e19db 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -824,7 +824,7 @@ export async function resolve(specifier, context, nextResolve) {
 changes:
   - version: REPLACEME
     pr-url: https://github.com/nodejs/node/pull/42623
-    description: Add support for chaining load hooks.  Each hook must either
+    description: Add support for chaining load hooks. Each hook must either
       call `nextLoad()` or include a `shortCircuit` property set to `true` in
       its return.
 -->

From 15eecb6284c970b1425e97319fedc2789758c586 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Tue, 3 May 2022 20:21:43 +0200
Subject: [PATCH 22/24] fixup: wordsmith ESM warning for triggering chaining
 exceptions

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

diff --git a/doc/api/esm.md b/doc/api/esm.md
index a82ed54b6e19db..fd128397f4981f 100644
--- a/doc/api/esm.md
+++ b/doc/api/esm.md
@@ -721,10 +721,10 @@ 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.
 
-A hook that fails to return triggers an exception. A hook that returns without
-calling `next<hookName>()` and without returning `shortCircuit: true` also
-triggers an exception. These errors are to help prevent unintentional breaks in
-the chain.
+A hook that returns a value lacking a required property triggers an exception.
+A hook that returns without calling `next<hookName>()` _and_ without returning
+`shortCircuit: true` also triggers an exception. These errors are to help
+prevent unintentional breaks in the chain.
 
 #### `resolve(specifier, context, nextResolve)`
 

From 6dd23ee023b301f98f34d18c4eaac6d291d9ff45 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Wed, 4 May 2022 09:56:35 +0200
Subject: [PATCH 23/24] fixup: optimise resolve's validity check on `url`

---
 lib/internal/modules/esm/loader.js | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/lib/internal/modules/esm/loader.js b/lib/internal/modules/esm/loader.js
index 26f29a043203d0..8bc22ef697db3e 100644
--- a/lib/internal/modules/esm/loader.js
+++ b/lib/internal/modules/esm/loader.js
@@ -525,7 +525,7 @@ class ESMLoader {
     let shortCircuited = false;
 
     const nextLoad = async (nextUrl, ctx = context) => {
-      --hookIndex; // `next` has been called, so decrement our pointer
+      --hookIndex; // `nextLoad` has been called, so decrement our pointer.
 
       ({
         fn: loader,
@@ -773,7 +773,7 @@ class ESMLoader {
     };
 
     const nextResolve = async (suppliedSpecifier, ctx = context) => {
-      --hookIndex; // `nextResolve` has been called, so decrement our pointer
+      --hookIndex; // `nextResolve` has been called, so decrement our pointer.
 
       ({
         fn: resolver,
@@ -848,15 +848,18 @@ class ESMLoader {
       );
     }
 
-    try {
-      new URL(url);
-    } catch {
-      throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
-        'a url string',
-        hookErrIdentifier,
-        'url',
-        url,
-      );
+    // Try to avoid expensive URL instantiation for known-good urls
+    if (!this.moduleMap.has(url)) {
+      try {
+        new URL(url);
+      } catch {
+        throw new ERR_INVALID_RETURN_PROPERTY_VALUE(
+          'a url string',
+          hookErrIdentifier,
+          'url',
+          url,
+        );
+      }
     }
 
     return {

From 38e596b614a1dbc57ec4e8234f9262bf0a956c67 Mon Sep 17 00:00:00 2001
From: Jacob Smith <3012099+JakobJingleheimer@users.noreply.github.com>
Date: Wed, 4 May 2022 09:58:19 +0200
Subject: [PATCH 24/24] =?UTF-8?q?fixup:=20test=20fixture=20`node:`=20?=
 =?UTF-8?q?=E2=86=92=20`import.meta.url`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 test/es-module/test-esm-loader-hooks.mjs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/es-module/test-esm-loader-hooks.mjs b/test/es-module/test-esm-loader-hooks.mjs
index 7e6ea6793e227b..d314a4d9aa0a5e 100644
--- a/test/es-module/test-esm-loader-hooks.mjs
+++ b/test/es-module/test-esm-loader-hooks.mjs
@@ -67,7 +67,7 @@ const { ESMLoader } = esmLoaderModule;
         resolve: mustCall(resolve),
         load: mustCall(load),
       },
-      url: 'node:test/es-module/test-esm-loader-hooks.mjs',
+      url: import.meta.url,
     },
   ];