import-in-the-middle 2.0.5 → 3.0.0

package/CHANGELOG.md

@@ -1,11 +1,33 @@
 # Changelog
 
+## [3.0.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v2.0.6...import-in-the-middle-v3.0.0) (2026-01-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* drop support for Node.js < v18 ([#230](https://github.com/nodejs/import-in-the-middle/issues/230))
+
+### Miscellaneous Chores
+
+* drop support for Node.js &lt; v18 ([#230](https://github.com/nodejs/import-in-the-middle/issues/230)) ([f463b13](https://github.com/nodejs/import-in-the-middle/commit/f463b1342ca946608432c9be39fecb86e7f7cbf0))
+
+## [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
@@ -30,8 +29,6 @@ if (NODE_MAJOR > 16 || (NODE_MAJOR === 16 && NODE_MINOR >= 16)) {
   getExports = (url) => import(url).then(Object.keys)
 }
 
-let entrypoint
-
 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) {
@@ -61,9 +58,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:///', '')
       }
@@ -77,28 +71,6 @@ function deleteIitm (url) {
   return resultUrl
 }
 
-function isNodeMajor16AndMinor17OrGreater () {
-  return NODE_MAJOR === 16 && NODE_MINOR >= 17
-}
-
-function isFileProtocol (urlObj) {
-  return urlObj.protocol === 'file:'
-}
-
-function isNodeProtocol (urlObj) {
-  return urlObj.protocol === 'node:'
-}
-
-function needsToAddFileProtocol (urlObj) {
-  if (NODE_MAJOR === 17) {
-    return !isFileProtocol(urlObj)
-  }
-  if (isNodeMajor16AndMinor17OrGreater()) {
-    return !isFileProtocol(urlObj) && !isNodeProtocol(urlObj)
-  }
-  return !isFileProtocol(urlObj) && NODE_MAJOR < 18
-}
-
 /**
  * Determines if a specifier represents an export all ESM line.
  * Note that the expected `line` isn't 100% valid ESM. It is derived
@@ -291,7 +263,7 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
     } else {
       const variableName = `$${n.replace(/[^a-zA-Z0-9_$]/g, '_')}`
       const objectKey = JSON.stringify(n)
-      const reExportedName = n === 'default' || NODE_MAJOR < 16 ? n : objectKey
+      const reExportedName = n === 'default' ? n : objectKey
 
       addSetter(n, `
       let ${variableName}
@@ -328,7 +300,7 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
 function addIitm (url) {
   const urlObj = new URL(url)
   urlObj.searchParams.set('iitm', 'true')
-  return needsToAddFileProtocol(urlObj) ? 'file:' + urlObj.href : urlObj.href
+  return urlObj.href
 }
 
 export function createHook (meta) {
@@ -344,10 +316,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')
 
@@ -394,13 +362,9 @@ export function createHook (meta) {
     // are evaluated, and can make them exit without doing anything.
     if (parentURL === '') {
       if (!EXTENSION_RE.test(result.url) && !hasIitm(result.url)) {
-        entrypoint = result.url
         return { url: result.url, format: 'commonjs' }
       }
-      if (NODE_MAJOR > 16 || (NODE_MAJOR === 16 && NODE_MINOR >= 16)) {
-        entrypoint = result.url
-        return result
-      }
+      return result
     }
 
     // For included/excluded modules, we check the specifier to match libraries
@@ -488,7 +452,6 @@ 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' } })
@@ -583,7 +546,6 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
     return parentGetSource(url, context)
   }
 
-  // For Node.js 16.12.0 and higher.
   async function load (url, context, parentLoad) {
     if (hasIitm(url)) {
       const result = await getSource(url, context, parentLoad)
@@ -604,28 +566,5 @@ register(${JSON.stringify(realUrl)}, _, set, get, ${JSON.stringify(originalSpeci
     return parentLoad(url, context)
   }
 
-  if (NODE_MAJOR >= 17 || (NODE_MAJOR === 16 && NODE_MINOR >= 12)) {
-    return { initialize, load, resolve }
-  } else {
-    return {
-      initialize,
-      load,
-      resolve,
-      getSource,
-      getFormat (url, context, parentGetFormat) {
-        if (hasIitm(url)) {
-          return {
-            format: 'module'
-          }
-        }
-        if (url === entrypoint) {
-          return {
-            format: 'commonjs'
-          }
-        }
-
-        return parentGetFormat(url, context)
-      }
-    }
-  }
+  return { initialize, load, resolve }
 }

package/hook.mjs

@@ -4,6 +4,6 @@
 
 import { createHook } from './create-hook.mjs'
 
-const { initialize, load, resolve, getFormat, getSource } = createHook(import.meta)
+const { initialize, load, resolve } = createHook(import.meta)
 
-export { initialize, load, resolve, getFormat, getSource }
+export { initialize, load, resolve }

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,16 @@
 {
   "name": "import-in-the-middle",
-  "version": "2.0.5",
+  "version": "3.0.0",
   "description": "Intercept imports in Node.js",
+  "engines": {
+    "node": ">=18"
+  },
   "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"
   },