import-in-the-middle 3.0.2 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [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)
+
+
+### Features
+
+* add synchronous loader hooks via module.registerHooks ([#253](https://github.com/nodejs/import-in-the-middle/issues/253)) ([dd7e550](https://github.com/nodejs/import-in-the-middle/commit/dd7e5501f0cb901b8e4979f819e9deda6c84e2fc))
+
 ## [3.0.2](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v3.0.1...import-in-the-middle-v3.0.2) (2026-06-08)
 
 

package/README.md

@@ -115,6 +115,66 @@ fs.readFileSync('file.txt')
 node --import=./instrument.mjs ./my-app.mjs
 ```
 
+## Synchronous loader hooks
+
+On Node.js versions that provide
+[`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.
+
+`instrument.mjs`
+
+```js
+import { register } from 'import-in-the-middle/register-hooks.mjs'
+import { Hook } from 'import-in-the-middle'
+
+register({ include: ['package-i-want-to-include'] })
+
+Hook(['package-i-want-to-include'], (exported, name, baseDir) => {
+  // Instrument the module
+})
+```
+
+```shell
+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()`.
+
+### 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', ...)`.
+
 ## Limitations
 
 * You cannot add new exports to a module. You can only modify existing ones.

package/create-hook.mjs

@@ -6,9 +6,10 @@ import { URL, fileURLToPath } from 'url'
 import { inspect } from 'util'
 import { builtinModules } from 'module'
 import {
-  getExports as getExportsImpl,
+  getExports,
   hasModuleExportsCJSDefault
 } from './lib/get-exports.mjs'
+import { RESOLVE, driveSync, driveAsync } from './lib/io.mjs'
 
 const specifiers = new Map()
 const isWin = process.platform === 'win32'
@@ -16,17 +17,34 @@ const isWin = process.platform === 'win32'
 // 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 NODE_VERSION = process.versions.node.split('.')
-const NODE_MAJOR = Number(NODE_VERSION[0])
-const NODE_MINOR = Number(NODE_VERSION[1])
 const HANDLED_FORMATS = new Set(['builtin', 'module', 'commonjs'])
 const TRACE_WARNINGS = process.execArgv.includes('--trace-warnings')
 
-let getExports
-if (NODE_MAJOR > 16 || (NODE_MAJOR === 16 && NODE_MINOR >= 16)) {
-  getExports = getExportsImpl
-} else {
-  getExports = (url) => import(url).then(Object.keys)
+// 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) {
@@ -181,21 +199,81 @@ function emitWarning (err) {
   process.emitWarning(warnMessage)
 }
 
+/**
+ * Builds the setter/getter/re-export block injected into the wrapper module for
+ * a single named export. This is pure string generation, identical regardless
+ * of how the loader is driven, so both the synchronous and asynchronous paths
+ * share it.
+ *
+ * @param {string} n The exported name.
+ * @param {string} srcUrl The URL of the module the export belongs to.
+ * @returns {string}
+ */
+function buildSetter (n, srcUrl) {
+  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' : ''
+
+  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}
+      `
+}
+
 /**
  * Processes a module's exports and builds a set of setter blocks.
  *
+ * Written as a "sans-io" generator (see `lib/io.mjs`): instead of calling the
+ * loader's resolve/load hooks directly it `yield`s `[RESOLVE, ...]` to resolve
+ * star re-exports and `[LOAD, ...]` (via {@link getExports}) to read source,
+ * and is driven by either {@link driveSync} (for
+ * `module.registerHooks`) or {@link driveAsync} (for `module.register`). The
+ * body is identical for both, so there is a single implementation to maintain.
+ *
  * @param {object} params
  * @param {string} params.srcUrl The full URL to the module to process.
  * @param {object} params.context Provided by the loaders API.
- * @param {Function} params.parentGetSource Provides the source code for the parent module.
- * @param {Function} params.parentResolve Provides the resolve function for the parent module.
  * @param {boolean} [params.excludeDefault = false] Exclude the default export.
  *
- * @returns {Promise<Map<string, string>>} The shimmed setters for all the exports
+ * @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.
  */
-async function processModule ({ srcUrl, context, parentGetSource, parentResolve, excludeDefault = false }) {
-  const exportNames = await getExports(srcUrl, context, parentGetSource)
+function * processModule ({ srcUrl, context, excludeDefault = false }) {
+  const exportNames = yield * getExports(srcUrl, context)
   const starExports = new Set()
   const setters = new Map()
 
@@ -243,17 +321,14 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
 
       // Relative paths need to be resolved relative to the parent module
       const newSpecifier = isBareSpecifier(modFile) ? modFile : new URL(modFile, srcUrl).href
-      // We need to call `parentResolve` to resolve bare specifiers to a full
-      // URL. We also need to call `parentResolve` for all sub-modules to get
-      // the `format`. We can't rely on the parents `format` to know if this
-      // sub-module is ESM or CJS!
-      const result = await parentResolve(newSpecifier, { parentURL: srcUrl })
+      // We need to resolve bare specifiers to a full URL. We also need to
+      // resolve all sub-modules to get the `format`. We can't rely on the
+      // parent's `format` to know if this sub-module is ESM or CJS!
+      const result = yield [RESOLVE, newSpecifier, { parentURL: srcUrl }]
 
-      const subSetters = await processModule({
+      const subSetters = yield * processModule({
         srcUrl: result.url,
         context: { ...context, format: result.format },
-        parentGetSource,
-        parentResolve,
         excludeDefault: true
       })
 
@@ -261,43 +336,7 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
         addSetter(name, setter, true)
       }
     } else {
-      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' : ''
-
-      addSetter(n, `
-      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 }
-        ))
-      }
-      ${(n === 'module.exports' && (srcUrl.startsWith('node:') || builtinModules.includes(srcUrl))) ? '' : `export { ${variableName} as ${reExportedName} }`}
-      set[${objectKey}] = (v) => {
-        __overridden[${objectKey}] = true
-        ${variableName} = v
-        return true
-      }
-      get[${objectKey}] = () => ${variableName}
-      `)
+      addSetter(n, buildSetter(n, srcUrl))
     }
   }
 
@@ -314,6 +353,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
@@ -323,55 +363,95 @@ export function createHook (meta) {
   // patterns like `class App extends require('events') {}`.
   const cjsInIitmChain = new Set()
 
-  async function initialize (data) {
-    if (global.__import_in_the_middle_initialized__) {
-      process.emitWarning("The 'import-in-the-middle' hook has already been initialized")
+  // 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)
+      }
 
-    global.__import_in_the_middle_initialized__ = true
+      return each === specifier || each === url || (resultPath && each === resultPath)
+    }
 
-    if (data) {
-      includeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.include, 'include')
-      excludeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.exclude, 'exclude')
+    if (includeModules && !includeModules.some(match)) {
+      return false
+    }
 
-      if (data.addHookMessagePort) {
-        data.addHookMessagePort.on('message', (modules) => {
-          if (includeModules === undefined) {
-            includeModules = []
-          }
+    if (excludeModules && excludeModules.some(match)) {
+      return false
+    }
 
-          for (const each of modules) {
-            if (!each.startsWith('node:') && builtinModules.includes(each)) {
-              includeModules.push(`node:${each}`)
-            }
+    return true
+  }
 
-            includeModules.push(each)
+  // 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
+  // (`module.registerHooks`), which has no `initialize` step and passes the
+  // same options directly.
+  function applyOptions (data) {
+    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) {
+          includeModules = []
+        }
+
+        for (const each of modules) {
+          if (!each.startsWith('node:') && builtinModules.includes(each)) {
+            includeModules.push(`node:${each}`)
           }
 
-          data.addHookMessagePort.postMessage('ack')
-        }).unref()
-      }
+          includeModules.push(each)
+        }
+
+        data.addHookMessagePort.postMessage('ack')
+      }).unref()
     }
   }
 
-  async function resolve (specifier, context, parentResolve) {
-    cachedResolve = parentResolve
-
-    // See https://github.com/nodejs/import-in-the-middle/pull/76.
-    if (specifier === iitmURL) {
-      return {
-        url: specifier,
-        shortCircuit: true
-      }
+  async function initialize (data) {
+    if (global.__import_in_the_middle_initialized__) {
+      process.emitWarning("The 'import-in-the-middle' hook has already been initialized")
     }
 
-    const { parentURL = '' } = context
-    const newSpecifier = deleteIitm(specifier)
-    if (isWin && parentURL.indexOf('file:node') === 0) {
-      context.parentURL = ''
+    global.__import_in_the_middle_initialized__ = true
+
+    if (data) {
+      applyOptions(data)
     }
-    const result = await parentResolve(newSpecifier, context)
+  }
 
+  // Shared post-processing for the `resolve` hook: everything that happens
+  // once the parent loader has turned the specifier into a resolved URL. The
+  // only difference between the asynchronous and synchronous hooks is whether
+  // that resolution was awaited, so all the wrapping decisions live here.
+  function finishResolve (result, specifier, context, parentURL) {
     // Do not wrap the entrypoint module. Many CLIs check whether they are the
     // "main" module (e.g. require.main === module). Wrapping changes how they
     // are evaluated, and can make them exit without doing anything.
@@ -382,37 +462,28 @@ 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)
-    }
-
+    // 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
     }
 
-    if (includeModules && !includeModules.some(match)) {
+    // 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
+    // return the native, mutable module value (e.g. graceful-fs does
+    // `Object.defineProperty(require('fs'), ...)`, which throws on a frozen ESM
+    // namespace). Node reports the active module system in `context.conditions`
+    // ('require' vs 'import'), so leave any require() resolution untouched. The
+    // asynchronous hook never sees the 'require' condition, so this is a no-op
+    // there and only affects the synchronous path.
+    if (context.conditions?.includes('require')) {
       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
     }
 
@@ -456,31 +527,63 @@ export function createHook (meta) {
     return {
       url: addIitm(result.url),
       shortCircuit: true,
-      format: result.format
+      // Node's synchronous resolver drops `format: 'builtin'` for bare builtin
+      // specifiers (`require('crypto')` -> `node:crypto`), so restore it;
+      // otherwise the load hook reads `node:crypto` from disk and throws ENOENT.
+      format: result.format ?? (result.url.startsWith('node:') ? 'builtin' : undefined)
     }
   }
 
-  async function getSource (url, context, parentGetSource) {
-    if (hasIitm(url)) {
-      const realUrl = deleteIitm(url)
-      const originalSpecifier = specifiers.get(realUrl)
+  async function resolve (specifier, context, parentResolve) {
+    cachedResolve = parentResolve
 
-      try {
-        const setters = await processModule({
-          srcUrl: realUrl,
-          context,
-          parentGetSource,
-          parentResolve: cachedResolve
-        })
-        // If the module loaded successfully, we can remove the specifier to reduce memory usage early.
-        specifiers.delete(realUrl)
-        // Track CJS modules so their transitive require() calls bypass IITM.
-        // context.format is set to 'commonjs' by getCjsExports during processModule.
-        if (context.format === 'commonjs') {
-          cjsInIitmChain.add(realUrl)
-        }
-        return {
-          source: `
+    // See https://github.com/nodejs/import-in-the-middle/pull/76.
+    if (specifier === iitmURL) {
+      return {
+        url: specifier,
+        shortCircuit: true
+      }
+    }
+
+    const { parentURL = '' } = context
+    const newSpecifier = deleteIitm(specifier)
+    if (isWin && parentURL.indexOf('file:node') === 0) {
+      context.parentURL = ''
+    }
+    const result = await parentResolve(newSpecifier, context)
+
+    return finishResolve(result, specifier, context, parentURL)
+  }
+
+  // Synchronous counterpart to `resolve`, for `module.registerHooks`. The
+  // synchronous `nextResolve` returns its result directly. We stash it so the
+  // synchronous `load` hook can resolve star re-exports later, mirroring how
+  // `resolve` caches `parentResolve`.
+  function resolveSync (specifier, context, nextResolve) {
+    cachedResolve = nextResolve
+
+    if (specifier === iitmURL) {
+      return {
+        url: specifier,
+        shortCircuit: true
+      }
+    }
+
+    const { parentURL = '' } = context
+    const newSpecifier = deleteIitm(specifier)
+    if (isWin && parentURL.indexOf('file:node') === 0) {
+      context.parentURL = ''
+    }
+    const result = nextResolve(newSpecifier, context)
+
+    return finishResolve(result, specifier, context, parentURL)
+  }
+
+  // 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) {
+    return `
 import { register } from '${iitmURL}'
 import * as namespace from ${JSON.stringify(realUrl)}
 
@@ -549,26 +652,46 @@ if (__pending.length > 0) {
 
 register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpecifier)})
 `
