esm: remove globalPreload hook (superseded by initialize)

PR-URL: #49144 Reviewed-By: Geoffrey Booth <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]>

Author: JakobJingleheimer

doc/api/module.md

@@ -149,6 +149,9 @@ import('node:fs').then((esmFS) =>{
 <!-- YAML
 added: v8.8.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/49144
+ description: Removed `globalPreload`.
  - version: v20.6.0
  pr-url: https://github.com/nodejs/node/pull/48842
  description: Added `initialize` hook to replace `globalPreload`.
@@ -674,79 +677,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.
--->
-
-> Stability: 1.0 - Early development
-
-> **Warning:** This hook will be removed in a future version. Use
-> [`initialize`][] instead. When a hooks module has an `initialize` export,
-> `globalPreload` will be ignored.
-
-* `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()`.
-
-```mjs
-exportfunctionglobalPreload(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>');
-// [...]
-`;
-}
-```
-
-Another argument is provided to the preload code: `port`. This is available as a
-parameter to the hook and inside of the source text returned by the hook. This
-functionality has been moved to the `initialize` hook.
-
-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.
-
-```mjs
-/**
- * This example has the application context send a message to the hook
- * and sends the message back to the application context
-*/
-exportfunctionglobalPreload({port }){
-port.onmessage= (evt) =>{
-port.postMessage(evt.data);
- };
-return`\
- port.postMessage('console.log("I went to the hook and back");');
- port.onmessage = (evt) =>{
- eval(evt.data);
- };
-`;
-}
-```
-
 ### Examples
 
 The various module customization hooks can be used together to accomplish
@@ -1105,8 +1035,6 @@ returned object contains the following keys:
 [`Uint8Array`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array
 [`initialize`]: #initialize
 [`module`]: modules.md#the-module-object
-[`port.ref()`]: worker_threads.md#portref
-[`port.unref()`]: worker_threads.md#portunref
 [`register`]: #moduleregisterspecifier-parenturl-options
 [`string`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
 [`util.TextDecoder`]: util.md#class-utiltextdecoder

lib/internal/modules/esm/hooks.js

@@ -3,15 +3,13 @@
 const{
  ArrayPrototypePush,
  ArrayPrototypePushApply,
- FunctionPrototypeCall,
  Int32Array,
  ObjectAssign,
  ObjectDefineProperty,
  ObjectSetPrototypeOf,
  Promise,
  SafeSet,
  StringPrototypeSlice,
- StringPrototypeStartsWith,
  StringPrototypeToUpperCase,
  globalThis,
 }=primordials;
@@ -33,7 +31,6 @@ const{
 ERR_INVALID_RETURN_VALUE,
 ERR_LOADER_CHAIN_INCOMPLETE,
 ERR_METHOD_NOT_IMPLEMENTED,
-ERR_UNKNOWN_BUILTIN_MODULE,
 ERR_WORKER_UNSERIALIZABLE_ERROR,
 }=require('internal/errors').codes;
 const{exitCodes: { kUnfinishedTopLevelAwait }}=internalBinding('errors');
@@ -49,7 +46,6 @@ const{
  validateString,
 }=require('internal/validators');
 const{
- emitExperimentalWarning,
  kEmptyObject,
 }=require('internal/util');
 
@@ -73,8 +69,6 @@ let importMetaInitializer;
 
 /**
  * @typedef{object} ExportedHooks
- * @property{Function} initialize Customizations setup hook.
- * @property{Function} globalPreload Global preload hook.
  * @property{Function} resolve Resolve hook.
  * @property{Function} load Load hook.
  */
@@ -89,13 +83,6 @@ let importMetaInitializer;
 
 classHooks{
  #chains ={
-/**
- * Prior to ESM loading. These are called once before any modules are started.
- * @private
- * @property{KeyedHook[]} globalPreload Last-in-first-out list of preload hooks.
- */
-globalPreload: [],
-
 /**
  * Phase 1 of 2 in ESM loading.
  * The output of the `resolve` chain of hooks is passed into the `load` chain of hooks.
@@ -146,7 +133,6 @@ class Hooks{
 
 /**
  * Collect custom/user-defined module loader hook(s).
- * After all hooks have been collected, the global preload hook(s) must be initialized.
  * @param{string} url Custom loader specifier
  * @param{Record<string, unknown>} exports
  * @param{any} [data] Arbitrary data to be passed from the custom loader (user-land)
@@ -155,18 +141,11 @@ class Hooks{
  */
 addCustomLoader(url,exports,data){
 const{
- globalPreload,
  initialize,
  resolve,
  load,
 }=pluckHooks(exports);
 
-if(globalPreload&&!initialize){
-emitExperimentalWarning(
-'`globalPreload` is planned for removal in favor of `initialize`. `globalPreload`',
-);
-ArrayPrototypePush(this.#chains.globalPreload,{__proto__: null,fn: globalPreload, url });
-}
 if(resolve){
 constnext=this.#chains.resolve[this.#chains.resolve.length-1];
 ArrayPrototypePush(this.#chains.resolve,{__proto__: null,fn: resolve, url, next });
@@ -178,49 +157,6 @@ class Hooks{
 returninitialize?.(data);
 }
 
-/**
- * Initialize `globalPreload` hooks.
- */
-initializeGlobalPreload(){
-constpreloadScripts=[];
-for(leti=this.#chains.globalPreload.length-1;i>=0;i--){
-const{ MessageChannel }=require('internal/worker/io');
-constchannel=newMessageChannel();
-const{
-port1: insidePreload,
-port2: insideLoader,
-}=channel;
-
-insidePreload.unref();
-insideLoader.unref();
-
-const{
-fn: preload,
-url: specifier,
-}=this.#chains.globalPreload[i];
-
-constpreloaded=preload({
-port: insideLoader,
-});
-
-if(preloaded==null){continue;}
-
-if(typeofpreloaded!=='string'){// [2]
-thrownewERR_INVALID_RETURN_VALUE(
-'a string',
-`${specifier} globalPreload`,
-preload,
-);
-}
-
-ArrayPrototypePush(preloadScripts,{
-code: preloaded,
-port: insidePreload,
-});
-}
-returnpreloadScripts;
-}
-
 /**
  * Resolve the location of the module.
  *
@@ -559,8 +495,9 @@ class HooksProxy{
 AtomicsWait(this.#lock,WORKER_TO_MAIN_THREAD_NOTIFICATION,0);
 constresponse=this.#worker.receiveMessageSync();
 if(response==null||response.message.status==='exit'){return;}
-const{ preloadScripts }=this.#unwrapMessage(response);
-this.#executePreloadScripts(preloadScripts);
+
+// ! This line catches initialization errors in the worker thread.
+this.#unwrapMessage(response);
 }
 
 this.#isReady =true;
@@ -677,66 +614,12 @@ class HooksProxy{
 importMetaInitialize(meta,context,loader){
 this.#importMetaInitializer(meta,context,loader);
 }
-
- #executePreloadScripts(preloadScripts){
-for(leti=0;i<preloadScripts.length;i++){
-const{ code, port }=preloadScripts[i];
-const{ compileFunction }=require('vm');
-constpreloadInit=compileFunction(
-code,
-['getBuiltin','port','setImportMetaCallback'],
-{
-filename: '<preload>',
-},
-);
-letfinished=false;
-letreplacedImportMetaInitializer=false;
-letnext=this.#importMetaInitializer;
-const{ BuiltinModule }=require('internal/bootstrap/realm');
-// Calls the compiled preload source text gotten from the hook
-// Since the parameters are named we use positional parameters
-// see compileFunction above to cross reference the names
-try{
-FunctionPrototypeCall(
-preloadInit,
-globalThis,
-// Param getBuiltin
-(builtinName)=>{
-if(StringPrototypeStartsWith(builtinName,'node:')){
-builtinName=StringPrototypeSlice(builtinName,5);
-}elseif(!BuiltinModule.canBeRequiredWithoutScheme(builtinName)){
-thrownewERR_UNKNOWN_BUILTIN_MODULE(builtinName);
-}
-if(BuiltinModule.canBeRequiredByUsers(builtinName)){
-returnrequire(builtinName);
-}
-thrownewERR_UNKNOWN_BUILTIN_MODULE(builtinName);
-},
-// Param port
-port,
-// setImportMetaCallback
-(fn)=>{
-if(finished||typeoffn!=='function'){
-thrownewERR_INVALID_ARG_TYPE('fn',fn);
-}
-replacedImportMetaInitializer=true;
-constparent=next;
-next=(meta,context)=>{
-returnfn(meta,context,parent);
-};
-},
-);
-}finally{
-finished=true;
-if(replacedImportMetaInitializer){
-this.#importMetaInitializer =next;
-}
-}
-}
-}
 }
 ObjectSetPrototypeOf(HooksProxy.prototype,null);
 
+// TODO(JakobJingleheimer): Remove this when loaders go "stable".
+letglobalPreloadWarningWasEmitted=false;
+
 /**
  * A utility function to pluck the hooks from a user-defined loader.
  * @param{import('./loader.js).ModuleExports} exports
@@ -750,9 +633,6 @@ function pluckHooks({
 }){
 constacceptedHooks={__proto__: null};
 
-if(globalPreload){
-acceptedHooks.globalPreload=globalPreload;
-}
 if(resolve){
 acceptedHooks.resolve=resolve;
 }
@@ -762,6 +642,12 @@ function pluckHooks({
 
 if(initialize){
 acceptedHooks.initialize=initialize;
+}elseif(globalPreload&&!globalPreloadWarningWasEmitted){
+process.emitWarning(
+'`globalPreload` has been removed; use `initialize` instead.',
+'UnsupportedWarning',
+);
+globalPreloadWarningWasEmitted=true;
 }
 
 returnacceptedHooks;

lib/internal/modules/esm/utils.js

@@ -145,9 +145,7 @@ async function initializeHooks(){
 );
 }
 
-constpreloadScripts=hooks.initializeGlobalPreload();
-
-return{__proto__: null, hooks, preloadScripts };
+returnhooks;
 }
 
 module.exports={

lib/internal/modules/esm/worker.js

@@ -74,7 +74,8 @@ function wrapMessage(status, body){
 }
 
 asyncfunctioncustomizedModuleWorker(lock,syncCommPort,errorHandler){
-lethooks,preloadScripts,initializationError;
+lethooks;
+letinitializationError;
 lethasInitializationError=false;
 
 {
@@ -91,9 +92,7 @@ async function customizedModuleWorker(lock, syncCommPort, errorHandler){
 
 
 try{
-constinitResult=awaitinitializeHooks();
-hooks=initResult.hooks;
-preloadScripts=initResult.preloadScripts;
+hooks=awaitinitializeHooks();
 }catch(exception){
 // If there was an error while parsing and executing a user loader, for example if because a
 // loader contained a syntax error, then we need to send the error to the main thread so it can
@@ -107,7 +106,7 @@ async function customizedModuleWorker(lock, syncCommPort, errorHandler){
 if(hasInitializationError){
 syncCommPort.postMessage(wrapMessage('error',initializationError));
 }else{
-syncCommPort.postMessage(wrapMessage('success',{ preloadScripts }),preloadScripts.map(({ port })=>port));
+syncCommPort.postMessage(wrapMessage('success'));
 }
 
 // We're ready, so unlock the main thread.