Commit a0adc6a
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 2cf963d commit a0adc6a
2 files changed
Lines changed: 505 additions & 335 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1106,9 +1106,9 @@ changes: | |||
| 1106 | 1106 | ||
| 1107 | 1107 | > This flag is discouraged and may be removed in a future version of Node.js. | |
| 1108 | 1108 | > Please use | |
| 1109 | - > [`--import` with `register()`][module customization hooks: enabling] instead. | ||
| 1109 | + > [`--import` with `register()`][preloading asynchronous module customization hooks] instead. | ||
| 1110 | 1110 | ||
| 1111 | - Specify the `module` containing exported [module customization hooks][]. | ||
| 1111 | + Specify the `module` containing exported [asynchronous module customization hooks][]. | ||
| 1112 | 1112 | `module` may be any string accepted as an [`import` specifier][]. | |
| 1113 | 1113 | ||
| 1114 | 1114 | This feature requires `--allow-worker` if used with the [Permission Model][]. | |
@@ -4030,8 +4030,6 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 | |||
| 4030 | 4030 | [ExperimentalWarning: `vm.measureMemory` is an experimental feature]: vm.md#vmmeasurememoryoptions | |
| 4031 | 4031 | [File System Permissions]: permissions.md#file-system-permissions | |
| 4032 | 4032 | [Loading ECMAScript modules using `require()`]: modules.md#loading-ecmascript-modules-using-require | |
| 4033 | - [Module customization hooks]: module.md#customization-hooks | ||
| 4034 | - [Module customization hooks: enabling]: module.md#enabling | ||
| 4035 | 4033 | [Module resolution and loading]: packages.md#module-resolution-and-loading | |
| 4036 | 4034 | [Navigator API]: globals.md#navigator | |
| 4037 | 4035 | [Node.js issue tracker]: https://github.com/nodejs/node/issues | |
@@ -4094,6 +4092,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 | |||
| 4094 | 4092 | [`v8.startupSnapshot.addDeserializeCallback()`]: v8.md#v8startupsnapshotadddeserializecallbackcallback-data | |
| 4095 | 4093 | [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data | |
| 4096 | 4094 | [`v8.startupSnapshot` API]: v8.md#startup-snapshot-api | |
| 4095 | + [asynchronous module customization hooks]: module.md#asynchronous-customization-hooks | ||
| 4097 | 4096 | [captured by the built-in snapshot of Node.js]: https://github.com/nodejs/node/blob/b19525a33cc84033af4addd0f80acd4dc33ce0cf/test/parallel/test-bootstrap-modules.js#L24 | |
| 4098 | 4097 | [collecting code coverage from tests]: test.md#collecting-code-coverage | |
| 4099 | 4098 | [conditional exports]: packages.md#conditional-exports | |
@@ -4108,6 +4107,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12 | |||
| 4108 | 4107 | [jitless]: https://v8.dev/blog/jitless | |
| 4109 | 4108 | [libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html | |
| 4110 | 4109 | [module compile cache]: module.md#module-compile-cache | |
| 4110 | + [preloading asynchronous module customization hooks]: module.md#registration-of-asynchronous-customization-hooks | ||
| 4111 | 4111 | [remote code execution]: https://www.owasp.org/index.php/Code_Injection | |
| 4112 | 4112 | [running tests from the command line]: test.md#running-tests-from-the-command-line | |
| 4113 | 4113 | [scavenge garbage collector]: https://v8.dev/blog/orinoco-parallel-scavenger | |
0 commit comments