-        }
-      } catch (cause) {
-        // If the module failed loading, the specifier will not be used again, so
-        // we can remove it to prevent a memory leak.
-        specifiers.delete(realUrl)
-        // If there are other ESM loader hooks registered as well as iitm,
-        // depending on the order they are registered, source might not be
-        // JavaScript.
-        //
-        // If we fail to parse a module for exports, we should fall back to the
-        // parent loader. These modules will not be wrapped with proxies and
-        // cannot be Hook'ed but at least this does not take down the entire app
-        // and block iitm from being used.
-        //
-        // We log the error because there might be bugs in iitm and without this
-        // it would be very tricky to debug
-        const err = new Error(`'import-in-the-middle' failed to wrap '${realUrl}'`)
-        err.cause = cause
-        emitWarning(err)
+  }
+
+  // Bookkeeping shared by the async and sync wrap paths once `processModule`
+  // 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) {
+    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)
+  }
+
+  // Bookkeeping shared by the async and sync wrap paths when `processModule`
+  // throws. iitm falls back to the parent loader so the module loads unwrapped
+  // (it just can't be Hook'ed) rather than taking down the whole app. We free
+  // the specifier entry to avoid a leak, and log because a failure here is
+  // usually an iitm bug and would otherwise be very tricky to debug.
+  function onWrapFailure (realUrl, cause) {
+    specifiers.delete(realUrl)
+    const err = new Error(`'import-in-the-middle' failed to wrap '${realUrl}'`)
+    err.cause = cause
+    emitWarning(err)
+  }
 
