Skip to content

Commit 7f78002

Browse files
joyeecheungnodejs-github-bot
authored andcommitted
doc: reorganize docs of module customization hooks
This reorganizes the documentation of module customization hooks to promote the synchronous variant as it has fewer caveats. Previously the documentation was organized as follows: To do something: 1. For asynchronous hooks, do this, which may have these caveats 2. For synchronous hooks, do this, which does not have the caveats To do something else: 1. For asynchronous hooks, do this, which may have these caveats 2. For synchronous hooks, do this, which does not have the caveats It's now organized as follows: Synchronous hooks: To do something, do this. To do something else, do this. (No mention that it doesn't have caveats, because users are not supposed to burden themselves with caveats in the other API that they do not use). Asynchronous hooks: They have these caveats, if they are too complex to deal with, consider use the synchronous variant. To do something, do this, which may have these caveats. To do something, do this, which may have these caveats. PR-URL: #60960 Refs: #56241 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com>
1 parent 81e05e1 commit 7f78002

File tree

2 files changed

+505
-335
lines changed

2 files changed

+505
-335
lines changed

doc/api/cli.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1190,9 +1190,9 @@ changes:
11901190

11911191
> This flag is discouraged and may be removed in a future version of Node.js.
11921192
> Please use
1193-
> [`--import` with `register()`][module customization hooks: enabling] instead.
1193+
> [`--import` with `register()`][preloading asynchronous module customization hooks] instead.
11941194
1195-
Specify the `module` containing exported [module customization hooks][].
1195+
Specify the `module` containing exported [asynchronous module customization hooks][].
11961196
`module` may be any string accepted as an [`import` specifier][].
11971197

11981198
This feature requires `--allow-worker` if used with the [Permission Model][].
@@ -4158,8 +4158,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
41584158
[ExperimentalWarning: `vm.measureMemory` is an experimental feature]: vm.md#vmmeasurememoryoptions
41594159
[File System Permissions]: permissions.md#file-system-permissions
41604160
[Loading ECMAScript modules using `require()`]: modules.md#loading-ecmascript-modules-using-require
4161-
[Module customization hooks]: module.md#customization-hooks
4162-
[Module customization hooks: enabling]: module.md#enabling
41634161
[Module resolution and loading]: packages.md#module-resolution-and-loading
41644162
[Navigator API]: globals.md#navigator
41654163
[Node.js issue tracker]: https://github.com/nodejs/node/issues
@@ -4222,6 +4220,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
42224220
[`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data
42234221
[`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
42244222
[`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
4223+
[asynchronous module customization hooks]: module.md#asynchronous-customization-hooks
42254224
[captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24
42264225
[collecting code coverage from tests]: test.md#collecting-code-coverage
42274226
[conditional exports]: packages.md#conditional-exports
@@ -4236,6 +4235,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
42364235
[jitless]: https://v8.dev/blog/jitless
42374236
[libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html
42384237
[module compile cache]: module.md#module-compile-cache
4238+
[preloading asynchronous module customization hooks]: module.md#registration-of-asynchronous-customization-hooks
42394239
[remote code execution]: https://www.owasp.org/index.php/Code_Injection
42404240
[running tests from the command line]: test.md#running-tests-from-the-command-line
42414241
[scavenge garbage collector]: https://v8.dev/blog/orinoco-parallel-scavenger

0 commit comments

Comments
 (0)