process: add process.getBuiltinModule(id)

`process.getBuiltinModule(id)` provides a way to load built-in modules
in a globally available function. ES Modules that need to support
other environments can use it to conditionally load a Node.js built-in
when it is run in Node.js, without having to deal with the resolution
error that can be thrown by `import` in a non-Node.js environment or
having to use dynamic `import()` which either turns the module into an
asynchronous module, or turns a synchronous API into an asynchronous
one.

```mjs
if (globalThis.process.getBuiltinModule) {
  // Run in Node.js, use the Node.js fs module.
  const fs = globalThis.process.getBuiltinModule('fs');
  // If `require()` is needed to load user-modules, use
  // createRequire()
  const module = globalThis.process.getBuiltinModule('module');
  const require = module.createRequire(import.meta.url);
  const foo = require('foo');
}
```

If `id` specifies a built-in module available in the current Node.js
process, `process.getBuiltinModule(id)` method returns the
corresponding built-in module. If `id` does not correspond to any
built-in module, `undefined` is returned.

`process.getBuiltinModule(id)` accept built-in module IDs that are
recognized by `module.isBuiltin(id)`. Some built-in modules must be
loaded with the `node:` prefix.

The built-in modules returned by `process.getBuiltinModule(id)` are
always the original modules - that is, it's not affected by
`require.cache`.

PR-URL: nodejs#52762
Fixes: nodejs#52599
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Chengzhong Wu <[email protected]>
Reviewed-By: Rafael Gonzaga <[email protected]>
Reviewed-By: Marco Ippolito <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Zijian Liu <[email protected]>
Reviewed-By: Geoffrey Booth <[email protected]>
Reviewed-By: Mohammed Keyvanzadeh <[email protected]>

doc/api/process.md