+  async function getSource (url, context, parentGetSource) {
+    if (hasIitm(url)) {
+      const realUrl = deleteIitm(url)
+      const originalSpecifier = specifiers.get(realUrl)
+
+      try {
+        const setters = await driveAsync(
+          processModule({ srcUrl: realUrl, context }),
+          { resolve: cachedResolve, load: parentGetSource }
+        )
+        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters) }
+      } catch (cause) {
+        onWrapFailure(realUrl, cause)
         // Revert back to the non-iitm URL
         url = realUrl
       }
@@ -577,6 +700,29 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
     return parentGetSource(url, context)
   }
 
+  // Synchronous counterpart to `getSource`, for `module.registerHooks`. Drives
+  // `processModule` straight through; all bookkeeping and source generation is
+  // shared with `getSource`.
+  function getSourceSync (url, context, nextLoad) {
+    if (hasIitm(url)) {
+      const realUrl = deleteIitm(url)
+      const originalSpecifier = specifiers.get(realUrl)
+
+      try {
+        const setters = driveSync(
+          processModule({ srcUrl: realUrl, context }),
+          { resolve: cachedResolve, load: nextLoad }
+        )
+        return { source: onWrapSuccess(realUrl, context, originalSpecifier, setters) }
+      } catch (cause) {
+        onWrapFailure(realUrl, cause)
+        url = realUrl
+      }
+    }
+
+    return nextLoad(url, context)
+  }
+
   async function load (url, context, parentLoad) {
     if (hasIitm(url)) {
       const result = await getSource(url, context, parentLoad)
@@ -615,5 +761,39 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
     return parentLoad(url, context)
   }
 
-  return { initialize, load, resolve }
+  // Synchronous counterpart to `load`, for `module.registerHooks`. Mirrors the
+  // async `load` exactly — wrapping via `getSourceSync` and applying the same
+  // CJS-in-iitm-chain source stripping — only without awaiting.
+  function loadSync (url, context, nextLoad) {
+    if (hasIitm(url)) {
+      const result = getSourceSync(url, context, nextLoad)
+      // If wrapping failed, `getSourceSync()` may have fallen back to `nextLoad`,
+      // which can legally return `source: null` (e.g. for non-JS formats).
+      if (result && typeof result === 'object' && result.source != null) {
+        return {
+          source: result.source,
+          shortCircuit: true,
+          format: 'module'
+        }
+      }
+
+      // Fall back to the parent loader with the original (non-iitm) URL.
+      return nextLoad(deleteIitm(url), context)
+    }
+
+    if (cjsInIitmChain.has(url)) {
+      const result = nextLoad(url, context)
+      if (result.format === 'commonjs' && result.source != null) {
+        return {
+          format: result.format,
+          source: undefined
+        }
+      }
+      return result
+    }
+
+    return nextLoad(url, context)
+  }
+
+  return { initialize, load, resolve, resolveSync, loadSync, applyOptions }
 }

