module: add hook for global preload code

doc/api/esm.md

@@ -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() {
+ 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

lib/internal/modules/esm/loader.js

@@ -7,6 +7,7 @@ const {
 } = primordials;
 
 const {
+ ERR_INVALID_ARG_VALUE,
  ERR_INVALID_RETURN_PROPERTY,
  ERR_INVALID_RETURN_PROPERTY_VALUE,
  ERR_INVALID_RETURN_VALUE,
@@ -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 }>
@@ -168,7 +177,16 @@ class Loader {
  return module.getNamespace();
  }
 
- hook({ resolve, dynamicInstantiate, getFormat, getSource, transformSource }) {
+ hook(hooks) {
+ const {
+ resolve,
+ dynamicInstantiate,
+ getFormat,
+ getSource,
+ transformSource,
+ getGlobalPreloadCode,
+ } = hooks;
+
  // Use .bind() to avoid giving access to the Loader instance when called.
  if (resolve !== undefined)
  this._resolve = FunctionPrototypeBind(resolve, null);
@@ -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) {

lib/internal/process/esm_loader.js

@@ -69,6 +69,7 @@ async function initializeLoader() {
  await ESMLoader.import(userLoader, pathToFileURL(cwd).href);
  ESMLoader = new Loader();
  ESMLoader.hook(hooks);
+ ESMLoader.runGlobalPreloadCode();
  return exports.ESMLoader = ESMLoader;
  })();
 }

test/es-module/test-esm-loader-side-effect.mjs

@@ -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
+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');
+}

test/fixtures/es-module-loaders/loader-side-effect-require-preload.js

@@ -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');

test/fixtures/es-module-loaders/loader-side-effect.mjs

@@ -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()})();
+`;
+}