import-in-the-middle 1.9.1 → 1.11.0

package/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "1.9.1"
+  ".": "1.11.0"
 }

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [1.11.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v1.10.0...import-in-the-middle-v1.11.0) (2024-07-29)
+
+
+### Features
+
+* Optionally only wrap modules hooked in `--import` ([#146](https://github.com/nodejs/import-in-the-middle/issues/146)) ([71c8d7b](https://github.com/nodejs/import-in-the-middle/commit/71c8d7bac512df94566d12c96fc2e438b4de2e2a))
+
+
+### Bug Fixes
+
+* `node:` prefixed build-in modules with `include`/`exclude` ([#149](https://github.com/nodejs/import-in-the-middle/issues/149)) ([736a944](https://github.com/nodejs/import-in-the-middle/commit/736a9446e209bc8649801a27cb431df663551dc5))
+
+## [1.10.0](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v1.9.1...import-in-the-middle-v1.10.0) (2024-07-22)
+
+
+### Features
+
+* Allow regex for `include` and `exclude` options ([#148](https://github.com/nodejs/import-in-the-middle/issues/148)) ([697b0d2](https://github.com/nodejs/import-in-the-middle/commit/697b0d239b9a738f4952bb0f77c521c4a398ac79))
+
+
+### Bug Fixes
+
+* Use correct `format` when resolving exports from relative paths ([#145](https://github.com/nodejs/import-in-the-middle/issues/145)) ([632802f](https://github.com/nodejs/import-in-the-middle/commit/632802f4e7c797215b4e052ffdfa0fbda1780166))
+
 ## [1.9.1](https://github.com/nodejs/import-in-the-middle/compare/import-in-the-middle-v1.9.0...import-in-the-middle-v1.9.1) (2024-07-15)
 
 

package/README.md

@@ -34,14 +34,14 @@ console.log(foo) // 1 more than whatever that module exported
 This requires the use of an ESM loader hook, which can be added with the following
 command-line option.
 
-```
---loader=import-in-the-middle/hook.mjs
+```shell
+node --loader=import-in-the-middle/hook.mjs my-app.mjs
 ```
 
-It's also possible to register the loader hook programmatically via the Node
+Since `--loader` has been deprecated you can also register the loader hook programmatically via the Node
 [`module.register()`](https://nodejs.org/api/module.html#moduleregisterspecifier-parenturl-options)
 API. However, for this to be able to hook non-dynamic imports, it needs to be
-loaded before your app code is evaluated via the `--import` command-line option.
+registered before your app code is evaluated via the `--import` command-line option.
 
 `my-loader.mjs`
 ```js
@@ -54,9 +54,12 @@ node --import=./my-loader.mjs ./my-code.mjs
 ```
 
 When registering the loader hook programmatically, it's possible to pass a list
-of modules or file URLs to either exclude or specifically include which modules
-are intercepted. This is useful if a module is not compatible with the loader
-hook. 
+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. 
+
+> **Note:** This feature is incompatible with the `{internals: true}` Hook option
+
 ```js
 import * as module from 'module'
 
@@ -71,6 +74,41 @@ module.register('import-in-the-middle/hook.mjs', import.meta.url, {
 })
 ```
 
+### 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
+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'
+
+const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel()
+
+register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions)
+
+Hook(['fs'], (exported, name, baseDir) => {
+  // Instrument the fs module
+})
+
+// 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!
+fs.readFileSync('file.txt')
+```
+
+```shell
+node --import=./instrument.mjs ./my-app.mjs
+```
+
 ## Limitations
 
 * You cannot add new exports to a module. You can only modify existing ones.

package/hook.js

@@ -4,6 +4,7 @@
 
 const { URL } = require('url')
 const { inspect } = require('util')
+const { builtinModules } = require('module')
 const specifiers = new Map()
 const isWin = process.platform === 'win32'
 
@@ -116,7 +117,16 @@ function isBareSpecifier (specifier) {
   }
 }
 
-function isBareSpecifierOrFileUrl (input) {
+/**
+ * Determines whether the input is a bare specifier, file URL or a regular expression.
+ *
+ * - node: prefixed URL strings are considered bare specifiers in this context.
+ */
+function isBareSpecifierFileUrlOrRegex (input) {
+  if (input instanceof RegExp) {
+    return true
+  }
+
   // Relative and absolute paths
   if (
     input.startsWith('.') ||
@@ -127,22 +137,38 @@ function isBareSpecifierOrFileUrl (input) {
   try {
     // eslint-disable-next-line no-new
     const url = new URL(input)
-    return url.protocol === 'file:'
+    // We consider node: URLs bare specifiers in this context
+    return url.protocol === 'file:' || url.protocol === 'node:'
   } catch (err) {
     // Anything that fails parsing is a bare specifier
     return true
   }
 }
 
-function ensureArrayWithBareSpecifiersAndFileUrls (array, type) {
+/**
+ * Ensure an array only contains bare specifiers, file URLs or regular expressions.
+ *
+ * - We consider node: prefixed URL string as bare specifiers in this context.
+ * - For node built-in modules, we add additional node: prefixed modules to the
+ *   output array.
+ */
+function ensureArrayWithBareSpecifiersFileUrlsAndRegex (array, type) {
   if (!Array.isArray(array)) {
     return undefined
   }
 
-  const invalid = array.filter(s => !isBareSpecifierOrFileUrl(s))
+  const invalid = array.filter(s => !isBareSpecifierFileUrlOrRegex(s))
 
   if (invalid.length) {
-    throw new Error(`'${type}' option only supports bare specifiers and file URLs. Invalid entries: ${inspect(invalid)}`)
+    throw new Error(`'${type}' option only supports bare specifiers, file URLs or regular expressions. Invalid entries: ${inspect(invalid)}`)
+  }
+
+  // Rather than evaluate whether we have a node: scoped built-in-module for
+  // every call to resolve, we just add them to include/exclude now.
+  for (const each of array) {
+    if (typeof each === 'string' && !each.startsWith('node:') && builtinModules.includes(each)) {
+      array.push(`node:${each}`)
+    }
   }
 
   return array
@@ -206,19 +232,24 @@ async function processModule ({ srcUrl, context, parentGetSource, parentResolve,
     if (isStarExportLine(n) === true) {
       const [, modFile] = n.split('* from ')
 
-      async function processSubModule (url, ctx) {
-        const setters = await processModule({ srcUrl: url, context: ctx, parentGetSource, parentResolve, excludeDefault: true })
-        for (const [name, setter] of setters.entries()) {
-          addSetter(name, setter, true)
-        }
-      }
-
-      if (isBareSpecifier(modFile)) {
-        // Bare specifiers need to be resolved relative to the parent module.
-        const result = await parentResolve(modFile, { parentURL: srcUrl })
-        await processSubModule(result.url, { ...context, format: result.format })
-      } else {
-        await processSubModule(new URL(modFile, srcUrl).href, context)
+      // 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 })
+
+      const subSetters = await processModule({
+        srcUrl: result.url,
+        context: { ...context, format: result.format },
+        parentGetSource,
+        parentResolve,
+        excludeDefault: true
+      })
+
+      for (const [name, setter] of subSetters.entries()) {
+        addSetter(name, setter, true)
       }
     } else {
       addSetter(n, `
@@ -248,15 +279,33 @@ function createHook (meta) {
 
   async function initialize (data) {
     if (data) {
-      includeModules = ensureArrayWithBareSpecifiersAndFileUrls(data.include, 'include')
-      excludeModules = ensureArrayWithBareSpecifiersAndFileUrls(data.exclude, 'exclude')
+      includeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.include, 'include')
+      excludeModules = ensureArrayWithBareSpecifiersFileUrlsAndRegex(data.exclude, 'exclude')
+
+      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}`)
+            }
+
+            includeModules.push(each)
+          }
+
+          data.addHookMessagePort.postMessage('ack')
+        }).unref()
+      }
     }
   }
 
   async function resolve (specifier, context, parentResolve) {
     cachedResolve = parentResolve
 
-    // See github.com/nodejs/import-in-the-middle/pull/76.
+    // See https://github.com/nodejs/import-in-the-middle/pull/76.
     if (specifier === iitmURL) {
       return {
         url: specifier,
@@ -278,13 +327,21 @@ function createHook (meta) {
     // 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 only support matching file URL strings
-    // because using relative paths would be very error prone!
-    if (includeModules && !includeModules.some(lib => lib === specifier || lib === result.url.url)) {
+    // For non-bare specifier imports, we match to the full file URL because
+    // using relative paths would be very error prone!
+    function match (each) {
+      if (each instanceof RegExp) {
+        return each.test(result.url)
+      }
+
+      return each === specifier || each === result.url
+    }
+
+    if (includeModules && !includeModules.some(match)) {
       return result
     }
 
-    if (excludeModules && excludeModules.some(lib => lib === specifier || lib === result.url.url)) {
+    if (excludeModules && excludeModules.some(match)) {
       return result
     }
 

package/index.d.ts

@@ -84,3 +84,39 @@ export declare function addHook(hookFn: HookFunction): void
  * @param {HookFunction} hookFn The function to be removed.
  */
 export declare function removeHook(hookFn: HookFunction): void
+
+type CreateAddHookMessageChannelReturn<Data> = {
+  addHookMessagePort: MessagePort,
+  waitForAllMessagesAcknowledged: Promise<void>
+  registerOptions: { data?: Data; transferList?: any[]; }
+}
+
+/**
+ * EXPERIMENTAL
+ * This feature is experimental and may change in minor versions.
+ * **NOTE** This feature is incompatible with the {internals: true} Hook option.
+ *
+ * Creates a message channel with a port that can be used to add hooks to the
+ * list of exclusively included modules.
+ *
+ * This can be used to only wrap modules that are Hook'ed, however modules need
+ * to be hooked before they are imported.
+ *
+ * ```ts
+ * import { register } from 'module'
+ * import { Hook, createAddHookMessageChannel } from 'import-in-the-middle'
+ *
+ * const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel()
+ *
+ * register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions)
+ *
+ * Hook(['fs'], (exported, name, baseDir) => {
+ *   // Instrument the fs module
+ * })
+ *
+ * // Ensure that the loader has acknowledged all the modules
+ * // before we allow execution to continue
+ * await waitForAllMessagesAcknowledged()
+ * ```
+ */
+export declare function createAddHookMessageChannel<Data = any>(): CreateAddHookMessageChannelReturn<Data>;

package/index.js

@@ -5,6 +5,7 @@
 const path = require('path')
 const parse = require('module-details-from-path')
 const { fileURLToPath } = require('url')
+const { MessageChannel } = require('worker_threads')
 
 const {
   importHooks,
@@ -31,6 +32,75 @@ function callHookFn (hookFn, namespace, name, baseDir) {
   }
 }
 
+let sendModulesToLoader
+
+/**
+ * EXPERIMENTAL
+ * This feature is experimental and may change in minor versions.
+ * **NOTE** This feature is incompatible with the {internals: true} Hook option.
+ *
+ * Creates a message channel with a port that can be used to add hooks to the
+ * list of exclusively included modules.
+ *
+ * This can be used to only wrap modules that are Hook'ed, however modules need
+ * to be hooked before they are imported.
+ *
+ * ```ts
+ * import { register } from 'module'
+ * import { Hook, createAddHookMessageChannel } from 'import-in-the-middle'
+ *
+ * const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel()
+ *
+ * register('import-in-the-middle/hook.mjs', import.meta.url, registerOptions)
+ *
+ * Hook(['fs'], (exported, name, baseDir) => {
+ *   // Instrument the fs module
+ * })
+ *
+ * // Ensure that the loader has acknowledged all the modules
+ * // before we allow execution to continue
+ * await waitForAllMessagesAcknowledged()
+ * ```
+ */
+function createAddHookMessageChannel () {
+  const { port1, port2 } = new MessageChannel()
+  let pendingAckCount = 0
+  let resolveFn
+
+  sendModulesToLoader = (modules) => {
+    pendingAckCount++
+    port1.postMessage(modules)
+  }
+
+  port1.on('message', () => {
+    pendingAckCount--
+
+    if (resolveFn && pendingAckCount <= 0) {
+      resolveFn()
+    }
+  }).unref()
+
+  function waitForAllMessagesAcknowledged () {
+    // This timer is to prevent the process from exiting with code 13:
+    // 13: Unsettled Top-Level Await.
+    const timer = setInterval(() => { }, 1000)
+    const promise = new Promise((resolve) => {
+      resolveFn = resolve
+    }).then(() => { clearInterval(timer) })
+
+    if (pendingAckCount === 0) {
+      resolveFn()
+    }
+
+    return promise
+  }
+
+  const addHookMessagePort = port2
+  const registerOptions = { data: { addHookMessagePort, include: [] }, transferList: [addHookMessagePort] }
+
+  return { registerOptions, addHookMessagePort, waitForAllMessagesAcknowledged }
+}
+
 function Hook (modules, options, hookFn) {
   if ((this instanceof Hook) === false) return new Hook(modules, options, hookFn)
   if (typeof modules === 'function') {
@@ -43,6 +113,10 @@ function Hook (modules, options, hookFn) {
   }
   const internals = options ? options.internals === true : false
 
+  if (sendModulesToLoader && Array.isArray(modules)) {
+    sendModulesToLoader(modules)
+  }
+
   this._iitmHook = (name, namespace) => {
     const filename = name
     const isBuiltin = name.startsWith('node:')
@@ -92,3 +166,4 @@ module.exports = Hook
 module.exports.Hook = Hook
 module.exports.addHook = addHook
 module.exports.removeHook = removeHook
+module.exports.createAddHookMessageChannel = createAddHookMessageChannel

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "import-in-the-middle",
-  "version": "1.9.1",
+  "version": "1.11.0",
   "description": "Intercept imports in Node.js",
   "main": "index.js",
   "scripts": {

package/test/fixtures/import-after.mjs

@@ -0,0 +1,16 @@
+import { strictEqual } from 'assert'
+import { sep } from 'path'
+import * as os from 'node:os'
+import { Hook } from '../../index.js'
+
+const hooked = []
+
+Hook((_, name) => {
+  hooked.push(name)
+})
+
+strictEqual(hooked.length, 2)
+strictEqual(hooked[0], 'path')
+strictEqual(hooked[1], 'os')
+strictEqual(sep, '@')
+strictEqual(os.arch(), 'new_crazy_arch')

package/test/fixtures/import.mjs

@@ -0,0 +1,23 @@
+import { register } from 'module'
+import { Hook, createAddHookMessageChannel } from '../../index.js'
+// We've imported path here to ensure that the hook is still applied later even
+// if the library is used here.
+import * as path from 'path'
+
+const { registerOptions, waitForAllMessagesAcknowledged } = createAddHookMessageChannel()
+
+register('../../hook.mjs', import.meta.url, registerOptions)
+
+Hook(['path'], (exports) => {
+  exports.sep = '@'
+})
+
+Hook(['os'], (exports) => {
+  exports.arch = function () {
+    return 'new_crazy_arch'
+  }
+})
+
+console.assert(path.sep !== '@')
+
+await waitForAllMessagesAcknowledged()

package/test/hook/vue-server-renderer.mjs

@@ -1,5 +1,8 @@
-// https://github.com/nodejs/import-in-the-middle/issues/139
 import { strictEqual } from 'assert'
-import * as lib from 'vue/server-renderer'
+// https://github.com/nodejs/import-in-the-middle/issues/139
+import * as libServer from 'vue/server-renderer'
+// https://github.com/nodejs/import-in-the-middle/issues/144
+import * as lib from 'vue'
 
-strictEqual(typeof lib.renderToString, 'function')
+strictEqual(typeof libServer.renderToString, 'function')
+strictEqual(typeof lib.ref, 'function')

package/test/register/v18.19-exclude-regex.mjs

@@ -0,0 +1,16 @@
+import { register } from 'module'
+import Hook from '../../index.js'
+import { strictEqual } from 'assert'
+
+register('../../hook.mjs', import.meta.url, { data: { exclude: [/openai/] } })
+
+const hooked = new Set()
+
+Hook((_, name) => {
+  hooked.add(name)
+})
+
+await import('openai')
+
+strictEqual(hooked.has('openai'), false)
+strictEqual(hooked.has('fs'), true)

package/test/register/v18.19-include-builtin.mjs

@@ -0,0 +1,20 @@
+import { register } from 'module'
+import Hook from '../../index.js'
+import { strictEqual } from 'assert'
+
+register('../../hook.mjs', import.meta.url, { data: { include: ['node:util', 'os'] } })
+
+const hooked = []
+
+Hook((exports, name) => {
+  hooked.push(name)
+})
+
+await import('util')
+await import('node:os')
+await import('fs')
+await import('path')
+
+strictEqual(hooked.length, 2)
+strictEqual(hooked[0], 'util')
+strictEqual(hooked[1], 'os')

package/test/register/v18.19-include-message-port.mjs

@@ -0,0 +1,14 @@
+import { spawnSync } from 'child_process'
+
+const out = spawnSync(process.execPath,
+  ['--import', './test/fixtures/import.mjs', './test/fixtures/import-after.mjs'],
+  { stdio: 'inherit', env: {} }
+)
+
+if (out.error) {
+  console.error(out.error)
+}
+if (out.status !== 0) {
+  console.error(`Expected exit code 0, got ${out.status}`)
+}
+process.exit(out.status)