Skip to content

Commit cb05e4d

Browse files
module: remove async module customization hooks
Remove `module.register()` (DEP0205), the `--experimental-loader` and `--loader` flags, and the machinery that supported them: the loader hooks worker thread, the hooks proxy, the async module customization hook chains for resolving and loading, the internal worker class used to run the loader thread, and the asynchronous module job linking. Module customization is now provided only by `module.registerHooks()`, which runs synchronously on the thread that loads the modules. As the loader thread no longer exists, the ES module loader always loads and links modules synchronously, so the code that handled promises and the re-invented `require()` for imported CommonJS customized by the async module customization hooks is removed too. `import()` still defers evaluation of the module to a later microtask, as before. `worker_threads.isInternalThread` is kept for compatibility and is now always `false`; removing it is left for a future semver-major change. The `ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED` and `ERR_LOADER_CHAIN_INCOMPLETE` error codes are no longer used and are documented as removed. Tests that exist only to exercise the async module customization hooks are removed. Assisted-by: Claude Signed-off-by: Geoffrey Booth <webadmin@geoffreybooth.com> PR-URL: #67090 Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Ilyas Shabi <ilyasshabi94@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Jacob Smith <jacob@frende.me>
1 parent dd23cd2 commit cb05e4d

259 files changed

Lines changed: 263 additions & 7877 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎doc/api/cli.md‎

Lines changed: 0 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1535,33 +1535,6 @@ added:
15351535
15361536
Enable experimental support for inspector network resources.
15371537

1538-
### `--experimental-loader=module`
1539-
1540-
<!-- YAML
1541-
added: v8.8.0
1542-
changes:
1543-
- version:
1544-
- v23.6.1
1545-
- v22.13.1
1546-
- v20.18.2
1547-
pr-url: https://github.com/nodejs-private/node-private/pull/629
1548-
description: Using this feature with the permission model enabled requires
1549-
passing `--allow-worker`.
1550-
- version: v12.11.1
1551-
pr-url: https://github.com/nodejs/node/pull/29752
1552-
description: This flag was renamed from `--loader` to
1553-
`--experimental-loader`.
1554-
-->
1555-
1556-
> This flag is discouraged and may be removed in a future version of Node.js.
1557-
> Please use
1558-
> [`--import` with `register()`][preloading asynchronous module customization hooks] instead.
1559-
1560-
Specify the `module` containing exported [asynchronous module customization hooks][].
1561-
`module` may be any string accepted as an [`import` specifier][].
1562-
1563-
This feature requires `--allow-worker` if used with the [Permission Model][].
1564-
15651538
### `--experimental-network-inspection`
15661539

