Skip to content

Commit

Permalink
update ESM doc (remove globalPreload section
Browse files Browse the repository at this point in the history
  • Loading branch information
JakobJingleheimer committed Aug 20, 2023
1 parent c9a86ea commit 019b61b
Showing 1 changed file with 6 additions and 75 deletions.
81 changes: 6 additions & 75 deletions doc/api/esm.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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()`
<!-- YAML
changes:
- version:
- v18.6.0
- v16.17.0
pr-url: https://github.com/nodejs/node/pull/42623
description: Add support for chaining globalPreload hooks.
-->
> 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() + '/<preload>');
// [...]
`;
}
```
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
Expand Down

0 comments on commit 019b61b

Please sign in to comment.