@@ -1921,6 +1921,46 @@ console.log('After:', getActiveResourcesInfo());
 //   After: [ 'TTYWrap', 'TTYWrap', 'TTYWrap', 'Timeout' ]
 ```
 
+## `process.getBuiltinModule(id)`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* `id` {string} ID of the built-in module being requested.
+* Returns: {Object|undefined}
+
+`process.getBuiltinModule(id)` provides a way to load built-in modules
+in a globally available function. ES Modules that need to support
+other environments can use it to conditionally load a Node.js built-in
+when it is run in Node.js, without having to deal with the resolution
+error that can be thrown by `import` in a non-Node.js environment or
+having to use dynamic `import()` which either turns the module into
+an asynchronous module, or turns a synchronous API into an asynchronous one.
+
+```mjs
+if (globalThis.process?.getBuiltinModule) {
+  // Run in Node.js, use the Node.js fs module.
+  const fs = globalThis.process.getBuiltinModule('fs');
+  // If `require()` is needed to load user-modules, use createRequire()
+  const module = globalThis.process.getBuiltinModule('module');
+  const require = module.createRequire(import.meta.url);
+  const foo = require('foo');
+}
+```
+
+If `id` specifies a built-in module available in the current Node.js process,
+`process.getBuiltinModule(id)` method returns the corresponding built-in
+module. If `id` does not correspond to any built-in module, `undefined`
+is returned.
+
+`process.getBuiltinModule(id)` accepts built-in module IDs that are recognized
+by [`module.isBuiltin(id)`][]. Some built-in modules must be loaded with the
+`node:` prefix, see [built-in modules with mandatory `node:` prefix][].
+The references returned by `process.getBuiltinModule(id)` always point to
+the built-in module corresponding to `id` even if users modify
+[`require.cache`][] so that `require(id)` returns something else.
+
 ## `process.getegid()`
 
 <!-- YAML
@@ -4024,6 +4064,7 @@ cases:
 [`console.error()`]: console.md#consoleerrordata-args
 [`console.log()`]: console.md#consolelogdata-args
 [`domain`]: domain.md
+[`module.isBuiltin(id)`]: module.md#moduleisbuiltinmodulename
 [`net.Server`]: net.md#class-netserver
 [`net.Socket`]: net.md#class-netsocket
 [`os.constants.dlopen`]: os.md#dlopen-constants
@@ -4040,9 +4081,11 @@ cases:
 [`queueMicrotask()`]: globals.md#queuemicrotaskcallback
 [`readable.read()`]: stream.md#readablereadsize
 [`require()`]: globals.md#require
+[`require.cache`]: modules.md#requirecache
 [`require.main`]: modules.md#accessing-the-main-module
 [`subprocess.kill()`]: child_process.md#subprocesskillsignal
 [`v8.setFlagsFromString()`]: v8.md#v8setflagsfromstringflags
+[built-in modules with mandatory `node:` prefix]: modules.md#built-in-modules-with-mandatory-node-prefix
 [debugger]: debugger.md
 [deprecation code]: deprecations.md
 [note on process I/O]: #a-note-on-process-io

lib/internal/bootstrap/node.js

@@ -352,6 +352,11 @@ internalBinding('process_methods').setEmitWarningSync(emitWarningSync);
   setMaybeCacheGeneratedSourceMap(maybeCacheGeneratedSourceMap);
 }
 
+{
+  const { getBuiltinModule } = require('internal/modules/helpers');
+  process.getBuiltinModule = getBuiltinModule;
+}
+
 function setupProcessObject() {
   const EventEmitter = require('events');
   const origProcProto = ObjectGetPrototypeOf(process);

lib/internal/modules/helpers.js

@@ -285,8 +285,22 @@ let _hasStartedUserCJSExecution = false;
 // there is little value checking whether any user JS code is run anyway.
 let _hasStartedUserESMExecution = false;
 
+/**
+ * Load a public built-in module. ID may or may not be prefixed by `node:` and
+ * will be normalized.
+ * @param {string} id ID of the built-in to be loaded.
+ * @returns {object|undefined} exports of the built-in. Undefined if the built-in
+ * does not exist.
+ */
+function getBuiltinModule(id) {
+  validateString(id, 'id');
+  const normalizedId = BuiltinModule.normalizeRequirableId(id);
+  return normalizedId ? require(normalizedId) : undefined;
+}
+
 module.exports = {
   addBuiltinLibsToObject,
+  getBuiltinModule,
   getCjsConditions,
   initializeCjsConditions,
   loadBuiltinModule,

test/common/index.mjs

@@ -18,6 +18,7 @@ const {
   getCallSite,
   getTTYfd,
   hasCrypto,
+  hasIntl,
   hasIPv6,
   hasMultiLocalhost,
   isAIX,
@@ -73,6 +74,7 @@ export {
   getPort,
   getTTYfd,
   hasCrypto,
+  hasIntl,
   hasIPv6,
   hasMultiLocalhost,
   isAIX,

test/parallel/test-process-get-builtin.mjs

@@ -0,0 +1,55 @@
+import { isMainThread, hasCrypto, hasIntl } from '../common/index.mjs';
+import assert from 'node:assert';
+import { builtinModules } from 'node:module';
+
+for (const invalid of [1, undefined, null, false, [], {}, () => {}, Symbol('test')]) {
+  assert.throws(() => process.getBuiltinModule(invalid), { code: 'ERR_INVALID_ARG_TYPE' });
+}
+
+for (const invalid of [
+  'invalid', 'test', 'sea', 'test/reporter', 'internal/bootstrap/realm',
+  'internal/deps/undici/undici', 'internal/util',
+]) {
+  assert.strictEqual(process.getBuiltinModule(invalid), undefined);
+}
+
+// Check that createRequire()(id) returns the same thing as process.getBuiltinModule(id).
+const require = process.getBuiltinModule('module').createRequire(import.meta.url);
+const publicBuiltins = new Set(builtinModules);
+
+// Remove built-ins not available in the current setup.
+if (!isMainThread) {
+  publicBuiltins.delete('trace_events');
+}
+if (!hasCrypto) {
+  publicBuiltins.delete('crypto');
+  publicBuiltins.delete('tls');
+  publicBuiltins.delete('_tls_common');
+  publicBuiltins.delete('_tls_wrap');
+  publicBuiltins.delete('http2');
+  publicBuiltins.delete('https');
+  publicBuiltins.delete('inspector');
+  publicBuiltins.delete('inspector/promises');
+}
+if (!hasIntl) {
+  publicBuiltins.delete('inspector');
+  publicBuiltins.delete('trace_events');
+}
+
+for (const id of publicBuiltins) {
+  assert.strictEqual(process.getBuiltinModule(id), require(id));
+}
+// Check that import(id).default returns the same thing as process.getBuiltinModule(id).
+for (const id of publicBuiltins) {
+  const imported = await import(`node:${id}`);
+  assert.strictEqual(process.getBuiltinModule(id), imported.default);
+}
+
+// publicBuiltins does not include 'test' which requires the node: prefix.
+const ids = publicBuiltins.add('test');
+// Check that import(id).default returns the same thing as process.getBuiltinModule(id).
+for (const id of ids) {
+  const prefixed = `node:${id}`;
+  const imported = await import(prefixed);
+  assert.strictEqual(process.getBuiltinModule(prefixed), imported.default);
+}