15671540
<!-- YAML
@@ -4340,7 +4313,6 @@ one is included in the list below.
43404313
* `--experimental-import-meta-resolve`
43414314
* `--experimental-import-text`
43424315
* `--experimental-json-modules`
4343-
* `--experimental-loader`
43444316
* `--experimental-modules`
43454317
* `--experimental-package-map`
43464318
* `--experimental-print-required-tla`
@@ -5024,7 +4996,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
50244996
[`dns.setDefaultResultOrder()`]: dns.md#dnssetdefaultresultorderorder
50254997
[`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
50264998
[`import.meta.url`]: esm.md#importmetaurl
5027-
[`import` specifier]: esm.md#import-specifiers
50284999
[`inspector.open()`]: inspector.md#inspectoropenport-host-wait
50295000
[`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
50305001
[`node:ffi`]: ffi.md
@@ -5041,7 +5012,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
50415012
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
50425013
[`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
50435014
[`vfs.mount()`]: vfs.md#vfsmount
5044-
[asynchronous module customization hooks]: module.md#asynchronous-customization-hooks
50455015
[benchmark runner]: bench.md#command-line-runner
50465016
[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
50475017
[collecting code coverage from tests]: test.md#collecting-code-coverage
@@ -5059,7 +5029,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
50595029
[jitless]: https://v8.dev/blog/jitless
50605030
[libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html
50615031
[module compile cache]: module.md#module-compile-cache
5062-
[preloading asynchronous module customization hooks]: module.md#registration-of-asynchronous-customization-hooks
50635032
[randomizing tests execution order]: test.md#randomizing-tests-execution-order
50645033
[remote code execution]: https://www.owasp.org/index.php/Code_Injection
50655034
[running tests from the command line]: test.md#running-tests-from-the-command-line

‎doc/api/deprecations.md‎

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4615,6 +4615,9 @@ no longer supported.
46154615
46164616
<!-- YAML
46174617
changes:
4618+
- version: REPLACEME
4619+
pr-url: https://github.com/nodejs/node/pull/67090
4620+
description: End-of-Life.
46184621
- version: v26.0.0
46194622
pr-url: https://github.com/nodejs/node/pull/62401
46204623
description: Runtime deprecation.
@@ -4625,18 +4628,18 @@ changes:
46254628
description: Documentation-only deprecation.
46264629
-->
46274630
4628-
Type: Runtime
4631+
Type: End-of-Life
46294632
4630-
[`module.register()`][] is deprecated. Use [`module.registerHooks()`][]
4631-
instead.
4633+
The `module.register()` API and the `--experimental-loader` and `--loader`
4634+
flags have been removed. Use [`module.registerHooks()`][] instead.
46324635
4633-
The `module.register()` API provides off-thread async hooks for customizing ES modules;
4634-
the `module.registerHooks()` API provides similar hooks that are synchronous, in-thread, and
4635-
work for all types of modules.
4636-
Supporting async hooks has proven to be complex, involving worker threads orchestration, and there are issues
4637-
that have proven unresolvable. See [caveats of asynchronous customization hooks][]. Please migrate to
4638-
`module.registerHooks()` as soon as possible as `module.register()` will be
4639-
removed in a future version of Node.js.
4636+
The `module.register()` API provided off-thread async module customization
4637+
hooks for customizing ES modules. The `module.registerHooks()` API provides
4638+
similar hooks that are synchronous, in-thread and work for all types of modules.
4639+
To continue running async module customization off-thread, users can spawn their
4640+
own threads to run the async customizations, communicate from the in-thread
4641+
synchronous hooks and block for the results on the main thread, similar to how
4642+
`module.register()` worked internally.
46404643
46414644
### DEP0206: Calling `digest()` on an already-finalized `Hmac` instance
46424645
@@ -4935,7 +4938,6 @@ Type: Documentation-only
49354938
[`message.trailersDistinct`]: http.md#messagetrailersdistinct
49364939
[`message.trailers`]: http.md#messagetrailers
49374940
[`module.createRequire()`]: module.md#modulecreaterequirefilename
4938-
[`module.register()`]: module.md#moduleregisterspecifier-parenturl-options
49394941
[`module.registerHooks()`]: module.md#moduleregisterhooksoptions
49404942
[`os.networkInterfaces()`]: os.md#osnetworkinterfaces
49414943
[`os.tmpdir()`]: os.md#ostmpdir
@@ -4991,7 +4993,6 @@ Type: Documentation-only
49914993
[`zlib.bytesWritten`]: zlib.md#zlibbyteswritten
49924994
[alloc]: buffer.md#static-method-bufferallocsize-fill-encoding
49934995
[alloc_unsafe_size]: buffer.md#static-method-bufferallocunsafesize-alignment
4994-
[caveats of asynchronous customization hooks]: module.md#caveats-of-asynchronous-customization-hooks
49954996
[from_arraybuffer]: buffer.md#static-method-bufferfromarraybuffer-byteoffset-length
49964997
[from_string_encoding]: buffer.md#static-method-bufferfromstring-encoding
49974998
[legacy URL API]: url.md#legacy-url-api

‎doc/api/errors.md‎

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -733,13 +733,6 @@ by the `node:assert` module.
733733
An attempt was made to register something that is not a function as an
734734
`AsyncHooks` callback.
735735

736-
<a id="ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED"></a>
737-
738-
### `ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED`
739-
740-
An operation related to module loading is customized by an asynchronous loader
741-
hook that never settled the promise before the loader thread exits.
742-
743736
<a id="ERR_ASYNC_RESOURCE_DOMAIN_REMOVED"></a>
744737

745738
### `ERR_ASYNC_RESOURCE_DOMAIN_REMOVED`
@@ -2364,19 +2357,6 @@ for more information.
23642357

23652358
IP is blocked by `net.BlockList`.
23662359

2367-
<a id="ERR_LOADER_CHAIN_INCOMPLETE"></a>
2368-
2369-
### `ERR_LOADER_CHAIN_INCOMPLETE`
2370-
2371-
<!-- YAML
2372-
added:
2373-
- v18.6.0
2374-
- v16.17.0
2375-
-->
2376-
2377-
An ESM loader hook returned without calling `next()` and without explicitly
2378-
signaling a short circuit.
2379-
23802360
<a id="ERR_LOAD_SQLITE_EXTENSION"></a>
23812361

23822362
### `ERR_LOAD_SQLITE_EXTENSION`
@@ -3936,6 +3916,17 @@ attempting a [`require()`][] operation or when loading the program entry point.
39363916
> Stability: 0 - Deprecated. These error codes are either inconsistent, or have
39373917
> been removed.
39383918
3919+
<a id="ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED"></a>
3920+
3921+
### `ERR_ASYNC_LOADER_REQUEST_NEVER_SETTLED`
3922+
3923+
<!-- YAML
3924+
removed: REPLACEME
3925+
-->
3926+
3927+
An operation related to module loading is customized by an asynchronous loader
3928+
hook that never settled the promise before the loader thread exits.
3929+
39393930
<a id="ERR_CANNOT_TRANSFER_OBJECT"></a>
39403931

39413932
### `ERR_CANNOT_TRANSFER_OBJECT`
@@ -4174,6 +4165,20 @@ changes:
41744165

41754166
An invalid transfer object was passed to `postMessage()`.
41764167

4168+
<a id="ERR_LOADER_CHAIN_INCOMPLETE"></a>
4169+
4170+
### `ERR_LOADER_CHAIN_INCOMPLETE`
4171+
4172+
<!-- YAML
4173+
added:
4174+
- v18.6.0
4175+
- v16.17.0
4176+
removed: REPLACEME
4177+
-->
4178+
4179+
An ESM loader hook returned without calling `next()` and without explicitly
4180+
signaling a short circuit.
4181+
41774182
<a id="ERR_MANIFEST_ASSERT_INTEGRITY"></a>
41784183

41794184
### `ERR_MANIFEST_ASSERT_INTEGRITY`

‎doc/api/esm.md‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -199,8 +199,7 @@ ES modules are resolved and cached as URLs. This means that special characters
199199
must be [percent-encoded][], such as `#` with `%23` and `?` with `%3F`.
200200

201201
`file:`, `node:`, and `data:` URL schemes are supported. A specifier like
202-
`'https://example.com/app.js'` is not supported natively in Node.js unless using
203-
a [custom HTTPS loader][].
202+
`'https://example.com/app.js'` is not supported natively in Node.js.
204203

205204
#### `file:` URLs
206205

@@ -493,8 +492,6 @@ resolutions are subject to the permitted exports resolutions within the package.
493492
494493
* This can result in synchronous file-system operations, which
495494
can impact performance similarly to `require.resolve`.
496-
* This feature is not available within custom loaders (it would
497-
create a deadlock).
498495
499496
**Non-standard API**:
500497
@@ -1316,8 +1313,8 @@ _isImports_, _conditions_)
13161313
### Customizing ESM specifier resolution algorithm
13171314
13181315
[Module customization hooks][] provide a mechanism for customizing the ESM
1319-
specifier resolution algorithm. An example that provides CommonJS-style
1320-
resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
1316+
specifier resolution algorithm, for example to provide CommonJS-style
1317+
resolution for ESM specifiers.
13211318
13221319
<!-- Note: The merve link should be kept in-sync with the deps version -->
13231320
@@ -1360,8 +1357,6 @@ resolution for ESM specifiers is [commonjs-extension-resolution-loader][].
13601357
[`process.dlopen`]: process.md#processdlopenmodule-filename-flags
13611358
[`require(esm)`]: modules.md#loading-ecmascript-modules-using-require
13621359
[`url.fileURLToPath()`]: url.md#urlfileurltopathurl-options
1363-
[commonjs-extension-resolution-loader]: https://github.com/nodejs/loaders-test/tree/main/commonjs-extension-resolution-loader
1364-
[custom https loader]: module.md#import-from-https
13651360
[import.meta.resolve]: #importmetaresolvespecifier
13661361
[merve]: https://github.com/anonrig/merve/tree/v1.0.0
13671362
[percent-encoded]: url.md#percent-encoding-in-urls

0 commit comments

Comments
 (0)