Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

module: add hook for global preload code #32068

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
33 changes: 33 additions & 0 deletions doc/api/esm.md
Original file line number Diff line number Diff line change
Expand Up @@ -1188,6 +1188,39 @@ export async function transformSource(source,
}
```

#### <code>getGlobalPreloadCode</code> hook

> Note: The loaders API is being redesigned. This hook may disappear or its
> signature may change. Do not rely on the API described below.

Sometimes it can be necessary to run some code inside of the same global scope
that the application will run in. This hook allows to return a string that will
be ran as 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 will have to construct
its own `require` using `module.createRequire()`.

```js
/**
* @returns {string} Code to run before application startup
*/
export function getGlobalPreloadCode() {
guybedford marked this conversation as resolved.
Show resolved Hide resolved
return `\
globalThis.someInjectedProperty = 42;
console.log('I just set some globals!');

const { createRequire } = getBuiltin('module');

const require = createRequire(process.cwd + '/<preload>');
// [...]
`;
}
```

#### <code>dynamicInstantiate</code> hook

> Note: The loaders API is being redesigned. This hook may disappear or its
Expand Down
51 changes: 50 additions & 1 deletion lib/internal/modules/esm/loader.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const {
} = primordials;

const {
ERR_INVALID_ARG_VALUE,
ERR_INVALID_RETURN_PROPERTY,
ERR_INVALID_RETURN_PROPERTY_VALUE,
ERR_INVALID_RETURN_VALUE,
Expand Down Expand Up @@ -47,6 +48,14 @@ class Loader {
// Map of already-loaded CJS modules to use
this.cjsCache = new SafeMap();

// This hook is called before the first root module is imported. It's a
// function that returns a piece of code that runs as a sloppy-mode script.
// The script may evaluate to a function that can be called with a
// `getBuiltin` helper that can be used to retrieve builtins.
// If the hook returns `null` instead of a source string, it opts out of
// running any preload code.
// The preload code runs as soon as the hook module has finished evaluating.
this._getGlobalPreloadCode = null;
// The resolver has the signature
// (specifier : string, parentURL : string, defaultResolve)
// -> Promise<{ url : string }>
Expand Down Expand Up @@ -168,7 +177,16 @@ class Loader {
return module.getNamespace();
}

hook({ resolve, dynamicInstantiate, getFormat, getSource, transformSource }) {
hook(hooks) {
const {
resolve,
dynamicInstantiate,
getFormat,
getSource,
transformSource,
getGlobalPreloadCode,
GeoffreyBooth marked this conversation as resolved.
Show resolved Hide resolved
} = hooks;

// Use .bind() to avoid giving access to the Loader instance when called.
if (resolve !== undefined)
this._resolve = FunctionPrototypeBind(resolve, null);
Expand All @@ -185,6 +203,37 @@ class Loader {
if (transformSource !== undefined) {
this._transformSource = FunctionPrototypeBind(transformSource, null);
}
if (getGlobalPreloadCode !== undefined) {
this._getGlobalPreloadCode =
FunctionPrototypeBind(getGlobalPreloadCode, null);
}
}

runGlobalPreloadCode() {
if (!this._getGlobalPreloadCode) {
return;
}
const preloadCode = this._getGlobalPreloadCode();
if (preloadCode === null) {
return;
}

if (typeof preloadCode !== 'string') {
throw new ERR_INVALID_RETURN_VALUE(
'string', 'loader getGlobalPreloadCode', preloadCode);
}
const { compileFunction } = require('vm');
const preloadInit = compileFunction(preloadCode, ['getBuiltin'], {
filename: '<preload>',
});
const { NativeModule } = require('internal/bootstrap/loaders');

preloadInit.call(globalThis, (builtinName) => {
if (NativeModule.canBeRequiredByUsers(builtinName)) {
return require(builtinName);
}
throw new ERR_INVALID_ARG_VALUE('builtinName', builtinName);
});
}

async getModuleJob(specifier, parentURL) {
Expand Down
1 change: 1 addition & 0 deletions lib/internal/process/esm_loader.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ async function initializeLoader() {
await ESMLoader.import(userLoader, pathToFileURL(cwd).href);
ESMLoader = new Loader();
ESMLoader.hook(hooks);
ESMLoader.runGlobalPreloadCode();
jkrems marked this conversation as resolved.
Show resolved Hide resolved
return exports.ESMLoader = ESMLoader;
})();
}
32 changes: 32 additions & 0 deletions test/es-module/test-esm-loader-side-effect.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Flags: --experimental-loader ./test/fixtures/es-module-loaders/loader-side-effect.mjs --require ./test/fixtures/es-module-loaders/loader-side-effect-require-preload.js
jkrems marked this conversation as resolved.
Show resolved Hide resolved
import { allowGlobals, mustCall } from '../common/index.mjs';
import assert from 'assert';
import { fileURLToPath } from 'url';
import { Worker, isMainThread, parentPort } from 'worker_threads';

/* global implicitGlobalProperty */
assert.strictEqual(globalThis.implicitGlobalProperty, 42);
allowGlobals(implicitGlobalProperty);

/* global implicitGlobalConst */
assert.strictEqual(implicitGlobalConst, 42 * 42);
allowGlobals(implicitGlobalConst);

/* global explicitGlobalProperty */
assert.strictEqual(globalThis.explicitGlobalProperty, 42 * 42 * 42);
allowGlobals(explicitGlobalProperty);

/* global preloadOrder */
assert.deepStrictEqual(globalThis.preloadOrder, ['--require', 'loader']);
allowGlobals(preloadOrder);

if (isMainThread) {
const worker = new Worker(fileURLToPath(import.meta.url));
const promise = new Promise((resolve, reject) => {
worker.on('message', resolve);
worker.on('error', reject);
});
promise.then(mustCall());
} else {
parentPort.postMessage('worker done');
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
/**
* This file is combined with `loader-side-effect.mjs` via `--require`. Its
* purpose is to test execution order of the two kinds of preload code.
*/

(globalThis.preloadOrder || (globalThis.preloadOrder = [])).push('--require');
32 changes: 32 additions & 0 deletions test/fixtures/es-module-loaders/loader-side-effect.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// Arrow function so it closes over the this-value of the preload scope.
const globalPreload = () => {
/* global getBuiltin */
const assert = getBuiltin('assert');
const vm = getBuiltin('vm');

assert.strictEqual(typeof require, 'undefined');
assert.strictEqual(typeof module, 'undefined');
assert.strictEqual(typeof exports, 'undefined');
assert.strictEqual(typeof __filename, 'undefined');
assert.strictEqual(typeof __dirname, 'undefined');

assert.strictEqual(this, globalThis);
(globalThis.preloadOrder || (globalThis.preloadOrder = [])).push('loader');

vm.runInThisContext(`\
var implicitGlobalProperty = 42;
const implicitGlobalConst = 42 * 42;
`);

assert.strictEqual(globalThis.implicitGlobalProperty, 42);
(implicitGlobalProperty).foo = 'bar'; // assert: not strict mode

globalThis.explicitGlobalProperty = 42 * 42 * 42;
}

export function getGlobalPreloadCode() {
return `\
<!-- assert: inside of script goal -->
(${globalPreload.toString()})();
`;
}