diff --git a/doc/api/esm.md b/doc/api/esm.md index 459f87771815cc..b587c233cf3785 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -142,6 +142,25 @@ provided via a `--loader ./loader-name.mjs` argument to Node.js. When hooks are used they only apply to ES module loading and not to any CommonJS modules loaded. +### Hook Context + +This context contains access to functions that are scoped to the current load +process. + +A hook context consists of the following properties: + +- `defaultResolve` {Function} A shortcut to the resolve algorithm that ships + with Node.js. + - `specifier` {string} The specifier of the module to import. + - `parentURL` {string} The URL of the module that requested the specifier. +- `resolve` {Function} A shortcut to the current resolve function. Especially + useful if resolve is not hooked. + - `specifier` {string} The specifier of the module to import. + - `parentURL` {string} The URL of the module that requested the specifier. +- `vmModuleLinkHook` {object} This value can be passed to [`module.link`][] to + allow linking the import requests of a [`vm.Module`][] instance to the + loader. + ### Resolve hook The resolve hook returns the resolved file URL and module format for a @@ -153,7 +172,7 @@ baseURL.pathname = `${process.cwd()}/`; export async function resolve(specifier, parentModuleURL = baseURL, - defaultResolver) { + hookContext) { return { url: new URL(specifier, parentModuleURL).href, format: 'esm' @@ -195,7 +214,7 @@ const JS_EXTENSIONS = new Set(['.js', '.mjs']); const baseURL = new URL('file://'); baseURL.pathname = `${process.cwd()}/`; -export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) { +export function resolve(specifier, parentModuleURL = baseURL, hookContext) { if (builtins.includes(specifier)) { return { url: specifier, @@ -204,7 +223,7 @@ export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) { } if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) { // For node_modules support: - // return defaultResolve(specifier, parentModuleURL); + // return hookContext.defaultResolve(specifier, parentModuleURL); throw new Error( `imports must begin with '/', './', or '../'; '${specifier}' does not`); } @@ -238,7 +257,7 @@ This hook is called only for modules that return `format: 'dynamic'` from the `resolve` hook. ```js -export async function dynamicInstantiate(url) { +export async function dynamicInstantiate(url, hookContext) { return { exports: ['customExportName'], execute: (exports) => { @@ -253,6 +272,8 @@ With the list of module exports provided upfront, the `execute` function will then be called at the exact point of module evaluation order for that module in the import tree. +[`module.link`]: vm.html#vm_module_link_linker +[`vm.Module`]: vm.html#vm_class_vm_module [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md [addons]: addons.html [dynamic instantiate hook]: #esm_dynamic_instantiate_hook diff --git a/doc/api/vm.md b/doc/api/vm.md index cc9b3135381dad..f434f457c7bb20 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -395,6 +395,8 @@ that point all modules would have been fully linked already, the [HostResolveImportedModule][] implementation is fully synchronous per specification. +The linker may also be passed from [`hookContext.vmModuleLinkhook`][]. + ## Class: vm.Script