diff --git a/doc/api/esm.md b/doc/api/esm.md index 476d076deb3239..d9476ab9e2b941 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -700,6 +700,9 @@ changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/48842 description: Added `initialize` hook to replace `globalPreload`. + - version: REPLACEME + pr-url: https://github.com/nodejs/node/pull/49144 + description: Removed `globalPreload`. - version: - v18.6.0 - v16.17.0 @@ -775,10 +778,10 @@ This hook can send and receive data from a [`register`][] invocation, including ports and other transferrable objects. The return value of `initialize` must be either: -* `undefined`, +* `undefined` * something that can be posted as a message between threads (e.g. the input to - [`port.postMessage`][]), -* a `Promise` resolving to one of the aforementioned values. + [`port.postMessage`][]) +* a `Promise` resolving to one of the aforementioned values Loader code: @@ -1042,78 +1045,6 @@ export async function load(url, context, nextLoad) { In a more advanced scenario, this can also be used to transform an unsupported source to a supported one (see [Examples](#examples) below). -#### `globalPreload()` - - - -> This hook will be removed in a future version. Use [`initialize`][] instead. -> When a loader has an `initialize` export, `globalPreload` will be ignored. - -> In a previous version of this API, this hook was named -> `getGlobalPreloadCode`. - -* `context` {Object} Information to assist the preload code - * `port` {MessagePort} -* Returns: {string} Code to run before application startup - -Sometimes it might be necessary to run some code inside of the same global -scope that the application runs in. This hook allows the return of a string -that is run as a sloppy-mode script on startup. - -Similar to how CommonJS wrappers work, the code runs in an implicit function -scope. The only argument is a `require`-like function that can be used to load -builtins like "fs": `getBuiltin(request: string)`. - -If the code needs more advanced `require` features, it has to construct -its own `require` using `module.createRequire()`. - -```js -export function globalPreload(context) { - return `\ -globalThis.someInjectedProperty = 42; -console.log('I just set some globals!'); - -const { createRequire } = getBuiltin('module'); -const { cwd } = getBuiltin('process'); - -const require = createRequire(cwd() + '/'); -// [...] -`; -} -``` - -In order to allow communication between the application and the loader, another -argument is provided to the preload code: `port`. This is available as a -parameter to the loader hook and inside of the source text returned by the hook. -Some care must be taken in order to properly call [`port.ref()`][] and -[`port.unref()`][] to prevent a process from being in a state where it won't -close normally. - -```js -/** - * This example has the application context send a message to the loader - * and sends the message back to the application context - */ -export function globalPreload({ port }) { - port.onmessage = (evt) => { - port.postMessage(evt.data); - }; - return `\ - port.postMessage('console.log("I went to the Loader and back");'); - port.onmessage = (evt) => { - eval(evt.data); - }; - `; -} -``` - ### Examples The various loader hooks can be used together to accomplish wide-ranging