package/lib/get-exports.mjs

@@ -1,17 +1,29 @@
 'use strict'
 
 import getEsmExports from './get-esm-exports.mjs'
-import { parse as parseCjs, init as parserInit } from 'cjs-module-lexer'
+import { parse as parseCjs, initSync } from 'cjs-module-lexer'
 import { readFileSync, existsSync } from 'fs'
 import { builtinModules, createRequire } from 'module'
 import { fileURLToPath, pathToFileURL } from 'url'
 import { dirname, join } from 'path'
+import { LOAD } from './io.mjs'
 
 const nodeMajor = Number(process.versions.node.split('.')[0])
 export const hasModuleExportsCJSDefault = nodeMajor >= 23
 
 let parserInitialized = false
 
+// The CJS export scanner is backed by WebAssembly. `initSync` compiles it
+// up front so the scanner can run inside synchronous loader hooks
+// (`module.registerHooks`) as well as the off-thread loader; it is a one-time
+// cost on the first CommonJS module either way.
+function ensureParserInitialized () {
+  if (!parserInitialized) {
+    initSync()
+    parserInitialized = true
+  }
+}
+
 function addDefault (arr) {
   return new Set(['default', ...arr])
 }
@@ -142,16 +154,29 @@ const BUILT_INS = new Map()
 
 let require
 
