Skip to content

Commit

Permalink
process: add process.getBuiltinModule(id)
Browse files Browse the repository at this point in the history
`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: #52762
Fixes: #52599
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
Reviewed-By: Zijian Liu <lxxyxzj@gmail.com>
Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com>
  • Loading branch information
joyeecheung authored and marco-ippolito committed Jul 19, 2024
1 parent a8601ef commit 67333a5
Show file tree
Hide file tree
Showing 5 changed files with 119 additions and 0 deletions.
43 changes: 43 additions & 0 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -1917,6 +1917,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
Expand Down Expand Up @@ -4016,6 +4056,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
Expand All @@ -4032,9 +4073,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
Expand Down
5 changes: 5 additions & 0 deletions lib/internal/bootstrap/node.js
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
14 changes: 14 additions & 0 deletions lib/internal/modules/helpers.js
Original file line number Diff line number Diff line change
Expand Up @@ -332,8 +332,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,
Expand Down
2 changes: 2 additions & 0 deletions test/common/index.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ const {
getCallSite,
getTTYfd,
hasCrypto,
hasIntl,
hasIPv6,
hasMultiLocalhost,
isAIX,
Expand Down Expand Up @@ -72,6 +73,7 @@ export {
getPort,
getTTYfd,
hasCrypto,
hasIntl,
hasIPv6,
hasMultiLocalhost,
isAIX,
Expand Down
55 changes: 55 additions & 0 deletions test/parallel/test-process-get-builtin.mjs
Original file line number Diff line number Diff line change
@@ -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);
}

0 comments on commit 67333a5

Please sign in to comment.