Commit 1d91a72
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
1 file changed
Lines changed: 64 additions & 1 deletion
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -234,9 +234,14 @@ changes: | |||
| 234 | 234 | * `options` {Object} | |
| 235 | 235 | * `load` {Function|undefined} See [load hook][]. **Default:** `undefined`. | |
| 236 | 236 | * `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. | ||
| 237 | 241 | ||
| 238 | 242 | 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]. | ||
| 240 | 245 | ||
| 241 | 246 | ### `module.stripTypeScriptTypes(code[, options])` | |
| 242 | 247 | ||
@@ -798,6 +803,63 @@ hook to signal that the chain is intentionally ending at your hook. | |||
| 798 | 803 | If a hook should be applied when loading other hook modules, the other hook | |
| 799 | 804 | modules should be loaded after the hook is registered. | |
| 800 | 805 | ||
| 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 | + | ||
| 801 | 863 | #### Hook functions accepted by `module.registerHooks()` | |
| 802 | 864 | ||
| 803 | 865 | <!-- YAML | |
@@ -2029,6 +2091,7 @@ returned object contains the following keys: | |||
| 2029 | 2091 | [asynchronous `resolve` hook]: #asynchronous-resolvespecifier-context-nextresolve | |
| 2030 | 2092 | [asynchronous hook functions]: #asynchronous-hooks-accepted-by-moduleregister | |
| 2031 | 2093 | [caveats of asynchronous customization hooks]: #caveats-of-asynchronous-customization-hooks | |
| 2094 | + [deregistration of synchronous customization hooks]: #deregistration-of-synchronous-customization-hooks | ||
| 2032 | 2095 | [hooks]: #customization-hooks | |
| 2033 | 2096 | [load hook]: #synchronous-loadurl-context-nextload | |
| 2034 | 2097 | [module compile cache]: #module-compile-cache | |
0 commit comments