import-in-the-middle 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [3.3.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.2.0...import-in-the-middle-v3.3.0) (2026-07-02)
+
+
+### Features
+
+* instrument type-stripped TypeScript modules ([#258](https://github.com/nodejs/import-in-the-middle/issues/258)) ([3c6b456](https://github.com/nodejs/import-in-the-middle/commit/3c6b4568a3d23028576ffb728e908a4d06e48523))
+
+
+### Bug Fixes
+
+* guard against circular export-star recursion ([#261](https://github.com/nodejs/import-in-the-middle/issues/261)) ([b957de3](https://github.com/nodejs/import-in-the-middle/commit/b957de3667292ec2ea3b8729704664d1324eaa8f))
+* keep get-esm-exports synchronous so require() works ([#266](https://github.com/nodejs/import-in-the-middle/issues/266)) ([4244b25](https://github.com/nodejs/import-in-the-middle/commit/4244b2512f6256af0ff916f6dc98cc65d988187a))
+* resolve re-exported values from their defining module ([#263](https://github.com/nodejs/import-in-the-middle/issues/263)) ([5ef34cb](https://github.com/nodejs/import-in-the-middle/commit/5ef34cbb59fb65cd0e25b27e06236d6c95c69176))
+
+
+### Performance Improvements
+
+* replace acorn with es-module-lexer for ESM parsing ([#259](https://github.com/nodejs/import-in-the-middle/issues/259)) ([b8cc8af](https://github.com/nodejs/import-in-the-middle/commit/b8cc8af150f46d09b1f447e01a89344d2e647c2c))
+* shrink generated wrapper source ([#264](https://github.com/nodejs/import-in-the-middle/issues/264)) ([491d968](https://github.com/nodejs/import-in-the-middle/commit/491d968d5e80cf0f0add2caeb0f447106caf32c3))
+
+## [3.2.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.1.0...import-in-the-middle-v3.2.0) (2026-06-22)
+
+
+### Features
+
+* add shouldInclude predicate for consumer-owned module matching ([#255](https://github.com/nodejs/import-in-the-middle/issues/255)) ([b2590d0](https://github.com/nodejs/import-in-the-middle/commit/b2590d054a5cfc6d6820c06edb4ff4987a10b5c4))
+
 ## [3.1.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.0.2...import-in-the-middle-v3.1.0) (2026-06-17)
 
 

package/README.md

@@ -117,13 +117,32 @@ node --import=./instrument.mjs ./my-app.mjs
 
 ## Synchronous loader hooks
 
-On Node.js versions that provide
+On Node.js versions that support
 [`module.registerHooks()`](https://nodejs.org/api/module.html#moduleregisterhooksoptions)
-(>= 22.15.0 / >= 24.0.0) the loader can run *synchronously*, on the application
-thread, instead of on the separate thread that `module.register()` uses. Running
-in-thread removes the message channel: `Hook()` registrations are visible to the
-loader directly, so the `createAddHookMessageChannel` /
-`waitForAllMessagesAcknowledged` step shown above is unnecessary.
+the loader can run *synchronously*, on the application thread, instead of on the
+separate thread that `module.register()` uses. Running in-thread removes the
+message channel: `Hook()` registrations are visible to the loader directly, so
+the `createAddHookMessageChannel` / `waitForAllMessagesAcknowledged` step shown
+above is unnecessary.
+
+`module.registerHooks()` was added in 22.15.0 / 24.0.0, but its synchronous load
+hook rejected the nullish CommonJS `source` the loader returns for `require()`s
+pulled into the ESM graph until [nodejs/node#59929][]. The fix shipped in
+**22.22.3, 24.11.1, 25.1.0 and 26.0.0**; earlier versions ship
+`module.registerHooks()` but cannot run the synchronous loader. Use
+`supportsSyncHooks()` to branch on this rather than a hand-written version check:
+
+```js
+import { register, supportsSyncHooks } from 'import-in-the-middle/register-hooks.mjs'
+
+if (supportsSyncHooks()) {
+  register({ include: ['package-i-want-to-include'] })
+} else {
+  // Fall back to the asynchronous loader, e.g. module.register('import-in-the-middle/hook.mjs').
+}
+```
+
+[nodejs/node#59929]: https://github.com/nodejs/node/pull/59929
 
 `instrument.mjs`
 
@@ -143,7 +162,65 @@ node --import=./instrument.mjs ./my-app.mjs
 ```
 
 `register()` accepts the same `include` / `exclude` options as the asynchronous
-loader and throws on a Node.js version without `module.registerHooks()`.
+loader and throws on a Node.js version where `supportsSyncHooks()` is `false`.
+
+### Custom matching with `shouldInclude`
+
+Instead of `include` / `exclude` lists, you can pass a `shouldInclude(url, specifier)`
+predicate to decide which modules are intercepted. It is called for every resolved
+module with the resolved URL and the import specifier; return a truthy value to
+intercept the module. When a predicate is provided it takes over the decision and
+the `include` / `exclude` options are ignored.
+
+This is useful when matching doesn't map cleanly onto bare specifiers, file URLs and
+regular expressions — for example a matcher built from your own configuration, or a
+decision that depends on more than the specifier.
+
+```js
+import { register } from 'import-in-the-middle/register-hooks.mjs'
+
+register({
+  shouldInclude (url, specifier) {
+    return specifier === 'package-i-want-to-include' ||
+      url.includes('/node_modules/some-scope/')
+  }
+})
+```
+
+The predicate receives only the URL and the specifier, never a resolved file path.
+Because `module.register()` transfers its `data` to the loader thread by structured
+clone — which cannot carry a function — `shouldInclude` is supported for synchronous
+registration (`register-hooks.mjs`, shown above) and for predicates constructed on
+the loader thread; it is not accepted through the `data` option of the asynchronous
+`module.register('import-in-the-middle/hook.mjs', ...)`.
+
+## TypeScript modules
+
+On Node.js versions that strip TypeScript types natively (those exposing
+[`module.stripTypeScriptTypes()`](https://nodejs.org/api/module.html#modulestriptypescripttypescode-options),
+>= 22.13.0 / >= 23.9.0 / >= 24.0.0), `import-in-the-middle` intercepts `.ts`,
+`.mts` and `.cts` modules just like their JavaScript counterparts. The types are
+stripped before the module's exports are read, so type-only exports
+(`export type`, `export interface`) are not present on the intercepted
+namespace; value exports are.
+
+```ts
+// math.mts
+export type Op = '+' | '-'
+export function add (a: number, b: number): number {
+  return a + b
+}
+```
+
+```js
+Hook(['./math.mts'], (exported) => {
+  // `exported.add` is interceptable; the `Op` type is not part of the namespace
+})
+```
+
+On Node.js versions where type stripping is not enabled by default, run with
+`--experimental-strip-types`. Older versions that predate
+`module.stripTypeScriptTypes()` leave TypeScript modules untouched.
 
 ## Limitations
 

package/create-hook.mjs

@@ -10,43 +10,33 @@ import {
   hasModuleExportsCJSDefault
 } from './lib/get-exports.mjs'
 import { RESOLVE, driveSync, driveAsync } from './lib/io.mjs'
+import { supportsSyncHooks } from './supports-sync-hooks.mjs'
+
+// Re-exported for backwards compatibility: `supportsSyncHooks` now lives in its
+// own import-free module so a CommonJS preloader can check it without loading
+// this file's acorn / cjs-module-lexer dependency graph.
+export { supportsSyncHooks }
 
 const specifiers = new Map()
 const isWin = process.platform === 'win32'
 
+// Depth at which `processModule` starts tracking visited URLs to break an
+// `export *` cycle. Real re-export chains are only a few levels deep, so this
+// is far beyond any legitimate graph yet well below the call-stack limit a
+// cycle would otherwise hit. Below it the recursion pays only an integer
+// compare per level and allocates no set.
+const STAR_CYCLE_DEPTH = 100
+
 // FIXME: Typescript extensions are added temporarily until we find a better
 // way of supporting arbitrary extensions
 const EXTENSION_RE = /\.(js|mjs|cjs|ts|mts|cts)$/
-const HANDLED_FORMATS = new Set(['builtin', 'module', 'commonjs'])
+// The `-typescript` formats are listed unconditionally; getExports strips the
+// types when the runtime supports it and otherwise falls back to onWrapFailure.
+const HANDLED_FORMATS = new Set([
+  'builtin', 'module', 'commonjs', 'module-typescript', 'commonjs-typescript'
+])
 const TRACE_WARNINGS = process.execArgv.includes('--trace-warnings')
 
-// process.versions.node is always "major.minor.patch" (nightlies add a suffix
-// the regex ignores).
-const [, NODE_MAJOR, NODE_MINOR, NODE_PATCH] =
-  process.versions.node.match(/^(\d+)\.(\d+)\.(\d+)/).map(Number)
-
-/**
- * Whether the running Node.js can correctly run the synchronous loader via
- * `module.registerHooks`.
- *
- * `module.registerHooks` exists since v22.15, but its synchronous load hook
- * rejected the nullish CommonJS `source` the loader returns for `require()`s
- * pulled into the ESM graph (throwing `ERR_INVALID_RETURN_PROPERTY_VALUE`) until
- * https://github.com/nodejs/node/pull/59929, released in 22.22.3, 24.11.1,
- * 25.1.0 and 26.0.0. Earlier 24.x (<= 24.11.0) and 25.0.0 ship `registerHooks`
- * but predate the fix, so the synchronous loader must fall back to the
- * asynchronous one there.
- *
- * @returns {boolean}
- */
-export function supportsSyncHooks () {
-  if (NODE_MAJOR >= 26) return true
-  if (NODE_MAJOR === 25) return NODE_MINOR >= 1
-  if (NODE_MAJOR === 24) return NODE_MINOR > 11 || (NODE_MINOR === 11 && NODE_PATCH >= 1)
-  if (NODE_MAJOR === 22) return NODE_MINOR > 22 || (NODE_MINOR === 22 && NODE_PATCH >= 3)
-  return false
-}
-
 function hasIitm (url) {
   // Fast path: avoid URL parsing on the hot path when there's clearly no iitm.
   if (typeof url !== 'string' || url.indexOf('iitm') === -1) {
@@ -205,52 +195,37 @@ function emitWarning (err) {
  * of how the loader is driven, so both the synchronous and asynchronous paths
  * share it.
  *
+ * The value is read from `namespaceVar`, the wrapper's namespace binding for the
+ * module that *defines* the export. For a module's own exports that is the
+ * wrapped module itself; for a name re-exported through `export *` it is the
+ * leaf that declares it. Reading from the defining module rather than the
+ * aggregating one keeps the value resolvable when the same binding reaches the
+ * aggregator through more than one re-export chain — Node sees those chains as
+ * distinct wrapper modules and leaves the name ambiguous (hence `undefined`) on
+ * the aggregate namespace, while the defining module always holds it (#171).
+ *
  * @param {string} n The exported name.
  * @param {string} srcUrl The URL of the module the export belongs to.
+ * @param {string} namespaceVar The wrapper binding holding `srcUrl`'s namespace.
  * @returns {string}
  */
-function buildSetter (n, srcUrl) {
+function buildSetter (n, srcUrl, namespaceVar) {
   const variableName = `$${n.replace(/[^a-zA-Z0-9_$]/g, '_')}`
   const objectKey = JSON.stringify(n)
   const reExportedName = n === 'default' ? n : objectKey
 
-  // For the module.exports synthetic export (Node 23+), fall back to $default
-  // when namespace['module.exports'] is not exposed by the native ESM namespace
-  // (builtins don't expose it). This ensures the IITM hook proxy returns the
-  // actual CJS value (e.g. EventEmitter) when an instrumentor reads
-  // capturedExports['module.exports'], rather than undefined.
-  const moduleExportsFallback = n === 'module.exports' ? ' ?? $default' : ''
+  // `1` makes __bind fall back to namespace['default'] for the module.exports
+  // synthetic export, which builtins don't expose on the native ESM namespace.
+  const fallback = n === 'module.exports' ? ', 1' : ''
 
+  // Builtins don't expose the module.exports synthetic name, so skip its re-export.
   const reExportLine = (n === 'module.exports' && (srcUrl.startsWith('node:') || builtinModules.includes(srcUrl)))
     ? ''
     : `export { ${variableName} as ${reExportedName} }`
 
-  return `
-      let ${variableName}
-      __overridden[${objectKey}] = false
-      let ${variableName}Defer = false
-      try {
-        ${variableName} = _[${objectKey}] = namespace[${objectKey}]${moduleExportsFallback}
-      } catch (err) {
-        if (!(err instanceof ReferenceError)) throw err
-        ${variableName}Defer = true
-      }
-
-      if (${variableName}Defer || ${variableName} === undefined) {
-        __pending.push(__makeUpdater(
-          ${objectKey},
-          () => namespace[${objectKey}]${moduleExportsFallback},
-          (v) => { ${variableName} = _[${objectKey}] = v }
-        ))
-      }
-      ${reExportLine}
-      set[${objectKey}] = (v) => {
-        __overridden[${objectKey}] = true
-        ${variableName} = v
-        return true
-      }
-      get[${objectKey}] = () => ${variableName}
-      `
+  return `let ${variableName}
+__bind(${objectKey}, ${namespaceVar}, v => { ${variableName} = v }, () => ${variableName}${fallback})
+${reExportLine}`
 }
 
 /**
@@ -267,37 +242,82 @@ function buildSetter (n, srcUrl) {
  * @param {string} params.srcUrl The full URL to the module to process.
  * @param {object} params.context Provided by the loaders API.
  * @param {boolean} [params.excludeDefault = false] Exclude the default export.
+ * @param {number} [params.depth = 0] Star-re-export recursion depth. Used to
+ * detect `export *` cycles (`a` re-exports `b`, `b` re-exports `a`) cheaply:
+ * the acyclic common case pays only an integer compare per level, and the
+ * cycle-tracking set is allocated only once recursion is implausibly deep.
+ * @param {Set<string>} [params.seen] URLs currently on the recursion stack,
+ * created lazily once `depth` crosses {@link STAR_CYCLE_DEPTH}. A URL is added
+ * before descending into its subtree and removed once that subtree finishes, so
+ * it tracks the active path rather than every URL ever visited.
+ * @param {Map<string, string>} [params.originNamespaces] Shared registry mapping
+ * a defining-module URL to the wrapper namespace alias a same-origin `export *`
+ * collision must read it from. Absent until the first such collision; then
+ * threaded through the recursion so one defining module yields one alias and
+ * {@link buildWrapperSource} imports each once. Only `*`-collided names use it;
+ * every other export reads from the wrapped module's own `namespace`.
  *
- * @returns {Generator<Array, Map<string, string>>} A generator that yields I/O
- * operations and ultimately returns the shimmed setters for all the exports
- * from the module and any transitive export all modules.
+ * @returns {Generator<Array, { setters: Map<string, string>, origins: (Map<string, string> | undefined), originNamespaces: (Map<string, string> | undefined) }>}
+ * A generator that yields I/O operations and ultimately returns the shimmed
+ * setters for all the exports from the module and any transitive export all
+ * modules. `origins` (the defining module per `*`-sourced name) is `undefined`
+ * for a module with no `export *`; `originNamespaces` stays `undefined` unless a
+ * same-origin `*` collision actually needed an alias.
  */
-function * processModule ({ srcUrl, context, excludeDefault = false }) {
+function * processModule ({ srcUrl, context, excludeDefault = false, depth = 0, seen, originNamespaces }) {
   const exportNames = yield * getExports(srcUrl, context)
-  const starExports = new Set()
   const setters = new Map()
 
-  const addSetter = (name, setter, isStarExport = false) => {
+  // Maps each live `*`-sourced name to the module that defined it. Its keys
+  // double as "this name came from a `*` re-export" (so an explicit export can
+  // override it), and its values let two `*` re-exports of the same name be told
+  // apart. Allocated on the first `export *`, never for a module without one; a
+  // single Map carries both facts so a star with no collision pays one structure
+  // and one write per name, not two.
+  let starOrigins
+
+  // A name pulled in through more than one `export *` chain that all bottom out
+  // at the same module stays exported (ECMAScript ResolveExport;
+  // tc39/ecma262#3715), but the *aggregate* namespace this wrapper imports drops
+  // it: under iitm the chains are distinct wrapped modules, so Node sees the
+  // re-export as ambiguous and the name reads back undefined. Only those names
+  // must instead read from their defining module's own namespace, which always
+  // holds the value. `originNamespaces` maps such a defining module to the alias
+  // the wrapper imports for it; it is allocated on the first surviving
+  // collision, so a module without one emits no extra import (#171).
+  const ensureOriginNamespace = (origin) => {
+    originNamespaces ??= new Map()
+    let alias = originNamespaces.get(origin)
+    if (alias === undefined) {
+      alias = `__ns${originNamespaces.size}`
+      originNamespaces.set(origin, alias)
+    }
+    return alias
+  }
+
+  const addSetter = (name, setter, isStarExport, origin) => {
     if (setters.has(name)) {
       if (isStarExport) {
-        // If there's already a matching star export, delete it
-        if (starExports.has(name)) {
-          setters.delete(name)
+        // `starOrigins.has(name)` means the existing entry also came from a `*`
+        // re-export (an explicit export would not be tracked here).
+        if (starOrigins.has(name)) {
+          if (starOrigins.get(name) === origin) {
+            // The same binding reached through two `*` re-export chains. It
+            // stays exported, but the aggregate namespace dropped it, so point
+            // its setter at the defining module's namespace instead.
+            setters.set(name, buildSetter(name, origin, ensureOriginNamespace(origin)))
+          } else {
+            // Genuinely ambiguous: two `*` re-exports name it from different
+            // modules. Per ResolveExport the name is excluded entirely.
+            setters.delete(name)
+            starOrigins.delete(name)
+          }
         }
-        // and return so this is excluded
-        return
-      }
-
-      // if we already have this export but it is from a * export, overwrite it
-      if (starExports.has(name)) {
-        starExports.delete(name)
-        setters.set(name, setter)
+        // An explicit export already shadows the `*` re-export; leave it.
       }
     } else {
-      // Store export * exports so we know they can be overridden by explicit
-      // named exports
       if (isStarExport) {
-        starExports.add(name)
+        starOrigins.set(name, origin)
       }
 
       setters.set(name, setter)
@@ -326,21 +346,56 @@ function * processModule ({ srcUrl, context, excludeDefault = false }) {
       // parent's `format` to know if this sub-module is ESM or CJS!
       const result = yield [RESOLVE, newSpecifier, { parentURL: srcUrl }]
 
-      const subSetters = yield * processModule({
-        srcUrl: result.url,
-        context: { ...context, format: result.format },
-        excludeDefault: true
-      })
+      // First `*` re-export: allocate the origin bookkeeping lazily.
+      starOrigins ??= new Map()
+
+      // `export *` graphs are normally only a handful of levels deep. A cycle
+      // (`a` re-exports `b`, `b` re-exports `a`) instead recurses without bound
+      // and exhausts memory. Rather than track every URL on the common shallow
+      // path, only start recording once the depth is implausibly large for a
+      // real graph; from there a re-export pointing back at a module already on
+      // the recursion stack is the cycle, and is skipped (its exports are
+      // collected by the in-progress ancestor frame). `seen` mirrors the stack,
+      // not every URL visited: a module reached and fully processed through one
+      // sibling branch must stay reachable through a later, more direct branch,
+      // so it is removed again once its subtree finishes.
+      if (depth >= STAR_CYCLE_DEPTH) {
+        seen ??= new Set()
+        if (seen.has(result.url)) continue
+        seen.add(result.url)
+      }
 
-      for (const [name, setter] of subSetters.entries()) {
-        addSetter(name, setter, true)
+      try {
+        const sub = yield * processModule({
+          srcUrl: result.url,
+          context: { ...context, format: result.format },
+          excludeDefault: true,
+          depth: depth + 1,
+          seen,
+          originNamespaces
+        })
+
+        // Adopt any registry a nested `export *` minted before processing this
+        // child's results, so a collision detected here extends the same Map the
+        // child's setters already reference (one alias per defining module across
+        // the whole tree) rather than orphaning the child's into a second Map.
+        originNamespaces ??= sub.originNamespaces
+
+        // Star targets build their setters against `namespace` like any other
+        // module; only a surviving same-origin collision (in addSetter) rewrites
+        // the affected name to read from its defining module's alias.
+        for (const [name, setter] of sub.setters) {
+          addSetter(name, setter, true, sub.origins?.get(name) ?? result.url)
+        }
+      } finally {
+        seen?.delete(result.url)
       }
     } else {
-      addSetter(n, buildSetter(n, srcUrl))
+      addSetter(n, buildSetter(n, srcUrl, 'namespace'), false)
     }
   }
 
-  return setters
+  return { setters, origins: starOrigins, originNamespaces }
 }
 
 function addIitm (url) {
@@ -353,6 +408,7 @@ export function createHook (meta) {
   let cachedResolve
   const iitmURL = new URL('lib/register.js', meta.url).toString()
   let includeModules, excludeModules
+  let shouldInclude = defaultShouldInclude
 
   // Track CJS module URLs that IITM has wrapped. On Node 24+, CJS modules loaded
   // via loadCJSModule (in an ESM import chain) have their require() calls for
@@ -362,6 +418,43 @@ export function createHook (meta) {
   // patterns like `class App extends require('events') {}`.
   const cjsInIitmChain = new Set()
 
+  // Default matcher, used unless the consumer supplies its own `shouldInclude`
+  // (see applyOptions). It applies the include/exclude lists, so finishResolve
+  // always has a predicate to call and never has to special-case its absence.
+  //
+  // We check the specifier to match libraries loaded with bare specifiers from
+  // node_modules, and the full file URL for non-bare specifier imports (relative
+  // paths would be error prone). An absolute path entry added via Hook over the
+  // message port matches the resolved file path, so it is resolved here.
+  function defaultShouldInclude (url, specifier) {
+    let resultPath
+    if (url.startsWith('file:')) {
+      const stackTraceLimit = Error.stackTraceLimit
+      Error.stackTraceLimit = 0
+      try {
+        resultPath = fileURLToPath(url)
+      } catch {}
+      Error.stackTraceLimit = stackTraceLimit
+    }
+    function match (each) {
+      if (each instanceof RegExp) {
+        return each.test(url)
+      }
+
+      return each === specifier || each === url || (resultPath && each === resultPath)
+    }
+
+    if (includeModules && !includeModules.some(match)) {
+      return false
+    }
+
+    if (excludeModules && excludeModules.some(match)) {
+      return false
+    }
+
+    return true
+  }
+
   // Applies the include/exclude/message-port configuration. Shared by the
   // asynchronous `initialize` (off-thread `module.register`, which receives
   // `data` over the registration boundary) and by synchronous registration
@@ -371,6 +464,13 @@ export function createHook (meta) {
     includeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.include, 'include')
     excludeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.exclude, 'exclude')
 
+    // A consumer can supply its own matcher as `shouldInclude(url, specifier)`,
+    // taking ownership of the include/exclude decision instead of expressing it
+    // as bare-specifier / file-URL / regex lists. It replaces the default list
+    // matcher and is called with the resolved URL and specifier; otherwise the
+    // default applies the include/exclude options.
+    shouldInclude = typeof data.shouldInclude === 'function' ? data.shouldInclude : defaultShouldInclude
+
     if (data.addHookMessagePort) {
       data.addHookMessagePort.on('message', (modules) => {
         if (includeModules === undefined) {
@@ -417,6 +517,12 @@ export function createHook (meta) {
       return result
     }
 
+    // Never wrap a module whose format we don't handle (e.g. json, wasm); this
+    // holds regardless of how inclusion is decided below.
+    if (result.format && !HANDLED_FORMATS.has(result.format)) {
+      return result
+    }
+
     // The synchronous hooks (`module.registerHooks`) fire for `require()` as well
     // as `import`, but iitm only owns the ESM graph: CommonJS modules are
     // instrumented separately through require-in-the-middle, and `require()` must
@@ -430,37 +536,9 @@ export function createHook (meta) {
       return result
     }
 
-    // For included/excluded modules, we check the specifier to match libraries
-    // that are loaded with bare specifiers from node_modules.
-    //
-    // For non-bare specifier imports, we match to the full file URL because
-    // using relative paths would be very error prone!
-    let resultPath
-    if (result.url.startsWith('file:')) {
-      const stackTraceLimit = Error.stackTraceLimit
-      Error.stackTraceLimit = 0
-      try {
-        resultPath = fileURLToPath(result.url)
-      } catch {}
-      Error.stackTraceLimit = stackTraceLimit
-    }
-    function match (each) {
-      if (each instanceof RegExp) {
-        return each.test(result.url)
-      }
-
-      return each === specifier || each === result.url || (resultPath && each === resultPath)
-    }
-
-    if (result.format && !HANDLED_FORMATS.has(result.format)) {
-      return result
-    }
-
-    if (includeModules && !includeModules.some(match)) {
-      return result
-    }
-
-    if (excludeModules && excludeModules.some(match)) {
+    // `shouldInclude` is always set (the include/exclude list matcher by default,
+    // a consumer-provided predicate otherwise), so no nullish check is needed.
+    if (!shouldInclude(result.url, specifier)) {
       return result
     }
 
@@ -559,11 +637,23 @@ export function createHook (meta) {
   // Builds the wrapper module source that re-exports the real module through
   // iitm's proxy. Pure string generation shared by the asynchronous and
   // synchronous `load` paths.
-  function buildWrapperSource (realUrl, setters, originalSpecifier) {
+  function buildWrapperSource (realUrl, setters, originalSpecifier, originNamespaces) {
+    // The wrapped module imports its namespace as `namespace`, which serves
+    // every export but the ones a same-origin `export *` collision forced onto
+    // their defining module (#171): the aggregate namespace drops those as
+    // ambiguous under iitm, so each such defining module gets its own alias the
+    // wrapper imports. Absent the registry (no such collision) nothing is added.
+    let originImports = ''
+    if (originNamespaces !== undefined) {
+      for (const [originUrl, alias] of originNamespaces) {
+        originImports += `import * as ${alias} from ${JSON.stringify(originUrl)}\n`
+      }
+    }
+
     return `
 import { register } from '${iitmURL}'
 import * as namespace from ${JSON.stringify(realUrl)}
-
+${originImports}
 // Mimic a Module object (https://tc39.es/ecma262/#sec-module-namespace-objects).
 const _ = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } })
 const set = {}
@@ -598,6 +688,31 @@ function __flushPendingOnce () {
   __pending = next
 }
 
+function __bind (key, source, write, read, useFallback) {
+  const readSource = useFallback
+    ? () => source[key] ?? source['default']
+    : () => source[key]
+  __overridden[key] = false
+  let deferred = false
+  try {
+    const v = readSource()
+    write(v)
+    _[key] = v
+  } catch (err) {
+    if (!(err instanceof ReferenceError)) throw err
+    deferred = true
+  }
+  if (deferred || read() === undefined) {
+    __pending.push(__makeUpdater(key, readSource, (v) => { write(v); _[key] = v }))
+  }
+  set[key] = (v) => {
+    __overridden[key] = true
+    write(v)
+    return true
+  }
+  get[key] = read
+}
+
 ${Array.from(setters.values()).join('\n')}
 
 if (__pending.length > 0) {
@@ -635,13 +750,13 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
   // succeeds: free the specifier entry early, and remember CJS modules so their
   // transitive require() chain bypasses iitm (see `load`). Returns the wrapper
   // module source.
-  function onWrapSuccess (realUrl, context, originalSpecifier, setters) {
+  function onWrapSuccess (realUrl, context, originalSpecifier, setters, originNamespaces) {
     specifiers.delete(realUrl)
     // context.format is set to 'commonjs' by getCjsExports during processModule.
     if (context.format === 'commonjs') {
       cjsInIitmChain.add(realUrl)
     }
-    return buildWrapperSource(realUrl, setters, originalSpecifier)
+    return buildWrapperSource(realUrl, setters, originalSpecifier, originNamespaces)
   }
 
   // Bookkeeping shared by the async and sync wrap paths when `processModule`
@@ -662,11 +777,11 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
       const originalSpecifier = specifiers.get(realUrl)
 
       try {
-        const setters = await driveAsync(
+        const { setters, originNamespaces } = await driveAsync(
           processModule({ srcUrl: realUrl, context }),
           { resolve: cachedResolve, load: parentGetSource }
         )
-        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters) }
+        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters, originNamespaces) }
       } catch (cause) {
         onWrapFailure(realUrl, cause)
         // Revert back to the non-iitm URL
@@ -686,11 +801,11 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
       const originalSpecifier = specifiers.get(realUrl)
 
       try {
-        const setters = driveSync(
+        const { setters, originNamespaces } = driveSync(
           processModule({ srcUrl: realUrl, context }),
           { resolve: cachedResolve, load: nextLoad }
         )
-        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters) }
+        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters, originNamespaces) }
       } catch (cause) {
         onWrapFailure(realUrl, cause)
         url = realUrl

package/lib/get-esm-exports.mjs

@@ -1,116 +1,146 @@
 'use strict'
 
-import { Parser } from 'acorn'
-import { importAttributesOrAssertions } from 'acorn-import-attributes'
+import { readFileSync } from 'fs'
+import { createRequire, Module } from 'module'
+import { initSync, parse as parseWasm } from 'es-module-lexer'
 
-const acornOpts = {
-  ecmaVersion: 'latest',
-  sourceType: 'module'
-}
+const require = createRequire(import.meta.url)
+
+// The default es-module-lexer build is WebAssembly backed and decodes string
+// literals (import specifiers, quoted export names) with an internal `eval`.
+// Under `--disallow-code-generation-from-strings` that `eval` silently no-ops,
+// so specifiers and quoted names come back undecoded (`* from undefined`,
+// `"string name"` with the quotes still attached). The eval-free asm.js build
+// (`es-module-lexer/js`) does the same work, so fall back to it when code
+// generation from strings is disallowed. Resolve the parser once at load time
+// so the per-module path stays a bare `parse(source)` call.
+const flag = '--disallow-code-generation-from-strings'
+const disallowCodegen = process.execArgv.includes(flag) ||
+  (process.env.NODE_OPTIONS?.includes(flag) ?? false)
 
-const parser = Parser.extend(importAttributesOrAssertions)
+// initSync compiles the Wasm module up front so `parse` can run inside
+// synchronous loader hooks (`module.registerHooks`) as well as the off-thread
+// loader; it is a one-time cost on the first ESM module either way. It stays the
+// default and remains callable even under the flag, so a parse before the asm.js
+// swap still works (with the flag's known specifier-decoding limitation) rather
+// than throwing.
+initSync()
 
-function warn (txt) {
-  process.emitWarning(txt, 'get-esm-exports')
+let parse = parseWasm
+
+if (disallowCodegen) {
+  parse = loadAsmParse()
 }
 
 /**
- * Utilizes an AST parser to interpret ESM source code and build a list of
- * exported identifiers. In the baseline case, the list of identifiers will be
- * the simple identifier names as written in the source code of the module.
- * However, there is a special case:
+ * Loads the eval-free asm.js parser synchronously, on every Node version.
  *
- * When an `export * from './foo.js'` line is encountered it is rewritten
- * as `* from ./foo.js`. This allows the interpreting code to recognize a
- * transitive export and recursively parse the indicated module. The returned
- * identifier list will have "* from ./foo.js" as an item.
+ * The asm.js build (`es-module-lexer/js`) is ESM-only with no CommonJS variant,
+ * and its only export is a top-level `parse` (no async wasm `init` to await).
+ * `require`-ing it is not portable: before require(esm) (Node < 20.19 / < 22.12)
+ * it throws `ERR_REQUIRE_ESM`, and `import()`-ing it from inside a loader hook
+ * deadlocks the loader on itself. Compiling the source as CommonJS sidesteps
+ * both: it runs synchronously, keeps this module require()-able for the
+ * synchronous `module.registerHooks` path, and never re-enters the ESM loader.
  *
- * @param {object} params
- * @param {string} params.moduleSource The source code of the module to parse
- * and interpret.
+ * `Module._compile` uses V8's script compiler, not `eval`, so it is unaffected
+ * by `--disallow-code-generation-from-strings` — the same reason the asm.js
+ * build itself decodes specifiers under the flag. The only export is rewritten
+ * to a CommonJS one; the source is a vendored build we control.
  *
- * @returns {Set<string>} The identifiers exported by the module along with any
- * custom directives.
+ * @returns {typeof parseWasm} The asm.js parse function.
  */
-export default function getEsmExports (moduleSource) {
-  const exportedNames = new Set()
-  const tree = parser.parse(moduleSource, acornOpts)
-  for (const node of tree.body) {
-    if (!node.type.startsWith('Export')) continue
-    switch (node.type) {
-      case 'ExportNamedDeclaration':
-        if (node.declaration) {
-          parseDeclaration(node, exportedNames)
-        } else {
-          parseSpecifiers(node, exportedNames)
-        }
-        break
-
-      case 'ExportDefaultDeclaration': {
-        exportedNames.add('default')
-        break
-      }
+function loadAsmParse () {
+  const asmPath = require.resolve('es-module-lexer/js')
+  const source = readFileSync(asmPath, 'utf8')
+    .replace('export function parse', 'function parse') +
+    '\nmodule.exports = { parse }\n'
+  const mod = new Module(asmPath)
+  mod.filename = asmPath
+  mod._compile(source, asmPath)
+  return mod.exports.parse
+}
 
-      case 'ExportAllDeclaration':
-        if (node.exported) {
-          exportedNames.add(node.exported.name)
-        } else {
-          exportedNames.add(`* from ${node.source.value}`)
-        }
-        break
-      default:
-        warn('unrecognized export type: ' + node.type)
-    }
+/**
+ * Decodes an exported identifier the way the JS engine would. es-module-lexer
+ * leaves Unicode escapes in bare identifier exports (`export const \u0061 = 1`)
+ * as their raw spelling, while the module namespace exposes the cooked name
+ * (`a`). Quoted export names are already decoded by the lexer and start with a
+ * quote in the source, so the cheap quote check keeps them on the fast path;
+ * only a bare identifier carrying a backslash needs cooking. A malformed escape
+ * falls back to the raw name rather than throwing inside the loader.
+ *
+ * @param {string} name The export name as reported by the lexer.
+ * @returns {string} The cooked export name.
+ */
+function decodeExportName (name) {
+  const first = name.charCodeAt(0)
+  if (first === 0x22 /* " */ || first === 0x27 /* ' */ || !name.includes('\\')) {
+    return name
+  }
+  try {
+    return JSON.parse(`"${name}"`)
+  } catch {
+    return name
   }
-  return exportedNames
 }
 
-function parseDeclaration (node, exportedNames) {
-  switch (node.declaration.type) {
-    case 'FunctionDeclaration':
-      exportedNames.add(node.declaration.id.name)
-      break
-    case 'VariableDeclaration':
-      for (const varDecl of node.declaration.declarations) {
-        parseVariableDeclaration(varDecl, exportedNames)
-      }
-      break
-    case 'ClassDeclaration':
-      exportedNames.add(node.declaration.id.name)
-      break
-    default:
-      warn('unknown declaration type: ' + node.delcaration.type)
-  }
+// es-module-lexer reports a bare `export * from <mod>` only as an import with no
+// matching export entry, indistinguishable from `import <mod>` except by the
+// statement text. This matches that text to rewrite it as the transitive
+// `* from <specifier>` marker the interpreting code recognizes. `export * as ns
+// from` binds a real name and is reported as a normal export, so it must not
+// match here. `GAP` allows whitespace and comments between the tokens, the way
+// the parser does (e.g. `export /* c */ * from`).
+const GAP = '(?:\\s|/\\*[^]*?\\*/|//[^\\n]*\\n)*'
+const STAR_REEXPORT = new RegExp(`^export${GAP}\\*${GAP}from`)
+
+/**
+ * Lexes ESM source code with es-module-lexer and builds a list of exported
+ * identifiers. In the baseline case the list is the simple identifier names as
+ * written in the source. There is one special case:
+ *
+ * When an `export * from './foo.js'` line is encountered it is rewritten as
+ * `* from ./foo.js`. This lets the interpreting code recognize a transitive
+ * export and recursively parse the indicated module. The returned identifier
+ * list will have "* from ./foo.js" as an item.
+ *
+ * @param {string} moduleSource The source code of the module to lex.
+ * @returns {Set<string>} The identifiers exported by the module along with any
+ * custom directives.
+ */
+export default function getEsmExports (moduleSource) {
+  return lexEsm(moduleSource).exportNames
 }
 
-function parseVariableDeclaration (node, exportedNames) {
-  switch (node.id.type) {
-    case 'Identifier':
-      exportedNames.add(node.id.name)
-      break
-    case 'ObjectPattern':
-      for (const prop of node.id.properties) {
-        exportedNames.add(prop.value.name)
-      }
-      break
-    case 'ArrayPattern':
-      for (const elem of node.id.elements) {
-        exportedNames.add(elem.name)
-      }
-      break
-    default:
-      warn('unknown variable declaration type: ' + node.id.type)
+/**
+ * Lexes ESM source code once and reports both the exported identifiers and
+ * whether the source uses ESM syntax. Sharing a single `parse` lets the
+ * unknown-format path in `getExports` decide between ESM and CommonJS without a
+ * second pass over the source.
+ *
+ * `hasModuleSyntax` is es-module-lexer's own signal: static `import`/`export`
+ * and `import.meta` set it, while a lone dynamic `import(...)` (valid in CJS)
+ * does not.
+ *
+ * @param {string} moduleSource The source code of the module to lex.
+ * @returns {{ exportNames: Set<string>, hasModuleSyntax: boolean }}
+ */
+export function lexEsm (moduleSource) {
+  const exportNames = new Set()
+  const [imports, exports, , hasModuleSyntax] = parse(moduleSource)
+
+  for (const exported of exports) {
+    exportNames.add(decodeExportName(exported.n))
   }
-}
 
-function parseSpecifiers (node, exportedNames) {
-  for (const specifier of node.specifiers) {
-    if (specifier.exported.type === 'Identifier') {
-      exportedNames.add(specifier.exported.name)
-    } else if (specifier.exported.type === 'Literal') {
-      exportedNames.add(specifier.exported.value)
-    } else {
-      warn('unrecognized specifier type: ' + specifier.exported.type)
+  // Bare `export * from <mod>` re-exports report no export name; reconstruct
+  // the transitive marker from the import statement that carries the specifier.
+  for (const imported of imports) {
+    if (STAR_REEXPORT.test(moduleSource.slice(imported.ss, imported.se))) {
+      exportNames.add(`* from ${imported.n}`)
     }
   }
+
+  return { exportNames, hasModuleSyntax }
 }

package/lib/get-exports.mjs

@@ -1,6 +1,6 @@
 'use strict'
 
-import getEsmExports from './get-esm-exports.mjs'
+import { lexEsm } from './get-esm-exports.mjs'
 import { parse as parseCjs, initSync } from 'cjs-module-lexer'
 import { readFileSync, existsSync } from 'fs'
 import { builtinModules, createRequire } from 'module'
@@ -11,6 +11,11 @@ import { LOAD } from './io.mjs'
 const nodeMajor = Number(process.versions.node.split('.')[0])
 export const hasModuleExportsCJSDefault = nodeMajor >= 23
 
+// Resolve `stripTypeScriptTypes` (Node >= 22.13) via `getBuiltinModule` rather
+// than a static named import (throws on older runtimes) or `require` (re-enters
+// iitm's own loader hooks). `undefined` on runtimes that lack it.
+const stripTypeScriptTypes = process.getBuiltinModule?.('module')?.stripTypeScriptTypes
+
 let parserInitialized = false
 
 // The CJS export scanner is backed by WebAssembly. `initSync` compiles it
@@ -28,127 +33,6 @@ function addDefault (arr) {
   return new Set(['default', ...arr])
 }
 
-function hasEsmSyntax (source) {
-  // Lightweight scan (no full parse) to determine if the *source code*
-  // contains ESM-specific syntax. This is used only when:
-  // - the loader chain didn't tell us a `format`, and
-  // - `getEsmExports()` found no exports.
-  //
-  // Notes:
-  // - We ignore comments and strings to reduce false positives.
-  // - We treat `import.meta` and static `import ...` as ESM.
-  // - We do NOT treat `import(` (dynamic import) as ESM because it is allowed
-  //   in CJS as an expression.
-  if (source.indexOf('import') === -1) return false
-
-  const isIdentCharCode = (code) => (
-    (code >= 48 && code <= 57) || // 0-9
-    (code >= 65 && code <= 90) || // A-Z
-    (code >= 97 && code <= 122) || // a-z
-    code === 95 || // _
-    code === 36 // $
-  )
-
-  const skipWhitespace = (idx) => {
-    while (idx < source.length) {
-      const c = source.charCodeAt(idx)
-      // space, tab, cr, lf
-      if (c !== 32 && c !== 9 && c !== 13 && c !== 10) break
-      idx++
-    }
-    return idx
-  }
-
-  let i = 0
-  while (i < source.length) {
-    const ch = source[i]
-
-    // Line comment
-    if (ch === '/' && source[i + 1] === '/') {
-      i += 2
-      while (i < source.length && source[i] !== '\n') i++
-      continue
-    }
-
-    // Block comment
-    if (ch === '/' && source[i + 1] === '*') {
-      i += 2
-      while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) i++
-      i += 2
-      continue
-    }
-
-    // Strings: '...' or "..."
-    if (ch === '\'' || ch === '"') {
-      const quote = ch
-      i++
-      while (i < source.length) {
-        const c = source[i]
-        if (c === '\\') {
-          i += 2
-          continue
-        }
-        if (c === quote) {
-          i++
-          break
-        }
-        i++
-      }
-      continue
-    }
-
-    // Template strings: `...`
-    if (ch === '`') {
-      i++
-      while (i < source.length) {
-        const c = source[i]
-        if (c === '\\') {
-          i += 2
-          continue
-        }
-        if (c === '`') {
-          i++
-          break
-        }
-        i++
-      }
-      continue
-    }
-
-    // Keyword scan (word-boundary): import
-    if (ch === 'i') {
-      const prev = source.charCodeAt(i - 1)
-      if (i > 0 && isIdentCharCode(prev)) {
-        i++
-        continue
-      }
-
-      if (source.startsWith('import', i)) {
-        const next = source.charCodeAt(i + 6)
-        if (isIdentCharCode(next)) {
-          i++
-          continue
-        }
-
-        const j = skipWhitespace(i + 6)
-        // `import.meta` is ESM-only
-        if (source[j] === '.') return true
-        // `import(` is dynamic import, allowed in CJS
-        if (source[j] === '(') {
-          i = j + 1
-          continue
-        }
-        // Otherwise assume it's a static import form
-        return true
-      }
-    }
-
-    i++
-  }
-
-  return false
-}
-
 // Cached exports for Node built-in modules
 const BUILT_INS = new Map()
 
@@ -362,28 +246,36 @@ export function * getExports (url, context) {
   }
 
   try {
-    if (format === 'module') {
-      return getEsmExports(source)
+    // Node hands the load hook the original TypeScript source, so strip the
+    // types before the JS parsers run, then treat the module as the JS it
+    // compiles to. Early type-stripping releases tag the format but lack the
+    // API; the un-stripped parse then fails cleanly into onWrapFailure.
+    let moduleFormat = format
+    if (format === 'module-typescript' || format === 'commonjs-typescript') {
+      if (stripTypeScriptTypes !== undefined) {
+        source = stripTypeScriptTypes(source, { mode: 'strip' })
+      }
+      moduleFormat = format === 'module-typescript' ? 'module' : 'commonjs'
     }
 
-    if (format === 'commonjs') {
+    if (moduleFormat === 'commonjs') {
       return yield * getCjsExports(url, context, source)
     }
 
-    // At this point our `format` is either undefined or not known by us. Fall
-    // back to parsing as ESM/CJS.
-    const esmExports = getEsmExports(source)
-    if (!esmExports.size) {
-      // If there's strong evidence this is ESM (static import/import.meta),
-      // prefer returning the empty ESM export set over incorrectly treating it
-      // as CJS.
-      if (!hasEsmSyntax(source)) {
-        // It might be possible to get here if the format
-        // isn't set at first and yet we have an ESM module with no exports.
-        return yield * getCjsExports(url, context, source)
-      }
+    const { exportNames, hasModuleSyntax } = lexEsm(source)
+
+    if (moduleFormat === 'module') {
+      return exportNames
+    }
+
+    // At this point our `format` is either undefined or not known by us. When
+    // there are no exports and no ESM syntax, fall back to CommonJS detection.
+    // Strong evidence of ESM (static import/import.meta) keeps the empty ESM
+    // export set rather than incorrectly treating the module as CJS.
+    if (!exportNames.size && !hasModuleSyntax) {
+      return yield * getCjsExports(url, context, source)
     }
-    return esmExports
+    return exportNames
   } catch (cause) {
     const err = new Error(`Failed to parse '${url}'`)
     err.cause = cause

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "import-in-the-middle",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "Intercept imports in Node.js",
   "engines": {
     "node": ">=18"
@@ -59,9 +59,8 @@
     "vue": "^3.5.26"
   },
   "dependencies": {
-    "acorn": "^8.15.0",
-    "acorn-import-attributes": "^1.9.5",
     "cjs-module-lexer": "^2.2.0",
+    "es-module-lexer": "^2.2.0",
     "module-details-from-path": "^1.0.4"
   }
 }

package/register-hooks.d.ts

@@ -17,7 +17,8 @@ export type RegisterHooksOptions = {
  * synchronous hooks run on the application thread, so `Hook()` registrations are
  * visible to the loader directly and no acknowledgement step is required.
  *
- * Requires a Node.js version with `module.registerHooks()` (>= 22.15.0 / >= 24).
+ * Requires a Node.js version where {@link supportsSyncHooks} is `true`
+ * (>= 22.22.3, >= 24.11.1, >= 25.1.0, or >= 26.0.0).
  *
  * ```ts
  * import { register } from 'import-in-the-middle/register-hooks.mjs'
@@ -30,6 +31,14 @@ export type RegisterHooksOptions = {
  * })
  * ```
  *
- * @throws If `module.registerHooks()` is unavailable in the running Node.js.
+ * @throws If {@link supportsSyncHooks} is `false` in the running Node.js.
  */
 export declare function register(options?: RegisterHooksOptions): void
+
+/**
+ * Whether the running Node.js can correctly run the synchronous loader via
+ * `module.registerHooks()`. `false` on versions that ship `module.registerHooks()`
+ * but predate the nullish-CommonJS-`source` fix (nodejs/node#59929); branch on it
+ * to fall back to the asynchronous `module.register()` loader.
+ */
+export declare function supportsSyncHooks(): boolean

package/register-hooks.mjs

@@ -1,5 +1,6 @@
 import * as module from 'module'
-import { createHook, supportsSyncHooks } from './create-hook.mjs'
+import { createHook } from './create-hook.mjs'
+import { supportsSyncHooks } from './supports-sync-hooks.mjs'
 
 export { supportsSyncHooks }
 

package/supports-sync-hooks.mjs

@@ -0,0 +1,47 @@
+// Unless explicitly stated otherwise all files in this repository are licensed under the Apache 2.0 License.
+//
+// This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2021 Datadog, Inc.
+
+// This module intentionally has no imports. `supportsSyncHooks` is a pure
+// Node.js version check, and consumers (e.g. a CommonJS preloader deciding
+// whether to require the ESM loader at all) need to call it without pulling in
+// `create-hook.mjs` and its acorn / cjs-module-lexer dependency graph.
+
+// `process.versions.node` is always "major.minor.patch" (nightlies append a
+// "-suffix" that parseInt stops at). Only release lines 22/24/25 need the minor
+// and patch, so parse the major eagerly and read those lazily.
+const version = process.versions.node
+const NODE_MAJOR = parseInt(version, 10)
+let NODE_MINOR
+let NODE_PATCH
+
+function readMinorAndPatch () {
+  const firstDot = version.indexOf('.')
+  const secondDot = version.indexOf('.', firstDot + 1)
+  NODE_MINOR = parseInt(version.slice(firstDot + 1, secondDot), 10)
+  NODE_PATCH = parseInt(version.slice(secondDot + 1), 10)
+}
+
+/**
+ * Whether the running Node.js can correctly run the synchronous loader via
+ * `module.registerHooks`.
+ *
+ * `module.registerHooks` exists since v22.15, but its synchronous load hook
+ * rejected the nullish CommonJS `source` the loader returns for `require()`s
+ * pulled into the ESM graph (throwing `ERR_INVALID_RETURN_PROPERTY_VALUE`) until
+ * https://github.com/nodejs/node/pull/59929, released in 22.22.3, 24.11.1,
+ * 25.1.0 and 26.0.0. Earlier 24.x (<= 24.11.0) and 25.0.0 ship `registerHooks`
+ * but predate the fix, so the synchronous loader must fall back to the
+ * asynchronous one there.
+ *
+ * @returns {boolean}
+ */
+export function supportsSyncHooks () {
+  if (NODE_MAJOR >= 26) return true
+  if (NODE_MAJOR < 22 || NODE_MAJOR === 23) return false
+
+  readMinorAndPatch()
+  if (NODE_MAJOR === 25) return NODE_MINOR >= 1
+  if (NODE_MAJOR === 24) return NODE_MINOR > 11 || (NODE_MINOR === 11 && NODE_PATCH >= 1)
+  return NODE_MINOR > 22 || (NODE_MINOR === 22 && NODE_PATCH >= 3)
+}