esm: remove globalPreload hook (superseded by initialize)

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
-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>');
-// [...]
-`;
-}
-```
-
-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
- */
-export function globalPreload({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;
 
 class Hooks{
  #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){
  const next = this.#chains.resolve[this.#chains.resolve.length - 1];
  ArrayPrototypePush(this.#chains.resolve,{__proto__: null, fn: resolve, url, next });
@@ -178,49 +157,6 @@ class Hooks{
  return initialize?.(data);
  }
 
- /**
- * Initialize `globalPreload` hooks.
- */
- initializeGlobalPreload(){
- const preloadScripts = [];
- for (let i = this.#chains.globalPreload.length - 1; i >= 0; i--){
- const{MessageChannel } = require('internal/worker/io');
- const channel = new MessageChannel();
- const{
- port1: insidePreload,
- port2: insideLoader,
- } = channel;
-
- insidePreload.unref();
- insideLoader.unref();
-
- const{
- fn: preload,
- url: specifier,
- } = this.#chains.globalPreload[i];
-
- const preloaded = preload({
- port: insideLoader,
- });
-
- if (preloaded == null){continue}
-
- if (typeof preloaded !== 'string'){// [2]
- throw new ERR_INVALID_RETURN_VALUE(
- 'a string',
- `${specifier} globalPreload`,
- preload,
- );
- }
-
- ArrayPrototypePush(preloadScripts,{
- code: preloaded,
- port: insidePreload,
- });
- }
- return preloadScripts;
- }
-
  /**
  * Resolve the location of the module.
  *
@@ -559,8 +495,9 @@ class HooksProxy{
  AtomicsWait(this.#lock, WORKER_TO_MAIN_THREAD_NOTIFICATION, 0);
  const response = 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 (let i = 0; i < preloadScripts.length; i++){
- const{code, port } = preloadScripts[i];
- const{compileFunction } = require('vm');
- const preloadInit = compileFunction(
- code,
- ['getBuiltin', 'port', 'setImportMetaCallback'],
-{
- filename: '<preload>',
- },
- );
- let finished = false;
- let replacedImportMetaInitializer = false;
- let next = 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);
- } else if (!BuiltinModule.canBeRequiredWithoutScheme(builtinName)){
- throw new ERR_UNKNOWN_BUILTIN_MODULE(builtinName);
- }
- if (BuiltinModule.canBeRequiredByUsers(builtinName)){
- return require(builtinName);
- }
- throw new ERR_UNKNOWN_BUILTIN_MODULE(builtinName);
- },
- // Param port
- port,
- // setImportMetaCallback
- (fn) =>{
- if (finished || typeof fn !== 'function'){
- throw new ERR_INVALID_ARG_TYPE('fn', fn);
- }
- replacedImportMetaInitializer = true;
- const parent = next;
- next = (meta, context) =>{
- return fn(meta, context, parent);
- };
- },
- );
- } finally{
- finished = true;
- if (replacedImportMetaInitializer){
- this.#importMetaInitializer = next;
- }
- }
- }
- }
 }
 ObjectSetPrototypeOf(HooksProxy.prototype, null);
 
+// TODO(JakobJingleheimer): Remove this when loaders go "stable".
+let globalPreloadWarningWasEmitted = 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({
 }){
  const acceptedHooks ={__proto__: null };
 
- if (globalPreload){
- acceptedHooks.globalPreload = globalPreload;
- }
  if (resolve){
  acceptedHooks.resolve = resolve;
  }
@@ -762,6 +642,12 @@ function pluckHooks({
 
  if (initialize){
  acceptedHooks.initialize = initialize;
+ } else if (globalPreload && !globalPreloadWarningWasEmitted){
+ process.emitWarning(
+ '`globalPreload` has been removed; use `initialize` instead.',
+ 'UnsupportedWarning',
+ );
+ globalPreloadWarningWasEmitted = true;
  }
 
  return acceptedHooks;

lib/internal/modules/esm/utils.js

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

lib/internal/modules/esm/worker.js

@@ -74,7 +74,8 @@ function wrapMessage(status, body){
 }
 
 async function customizedModuleWorker(lock, syncCommPort, errorHandler){
- let hooks, preloadScripts, initializationError;
+ let hooks;
+ let initializationError;
  let hasInitializationError = false;
 
 {
@@ -91,9 +92,7 @@ async function customizedModuleWorker(lock, syncCommPort, errorHandler){
 
 
  try{
- const initResult = await initializeHooks();
- hooks = initResult.hooks;
- preloadScripts = initResult.preloadScripts;
+ hooks = await initializeHooks();
  } 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.