Skip to content

Commit 1d91a72

Browse files
joyeecheungaduh95
authored andcommitted
doc,module: add missing doc for syncHooks.deregister()
PR-URL: #61959 Reviewed-By: Geoffrey Booth <webadmin@geoffreybooth.com> Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
1 parent 975dafb commit 1d91a72

File tree

1 file changed

+64
-1
lines changed

1 file changed

+64
-1
lines changed

doc/api/module.md

Lines changed: 64 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -234,9 +234,14 @@ changes:
234234
* `options` {Object}
235235
* `load` {Function|undefined} See [load hook][]. **Default:** `undefined`.
236236
* `resolve` {Function|undefined} See [resolve hook][]. **Default:** `undefined`.
237+
* Returns: {Object} An object with the following property:
238+
* `deregister()` {Function} Remove the registered hooks so that they are no
239+
longer called. Hooks are otherwise retained for the lifetime of the running
240+
process.
237241
238242
Register [hooks][] that customize Node.js module resolution and loading behavior.
239-
See [Customization hooks][].
243+
See [Customization hooks][]. The returned object can be used to
244+
[deregister the hooks][deregistration of synchronous customization hooks].
240245
241246
### `module.stripTypeScriptTypes(code[, options])`
242247
@@ -798,6 +803,63 @@ hook to signal that the chain is intentionally ending at your hook.
798803
If a hook should be applied when loading other hook modules, the other hook
799804
modules should be loaded after the hook is registered.
800805
806+
#### Deregistration of synchronous customization hooks
807+
808+
The object returned by `registerHooks()` has a `deregister()` method that can be
809+
used to remove the hooks from the chain. Once `deregister()` is called, the hooks
810+
will no longer be invoked during module resolution or loading.
811+
812+
This is currently only available for synchronous hooks registered via `registerHooks()`, not for asynchronous
813+
hooks registered via `module.register()`.
814+
815+
```mjs
816+
import { registerHooks } from 'node:module';
817+
818+
const hooks = registerHooks({
819+
resolve(specifier, context, nextResolve) {
820+
console.log('resolve hook called for', specifier);
821+
return nextResolve(specifier, context);
822+
},
823+
load(url, context, nextLoad) {
824+
return nextLoad(url, context);
825+
},
826+
});
827+
828+
// At this point, the hooks are active and will be called for
829+
// any subsequent import() or require() calls.
830+
await import('./my-module.mjs');
831+
832+
// Later, remove the hooks from the chain.
833+
hooks.deregister();
834+
835+
// Subsequent loads will no longer trigger the hooks.
836+
await import('./another-module.mjs');
837+
```
838+
839+
```cjs
840+
const { registerHooks } = require('node:module');
841+
842+
const hooks = registerHooks({
843+
resolve(specifier, context, nextResolve) {
844+
console.log('resolve hook called for', specifier);
845+
return nextResolve(specifier, context);
846+
},
847+
load(url, context, nextLoad) {
848+
return nextLoad(url, context);
849+
},
850+
});
851+
852+
// At this point, the hooks are active and will be called for
853+
// any subsequent require() calls.
854+
require('./my-module.cjs');
855+
856+
// Later, remove the hooks from the chain.
857+
hooks.deregister();
858+
859+
// Subsequent loads will no longer trigger the hooks.
860+
require('./another-module.cjs');
861+
```
862+
801863
#### Hook functions accepted by `module.registerHooks()`
802864
803865
<!-- YAML
@@ -2029,6 +2091,7 @@ returned object contains the following keys:
20292091
[asynchronous `resolve` hook]: #asynchronous-resolvespecifier-context-nextresolve
20302092
[asynchronous hook functions]: #asynchronous-hooks-accepted-by-moduleregister
20312093
[caveats of asynchronous customization hooks]: #caveats-of-asynchronous-customization-hooks
2094+
[deregistration of synchronous customization hooks]: #deregistration-of-synchronous-customization-hooks
20322095
[hooks]: #customization-hooks
20332096
[load hook]: #synchronous-loadurl-context-nextload
20342097
[module compile cache]: #module-compile-cache

0 commit comments

Comments
 (0)