-function getExportsForNodeBuiltIn (name) {
-  let exports = BUILT_INS.get(name)
-
+// Returns a builtin's exports object. `process.getBuiltinModule` (Node >=
+// 20.16 / >= 22.3) bypasses registered loader hooks; `require` does not. Under
+// the in-thread `module.registerHooks` loader a plain `require(name)` here
+// re-enters iitm's own hooks and resolves to the half-built wrapper instead of
+// the native module. The off-thread `module.register` loader runs `require` on
+// the loader thread where the hooks aren't installed, so the fallback stays
+// correct on older Node that lacks getBuiltinModule.
+function loadBuiltin (name) {
+  if (typeof process.getBuiltinModule === 'function') {
+    return process.getBuiltinModule(name)
+  }
   if (!require) {
     require = createRequire(import.meta.url)
   }
+  return require(name)
+}
+
+function getExportsForNodeBuiltIn (name) {
+  let exports = BUILT_INS.get(name)
 
   if (!exports) {
     // get all properties both enumerable and non-enumerable
-    exports = new Set(addDefault(Object.getOwnPropertyNames(require(name))))
+    exports = new Set(addDefault(Object.getOwnPropertyNames(loadBuiltin(name))))
     // added in node 23 as alias for default in cjs modules
     if (hasModuleExportsCJSDefault) {
       exports.add('module.exports')
@@ -220,52 +245,54 @@ function resolvePackageImports (specifier, fromUrl) {
   return null
 }
 
-async function getCjsExports (url, context, parentLoad, source) {
+function * getCjsExports (url, context, source) {
   if (urlsBeingProcessed.has(url)) {
     return new Set()
   }
   urlsBeingProcessed.add(url)
 
   try {
-    if (!parserInitialized) {
-      await parserInit()
-      parserInitialized = true
-    }
+    ensureParserInitialized()
     const result = parseCjs(source)
     const full = addDefault(result.exports)
 
-    await Promise.all(result.reexports.map(async re => {
-      if (re.startsWith('node:') || builtinModules.includes(re)) {
-        for (const each of getExportsForNodeBuiltIn(re)) {
+    for (const reexport of result.reexports) {
+      if (reexport.startsWith('node:') || builtinModules.includes(reexport)) {
+        for (const each of getExportsForNodeBuiltIn(reexport)) {
           full.add(each)
         }
-      } else {
-        if (re === '.') {
-          re = './'
-        }
+        continue
+      }
 
-        // Entries in the import field should always start with #
-        if (re.startsWith('#')) {
-          const resolved = resolvePackageImports(re, url)
-          if (!resolved) return
-          [url, re] = resolved
-        }
+      // Resolve each re-export relative to the current module. Keep the
+      // resolution scoped to this iteration: a `#`-import rewrites both the
+      // base URL and the specifier, and that rewrite must not leak into the
+      // next re-export.
+      let reUrl = url
+      let reSpecifier = reexport === '.' ? './' : reexport
+
+      // Entries in the import field should always start with #
+      if (reSpecifier.startsWith('#')) {
+        const resolved = resolvePackageImports(reSpecifier, url)
+        if (!resolved) continue
+        ;[reUrl, reSpecifier] = resolved
+      }
 
-        // Resolve the re-exported module relative to the current module.
-        if (!require) {
-          require = createRequire(import.meta.url)
-        }
-        const newUrl = pathToFileURL(require.resolve(re, { paths: [dirname(fileURLToPath(url))] })).href
+      if (!require) {
+        require = createRequire(import.meta.url)
+      }
+      const newUrl = pathToFileURL(
+        require.resolve(reSpecifier, { paths: [dirname(fileURLToPath(reUrl))] })
+      ).href
 
-        if (newUrl.endsWith('.node') || newUrl.endsWith('.json')) {
-          return
-        }
+      if (newUrl.endsWith('.node') || newUrl.endsWith('.json')) {
+        continue
+      }
 
-        for (const each of await getExports(newUrl, context, parentLoad)) {
-          full.add(each)
-        }
+      for (const each of yield * getExports(newUrl, context)) {
+        full.add(each)
       }
-    }))
+    }
 
     // added in node 23 as alias for default in cjs modules
     if (full.has('default') && hasModuleExportsCJSDefault) {
@@ -281,26 +308,30 @@ async function getCjsExports (url, context, parentLoad, source) {
 }
 
 /**
- * Inspects a module for its type (commonjs or module), attempts to get the
- * source code for said module from the loader API, and parses the result
- * for the entities exported from that module.
+ * Inspects a module for its type (commonjs or module), obtains the source code
+ * for said module from the loader API, and parses the result for the entities
+ * exported from that module.
+ *
+ * This is a "sans-io" generator: instead of calling the loader's `load` hook
+ * directly, it `yield`s `[LOAD, url, context]` and is driven by either
+ * {@link driveSync} or {@link driveAsync} (see `lib/io.mjs`). The same body
+ * therefore serves both the off-thread loader and `module.registerHooks`.
  *
- * @param {string} url A file URL string pointing to the module that
- * we should get the exports of.
- * @param {object} context Context object as provided by the `load`
- * hook from the loaders API.
- * @param {Function} parentLoad Next hook function in the loaders API
- * hook chain.
+ * @param {string} url A file URL string pointing to the module that we should
+ * get the exports of.
+ * @param {object} context Context object as provided by the `load` hook from
+ * the loaders API.
  *
- * @returns {Promise<Set<string>>} An array of identifiers exported by the module.
+ * @returns {Generator<Array, Set<string>>} A generator that yields I/O
+ * operations and ultimately returns the identifiers exported by the module.
  * Please see {@link getEsmExports} for caveats on special identifiers that may
  * be included in the result set.
  */
-export async function getExports (url, context, parentLoad) {
-  // `parentLoad` gives us the possibility of getting the source
-  // from an upstream loader. This doesn't always work though,
-  // so later on we fall back to reading it from disk.
-  const parentCtx = await parentLoad(url, context)
+export function * getExports (url, context) {
+  // `[LOAD, ...]` gives us the possibility of getting the source from an
+  // upstream loader. This doesn't always work though, so later on we fall back
+  // to reading it from disk.
+  const parentCtx = yield [LOAD, url, context]
   let source = parentCtx.source
   const format = parentCtx.format
 
@@ -336,7 +367,7 @@ export async function getExports (url, context, parentLoad) {
     }
 
     if (format === 'commonjs') {
-      return await getCjsExports(url, context, parentLoad, source)
+      return yield * getCjsExports(url, context, source)
     }
 
     // At this point our `format` is either undefined or not known by us. Fall
@@ -349,7 +380,7 @@ export async function getExports (url, context, parentLoad) {
       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 await getCjsExports(url, context, parentLoad, source)
+        return yield * getCjsExports(url, context, source)
       }
     }
     return esmExports

package/lib/io.mjs

@@ -0,0 +1,78 @@
+'use strict'
+
+// The export-collection logic (resolving star re-exports, reading source,
+// parsing exports) is identical whether `import-in-the-middle` runs as an
+// off-thread loader (`module.register`, asynchronous `nextResolve`/`nextLoad`)
+// or as an in-thread synchronous loader (`module.registerHooks`). To keep a
+// single implementation of that logic — instead of two copies that drift — it
+// is written as "sans-io" generators that `yield` the I/O they need and let a
+// driver fulfil it. The async driver awaits; the sync driver calls straight
+// through. Everything between the yields is shared.
+
+// Operation kinds a loader generator may yield. Each is `[KIND, ...args]`.
+export const LOAD = 0 // [LOAD, url, context]      -> resolves to { source, format }
+export const RESOLVE = 1 // [RESOLVE, specifier, context] -> resolves to { url, format }
+
+function runOp (op, io) {
+  if (op[0] === RESOLVE) {
+    return io.resolve(op[1], op[2])
+  }
+  return io.load(op[1], op[2])
+}
+
+/**
+ * Drives a loader generator to completion, fulfilling each yielded I/O
+ * operation synchronously. Used with `module.registerHooks`, whose
+ * `nextResolve`/`nextLoad` return their result directly.
+ *
+ * Errors from I/O are thrown back into the generator (via `gen.throw`) so its
+ * `try`/`finally` blocks run exactly as they would for an `await` rejection.
+ *
+ * @template T
+ * @param {Generator<Array, T>} gen
+ * @param {{ load: Function, resolve?: Function }} io
+ * @returns {T}
+ */
+export function driveSync (gen, io) {
+  let next = gen.next()
+  while (next.done === false) {
+    let result
+    let error
+    let threw = false
+    try {
+      result = runOp(next.value, io)
+    } catch (err) {
+      threw = true
+      error = err
+    }
+    next = threw ? gen.throw(error) : gen.next(result)
+  }
+  return next.value
+}
+
+/**
+ * Drives a loader generator to completion, awaiting each yielded I/O
+ * operation. Used with the off-thread `module.register` loader, whose
+ * `nextResolve`/`nextLoad` are asynchronous.
+ *
+ * @template T
+ * @param {Generator<Array, T>} gen
+ * @param {{ load: Function, resolve?: Function }} io
+ * @returns {Promise<T>}
+ */
+export async function driveAsync (gen, io) {
+  let next = gen.next()
+  while (next.done === false) {
+    let result
+    let error
+    let threw = false
+    try {
+      result = await runOp(next.value, io)
+    } catch (err) {
+      threw = true
+      error = err
+    }
+    next = threw ? gen.throw(error) : gen.next(result)
+  }
+  return next.value
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "import-in-the-middle",
-  "version": "3.0.2",
+  "version": "3.2.0",
   "description": "Intercept imports in Node.js",
   "engines": {
     "node": ">=18"

package/register-hooks.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for {@link register}. `include`/`exclude` accept bare specifiers,
+ * `file:` URLs or regular expressions, matched against the module being
+ * resolved.
+ */
+export type RegisterHooksOptions = {
+  include?: Array<string | RegExp>
+  exclude?: Array<string | RegExp>
+}
+
+/**
+ * Registers `import-in-the-middle` as a *synchronous*, in-thread loader hook via
+ * [`module.registerHooks()`](https://nodejs.org/api/module.html#moduleregisterhooksoptions).
+ *
+ * Unlike `module.register('import-in-the-middle/hook.mjs', ...)`, which runs the
+ * loader on a separate thread and pays an IPC round-trip per resolved module,
+ * 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).
+ *
+ * ```ts
+ * import { register } from 'import-in-the-middle/register-hooks.mjs'
+ * import { Hook } from 'import-in-the-middle'
+ *
+ * register({ include: ['package-i-want-to-include'] })
+ *
+ * Hook(['package-i-want-to-include'], (exported, name, baseDir) => {
+ *   // Instrument the module
+ * })
+ * ```
+ *
+ * @throws If `module.registerHooks()` is unavailable in the running Node.js.
+ */
+export declare function register(options?: RegisterHooksOptions): void

package/register-hooks.mjs

@@ -0,0 +1,63 @@
+import * as module from 'module'
+import { createHook, supportsSyncHooks } from './create-hook.mjs'
+
+export { supportsSyncHooks }
+
+const hook = createHook(import.meta)
+
+let registered = false
+
+/**
+ * Registers `import-in-the-middle` as a *synchronous*, in-thread loader hook via
+ * [`module.registerHooks()`](https://nodejs.org/api/module.html#moduleregisterhooksoptions).
+ *
+ * Unlike `module.register('import-in-the-middle/hook.mjs', ...)`, which runs the
+ * loader on a separate thread and pays an IPC round-trip per resolved module,
+ * synchronous hooks run in the application thread. There is no message channel
+ * to bridge, so `Hook()` registrations from the main `import-in-the-middle`
+ * entry point are visible to the loader directly and no acknowledgement step is
+ * required.
+ *
+ * Requires a Node.js version whose `module.registerHooks` accepts the nullish
+ * CommonJS source the loader relies on: >= 22.22.3, >= 24.11.1, >= 25.1.0, or
+ * >= 26.0.0 (see `supportsSyncHooks`). Use that predicate to fall back to the
+ * asynchronous `module.register` loader on unsupported versions.
+ *
+ * ```js
+ * import { register } from 'import-in-the-middle/register-hooks.mjs'
+ * import { Hook } from 'import-in-the-middle'
+ *
+ * register({ include: ['package-i-want-to-include'] })
+ *
+ * Hook(['package-i-want-to-include'], (exported, name, baseDir) => {
+ *   // Instrument the module
+ * })
+ * ```
+ *
+ * @param {object} [options]
+ * @param {Array<string|RegExp>} [options.include] Only intercept these modules.
+ * @param {Array<string|RegExp>} [options.exclude] Never intercept these modules.
+ * @returns {void}
+ */
+export function register (options) {
+  if (!supportsSyncHooks()) {
+    throw new Error(
+      "'import-in-the-middle' synchronous hooks require a Node.js version whose " +
+      'module.registerHooks accepts nullish CommonJS source ' +
+      '(>= 22.22.3, >= 24.11.1, >= 25.1.0, or >= 26.0.0); ' +
+      'see https://github.com/nodejs/node/pull/59929'
+    )
+  }
+
+  if (registered) {
+    process.emitWarning("'import-in-the-middle' synchronous hooks have already been registered")
+    return
+  }
+  registered = true
+
+  if (options) {
+    hook.applyOptions(options)
+  }
+
+  module.registerHooks({ resolve: hook.resolveSync, load: hook.loadSync })
+}