module: add hook for global preload code

PR-URL: #32068
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Geoffrey Booth <webmaster@geoffreybooth.com>

Author: hybrist

doc/api/esm.md

@@ -1188,6 +1188,39 @@ export async function transformSource(source,
 }
 ```
 
+#### <code>getGlobalPreloadCode</code>hook
+
+>Note:TheloadersAPIisbeingredesigned. Thishookmaydisappearorits
+>signaturemaychange. DonotrelyontheAPIdescribedbelow.
+
+Sometimesitcanbenecessarytorunsomecodeinsideofthesameglobalscope
+thattheapplicationwillrunin. Thishookallowstoreturnastringthatwill
+beranassloppy-modescriptonstartup.
+
+SimilartohowCommonJSwrapperswork, thecoderunsinanimplicitfunction
+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=newSafeMap();
 
+// 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 {
 returnmodule.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;
+}
+constpreloadCode=this._getGlobalPreloadCode();
+if(preloadCode===null){
+return;
+}
+
+if(typeofpreloadCode!=='string'){
+thrownewERR_INVALID_RETURN_VALUE(
+'string','loader getGlobalPreloadCode',preloadCode);
+}
+const{ compileFunction }=require('vm');
+constpreloadInit=compileFunction(preloadCode,['getBuiltin'],{
+filename: '<preload>',
+});
+const{ NativeModule }=require('internal/bootstrap/loaders');
+
+preloadInit.call(globalThis,(builtinName)=>{
+if(NativeModule.canBeRequiredByUsers(builtinName)){
+returnrequire(builtinName);
+}
+thrownewERR_INVALID_ARG_VALUE('builtinName',builtinName);
+});
 }
 
 asyncgetModuleJob(specifier,parentURL){

lib/internal/process/esm_loader.js

@@ -69,6 +69,7 @@ async function initializeLoader() {
 awaitESMLoader.import(userLoader,pathToFileURL(cwd).href);
 ESMLoader=newLoader();
 ESMLoader.hook(hooks);
+ESMLoader.runGlobalPreloadCode();
 returnexports.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';
+importassertfrom'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){
+constworker=newWorker(fileURLToPath(import.meta.url));
+constpromise=newPromise((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.
+constglobalPreload=()=>{
+/* global getBuiltin */
+constassert=getBuiltin('assert');
+constvm=getBuiltin('vm');
+
+assert.strictEqual(typeofrequire,'undefined');
+assert.strictEqual(typeofmodule,'undefined');
+assert.strictEqual(typeofexports,'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;
+}
+
+exportfunctiongetGlobalPreloadCode(){
+return`\
+<!-- assert: inside of script goal -->
+(${globalPreload.toString()})();
+`;
+}