import-in-the-middle 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [2.0.6](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v2.0.5...import-in-the-middle-v2.0.6) (2026-01-27)
+
+
+### Bug Fixes
+
+* ensure the callback 'name' arg is the module name when matching the module main file, even when 'internals: true' option is used ([#241](https://github.com/nodejs/import-in-the-middle/issues/241)) ([ad9d02c](https://github.com/nodejs/import-in-the-middle/commit/ad9d02cd774df110c5e2f72e6cca414d7c315404))
+* fix a couple issues with duplicate entries and specifier (submodule) matching ([#237](https://github.com/nodejs/import-in-the-middle/issues/237)) ([fdc0b3d](https://github.com/nodejs/import-in-the-middle/commit/fdc0b3d5863a1338586e25a94b831fee1bd8bd0b))
+* properly hook builtin modules that require the 'node:' prefix ([#240](https://github.com/nodejs/import-in-the-middle/issues/240)) ([de84589](https://github.com/nodejs/import-in-the-middle/commit/de8458962958182eac743e99edeb944160638e2c))
+* properly hook builtin modules that require the 'node:' prefix ([#240](https://github.com/nodejs/import-in-the-middle/issues/240)) ([9d916a5](https://github.com/nodejs/import-in-the-middle/commit/9d916a59b4a95b2a22568d1e8f65948598178de9))
+
+## [2.0.5](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v2.0.4...import-in-the-middle-v2.0.5) (2026-01-20)
+
+
+### Bug Fixes
+
+* handle lazy initialization and circular dependencies ([#229](https://github.com/nodejs/import-in-the-middle/issues/229)) ([d1421dc](https://github.com/nodejs/import-in-the-middle/commit/d1421dc0ae65ce6da5de5cb58f41af99f9d87371))
+* entrypoint can be treated as CommonJS when loader chains add query params to file URLs ([#223](https://github.com/nodejs/import-in-the-middle/issues/223)) ([60ab14a](https://github.com/nodejs/import-in-the-middle/commit/60ab14aeed8960b5dec4bec571a81649363e256e))
+
 ## [2.0.4](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v2.0.3...import-in-the-middle-v2.0.4) (2026-01-14)
 
 

package/README.md

@@ -44,11 +44,13 @@ API. However, for this to be able to hook non-dynamic imports, it needs to be
 registered before your app code is evaluated via the `--import` command-line option.
 
 `my-loader.mjs`
+
 ```js
 import * as module from 'module'
 
 module.register('import-in-the-middle/hook.mjs', import.meta.url)
 ```
+
 ```shell
 node --import=./my-loader.mjs ./my-code.mjs
 ```
@@ -56,7 +58,7 @@ node --import=./my-loader.mjs ./my-code.mjs
 When registering the loader hook programmatically, it's possible to pass a list
 of modules, file URLs or regular expressions to either `exclude` or specifically
 `include` which modules are intercepted. This is useful if a module is not
-compatible with the loader hook. 
+compatible with the loader hook.
 
 > **Note:** This feature is incompatible with the `{internals: true}` Hook option
 
@@ -74,7 +76,8 @@ module.register('import-in-the-middle/hook.mjs', import.meta.url, {
 })
 ```
 
-### Only Intercepting Hooked modules 
+### Only Intercepting Hooked modules
+
 > **Note:** This feature is experimental and is incompatible with the `{internals: true}` Hook option
 
 If you are `Hook`'ing all modules before they are imported, for example in a
@@ -82,6 +85,7 @@ module loaded via the Node.js `--import` CLI argument, you can configure the
 loader to intercept only modules that were specifically hooked.
 
 `instrument.mjs`
+
 ```js
 import { register } from 'module'
 import { Hook, createAddHookMessageChannel } from 'import-in-the-middle'
@@ -94,11 +98,13 @@ Hook(['fs'], (exported, name, baseDir) => {
   // Instrument the fs module
 })
 
-// Ensure that the loader has acknowledged all the modules 
+// Ensure that the loader has acknowledged all the modules
 // before we allow execution to continue
 await waitForAllMessagesAcknowledged()
 ```
+
 `my-app.mjs`
+
 ```js
 import * as fs from 'fs'
 // fs will be instrumented!
@@ -109,23 +115,6 @@ fs.readFileSync('file.txt')
 node --import=./instrument.mjs ./my-app.mjs
 ```
 
-### Experimental `experimentalPatchInternals` option
-
-It was found that `import-in-the-middle` didn't match the hooking behavior of `require-in-the-middle` in some cases: 
-https://github.com/nodejs/import-in-the-middle/issues/185
-
-The `experimentalPatchInternals` option forces the loader to match the behavior of `require-in-the-middle` in these cases.
-
-This option is experimental and may be removed or made the default in the future.
-
-```js
-import { register } from 'module'
-
-register('import-in-the-middle/hook.mjs', import.meta.url, {
-  data: { experimentalPatchInternals: true }
-})
-```
-
 ## Limitations
 
 * You cannot add new exports to a module. You can only modify existing ones.

package/create-hook.mjs

@@ -12,7 +12,6 @@ import {
 
 const specifiers = new Map()
 const isWin = process.platform === 'win32'
-let experimentalPatchInternals = false
 
 // FIXME: Typescript extensions are added temporarily until we find a better
 // way of supporting arbitrary extensions
@@ -24,7 +23,7 @@ const HANDLED_FORMATS = new Set(['builtin', 'module', 'commonjs'])
 const TRACE_WARNINGS = process.execArgv.includes('--trace-warnings')
 
 let getExports
-if (NODE_MAJOR >= 20 || (NODE_MAJOR === 18 && NODE_MINOR >= 19)) {
+if (NODE_MAJOR > 16 || (NODE_MAJOR === 16 && NODE_MINOR >= 16)) {
   getExports = getExportsImpl
 } else {
   getExports = (url) => import(url).then(Object.keys)
@@ -61,9 +60,6 @@ function deleteIitm (url) {
     if (urlObj.searchParams.has('iitm')) {
       urlObj.searchParams.delete('iitm')
       resultUrl = urlObj.href
-      if (resultUrl.startsWith('file:node:')) {
-        resultUrl = resultUrl.replace('file:', '')
-      }
       if (resultUrl.startsWith('file:///node:')) {
         resultUrl = resultUrl.replace('file:///', '')
       }
@@ -295,13 +291,25 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
 
       addSetter(n, `
       let ${variableName}
+      __overridden[${objectKey}] = false
+      let ${variableName}Defer = false
       try {
         ${variableName} = _[${objectKey}] = namespace[${objectKey}]
       } catch (err) {
         if (!(err instanceof ReferenceError)) throw err
+        ${variableName}Defer = true
+      }
+
+      if (${variableName}Defer || ${variableName} === undefined) {
+        __pending.push(__makeUpdater(
+          ${objectKey},
+          () => namespace[${objectKey}],
+          (v) => { ${variableName} = _[${objectKey}] = v }
+        ))
       }
       export { ${variableName} as ${reExportedName} }
       set[${objectKey}] = (v) => {
+        __overridden[${objectKey}] = true
         ${variableName} = v
         return true
       }
@@ -332,10 +340,6 @@ export function createHook (meta) {
     global.__import_in_the_middle_initialized__ = true
 
     if (data) {
-      if (data.experimentalPatchInternals) {
-        experimentalPatchInternals = true
-      }
-
       includeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.include, 'include')
       excludeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.exclude, 'exclude')
 
@@ -381,7 +385,7 @@ export function createHook (meta) {
     // "main" module (e.g. require.main === module). Wrapping changes how they
     // are evaluated, and can make them exit without doing anything.
     if (parentURL === '') {
-      if (!EXTENSION_RE.test(result.url)) {
+      if (!EXTENSION_RE.test(result.url) && !hasIitm(result.url)) {
         entrypoint = result.url
         return { url: result.url, format: 'commonjs' }
       }
@@ -476,15 +480,70 @@ export function createHook (meta) {
           source: `
 import { register } from '${iitmURL}'
 import * as namespace from ${JSON.stringify(realUrl)}
-${experimentalPatchInternals ? `import { setExperimentalPatchInternals } from '${iitmURL}'\nsetExperimentalPatchInternals(true)` : ''}
 
 // Mimic a Module object (https://tc39.es/ecma262/#sec-module-namespace-objects).
 const _ = Object.create(null, { [Symbol.toStringTag]: { value: 'Module' } })
 const set = {}
 const get = {}
+const __overridden = Object.create(null)
+let __pending = []
+
+function __makeUpdater (key, read, assign) {
+  return () => {
+    if (__overridden[key] === true) return true
+    try {
+      const v = read()
+      if (v !== undefined) {
+        assign(v)
+        return true
+      }
+      return false
+    } catch (err) {
+      if (err instanceof ReferenceError) return false
+      throw err
+    }
+  }
+}
+
+function __flushPendingOnce () {
+  if (__pending.length === 0) return
+  const next = []
+  for (const fn of __pending) {
+    // If it still throws ReferenceError, keep it for the (single) next attempt.
+    if (fn() !== true) next.push(fn)
+  }
+  __pending = next
+}
 
 ${Array.from(setters.values()).join('\n')}
 
+if (__pending.length > 0) {
+  queueMicrotask(() => {
+    __flushPendingOnce()
+
+    if (__pending.length > 0) {
+      const __retryDelays = [0, 10, 50]
+      const __schedulePending = (i) => {
+        if (__pending.length === 0) return
+        if (i >= __retryDelays.length) {
+          // Give up: leave exports as-is to avoid unbounded retries.
+          __pending = []
+          return
+        }
+
+        const t = setTimeout(() => {
+          __flushPendingOnce()
+          __schedulePending(i + 1)
+        }, __retryDelays[i])
+        // Don't keep the process alive just for best-effort retries.
+        if (t && typeof t.unref === 'function') t.unref()
+      }
+
+      __schedulePending(0)
+    }
+  })
+}
+
 register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpecifier)})
 `
         }
@@ -518,12 +577,19 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
   // For Node.js 16.12.0 and higher.
   async function load (url, context, parentLoad) {
     if (hasIitm(url)) {
-      const { source } = await getSource(url, context, parentLoad)
-      return {
-        source,
-        shortCircuit: true,
-        format: 'module'
+      const result = await getSource(url, context, parentLoad)
+      // If wrapping failed, `getSource()` may have fallen back to `parentLoad`,
+      // 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 parentLoad(deleteIitm(url), context)
     }
 
     return parentLoad(url, context)

package/index.js

@@ -3,15 +3,19 @@
 // This product includes software developed at Datadog (https://www.datadoghq.com/). Copyright 2021 Datadog, Inc.
 
 const path = require('path')
-const parse = require('module-details-from-path')
+const moduleDetailsFromPath = require('module-details-from-path')
 const { fileURLToPath } = require('url')
 const { MessageChannel } = require('worker_threads')
 
+let { isBuiltin } = require('module')
+if (!isBuiltin) {
+  isBuiltin = () => true
+}
+
 const {
   importHooks,
   specifiers,
-  toHook,
-  getExperimentalPatchInternals
+  toHook
 } = require('./lib/register')
 
 function addHook (hook) {
@@ -124,43 +128,58 @@ function Hook (modules, options, hookFn) {
   }
 
   this._iitmHook = (name, namespace, specifier) => {
-    const filename = name
-    const isBuiltin = name.startsWith('node:')
-    let baseDir
-
-    if (isBuiltin) {
-      name = name.replace(/^node:/, '')
-    } else {
-      if (name.startsWith('file://')) {
-        const stackTraceLimit = Error.stackTraceLimit
-        Error.stackTraceLimit = 0
-        try {
-          name = fileURLToPath(name)
-        } catch (e) {}
-        Error.stackTraceLimit = stackTraceLimit
+    const loadUrl = name
+    const isNodeUrl = loadUrl.startsWith('node:')
+    let filePath, baseDir
+
+    if (isNodeUrl) {
+      // Normalize builtin module name to *not* have 'node:' prefix, unless
+      // required, as it is for 'node:test' and some others.  `module.isBuiltin`
+      // is available in all Node.js versions that have node:-only modules.
+      const unprefixed = name.slice(5)
+      if (isBuiltin(unprefixed)) {
+        name = unprefixed
       }
-      const details = parse(name)
-      if (details) {
-        name = details.name
-        baseDir = details.basedir
+    } else if (loadUrl.startsWith('file://')) {
+      const stackTraceLimit = Error.stackTraceLimit
+      Error.stackTraceLimit = 0
+      try {
+        filePath = fileURLToPath(name)
+        name = filePath
+      } catch (e) {}
+      Error.stackTraceLimit = stackTraceLimit
+
+      if (filePath) {
+        const details = moduleDetailsFromPath(filePath)
+        if (details) {
+          name = details.name
+          baseDir = details.basedir
+        }
       }
     }
 
     if (modules) {
-      for (const moduleName of modules) {
-        const nameMatch = moduleName === name
-        const specMatch = moduleName === specifier
-        if (nameMatch || specMatch) {
-          if (baseDir) {
-            if (internals) {
-              name = name + path.sep + path.relative(baseDir, fileURLToPath(filename))
-            } else {
-              if (!getExperimentalPatchInternals() && !specMatch && !baseDir.endsWith(specifiers.get(filename))) {
-                continue
-              }
-            }
+      for (const matchArg of modules) {
+        if (filePath && matchArg === filePath) {
+          // abspath match
+          callHookFn(hookFn, namespace, filePath, undefined)
+        } else if (matchArg === name) {
+          if (!baseDir) {
+            // built-in module (or unexpected non file:// name?)
+            callHookFn(hookFn, namespace, name, baseDir)
+          } else if (baseDir.endsWith(specifiers.get(loadUrl))) {
+            // An import of the top-level module (e.g. `import 'ioredis'`).
+            // Note: Slight behaviour difference from RITM. RITM uses
+            // `require.resolve(name)` to see if filename is the module
+            // main file, which will catch `require('ioredis/built/index.js')`.
+            // The check here will not catch `import 'ioredis/built/index.js'`.
+            callHookFn(hookFn, namespace, name, baseDir)
+          } else if (internals) {
+            const internalPath = name + path.sep + path.relative(baseDir, filePath)
+            callHookFn(hookFn, namespace, internalPath, baseDir)
           }
-          callHookFn(hookFn, namespace, name, baseDir)
+        } else if (matchArg === specifier) {
+          callHookFn(hookFn, namespace, specifier, baseDir)
         }
       }
     } else {

package/lib/get-exports.mjs

@@ -299,6 +299,21 @@ export async function getExports (url, context, parentLoad) {
   let source = parentCtx.source
   const format = parentCtx.format
 
+  // Loader hooks can return ArrayBuffer / TypedArray sources. Normalize to a
+  // string for parsing.
+  if (source && typeof source !== 'string') {
+    // Avoid copies where possible:
+    // - Buffer.from(Uint8Array) copies
+    // - Buffer.from(ArrayBuffer, offset, length) wraps the existing memory
+    if (Buffer.isBuffer(source)) {
+      source = source.toString('utf8')
+    } else if (ArrayBuffer.isView(source)) {
+      source = Buffer.from(source.buffer, source.byteOffset, source.byteLength).toString('utf8')
+    } else {
+      source = Buffer.from(source).toString('utf8')
+    }
+  }
+
   if (!source) {
     if (format === 'builtin') {
       // Builtins don't give us the source property, so we're stuck

package/lib/register.js

@@ -55,19 +55,7 @@ function register (name, namespace, set, get, specifier) {
   toHook.push([name, proxy, specifier])
 }
 
-let experimentalPatchInternals = false
-
-function getExperimentalPatchInternals () {
-  return experimentalPatchInternals
-}
-
-function setExperimentalPatchInternals (value) {
-  experimentalPatchInternals = value
-}
-
 exports.register = register
 exports.importHooks = importHooks
 exports.specifiers = specifiers
 exports.toHook = toHook
-exports.getExperimentalPatchInternals = getExperimentalPatchInternals
-exports.setExperimentalPatchInternals = setExperimentalPatchInternals

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "import-in-the-middle",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Intercept imports in Node.js",
   "main": "index.js",
   "scripts": {
-    "test": "c8 --reporter lcov --check-coverage --lines 50 imhotap --files test/{hook,low-level,other,get-esm-exports,register}/*",
+    "test": "c8 --reporter lcov --check-coverage --lines 45 imhotap --files test/{hook,low-level,other,get-esm-exports,register}/*",
     "test:e2e": "node test/check-exports/test.mjs",
     "test:ts": "c8 --reporter lcov imhotap --files test/typescript/*.test.mts",
-    "coverage": "c8 --reporter html imhotap --files test/{hook,low-level,other,get-esm-exports}/* && echo '\nNow open coverage/index.html\n'",
+    "coverage": "c8 --reporter html imhotap --files test/{hook,low-level,other,get-esm-exports,register}/* && echo \"\nNow open coverage/index.html\n\"",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix"
   },