lib: refactor NativeModule

Refactor the internal NativeModule class to a JS class and add more documentation about its properties. PR-URL: #30856 Reviewed-By: Denys Otrishko <[email protected]> Reviewed-By: Gus Caplan <[email protected]> Reviewed-By: Rich Trott <[email protected]>

Author: joyeecheung

lib/internal/bootstrap/loaders.js

@@ -137,166 +137,180 @@ let internalBinding;
 };
 }
 
-// Think of this as module.exports in this file even though it is not
-// written in CommonJS style.
-constloaderExports={
- internalBinding,
- NativeModule,
-require: nativeModuleRequire
-};
-
 constloaderId='internal/bootstrap/loaders';
-
-// Set up NativeModule.
-functionNativeModule(id){
-this.filename=`${id}.js`;
-this.id=id;
-this.exports={};
-this.module=undefined;
-this.exportKeys=undefined;
-this.loaded=false;
-this.loading=false;
-this.canBeRequiredByUsers=!id.startsWith('internal/');
-}
-
-// To be called during pre-execution when --expose-internals is on.
-// Enables the user-land module loader to access internal modules.
-NativeModule.exposeInternals=function(){
-for(const[id,mod]ofNativeModule.map){
-// Do not expose this to user land even with --expose-internals.
-if(id!==loaderId){
-mod.canBeRequiredByUsers=true;
-}
-}
-};
-
 const{
  moduleIds,
  compileFunction
 }=internalBinding('native_module');
 
-NativeModule.map=newMap();
-for(leti=0;i<moduleIds.length;++i){
-constid=moduleIds[i];
-constmod=newNativeModule(id);
-NativeModule.map.set(id,mod);
-}
+constgetOwn=(target,property,receiver)=>{
+returnObjectPrototypeHasOwnProperty(target,property) ?
+ReflectGet(target,property,receiver) :
+undefined;
+};
 
-functionnativeModuleRequire(id){
-if(id===loaderId){
-returnloaderExports;
+/**
+ * An internal abstraction for the built-in JavaScript modules of Node.js.
+ * Be careful not to expose this to user land unless --expose-internals is
+ * used, in which case there is no compatibility guarantee about this class.
+ */
+classNativeModule{
+/**
+ * A map from the module IDs to the module instances.
+ * @type{Map<string, NativeModule>}
+ */
+staticmap=newMap(moduleIds.map((id)=>[id,newNativeModule(id)]));
+
+constructor(id){
+this.filename=`${id}.js`;
+this.id=id;
+this.canBeRequiredByUsers=!id.startsWith('internal/');
+
+// The CJS exports object of the module.
+this.exports={};
+// States used to work around circular dependencies.
+this.loaded=false;
+this.loading=false;
+
+// The following properties are used by the ESM implementation and only
+// initialized when the native module is loaded by users.
+/**
+ * The C++ ModuleWrap binding used to interface with the ESM implementation.
+ * @type{ModuleWrap|undefined}
+ */
+this.module=undefined;
+/**
+ * Exported names for the ESM imports.
+ * @type{string[]|undefined}
+ */
+this.exportKeys=undefined;
 }
 
-constmod=NativeModule.map.get(id);
-// Can't load the internal errors module from here, have to use a raw error.
-// eslint-disable-next-line no-restricted-syntax
-if(!mod)thrownewTypeError(`Missing internal module '${id}'`);
-returnmod.compile();
-}
+// To be called during pre-execution when --expose-internals is on.
+// Enables the user-land module loader to access internal modules.
+staticexposeInternals(){
+for(const[id,mod]ofNativeModule.map){
+// Do not expose this to user land even with --expose-internals.
+if(id!==loaderId){
+mod.canBeRequiredByUsers=true;
+}
+}
+}
 
-NativeModule.exists=function(id){
-returnNativeModule.map.has(id);
-};
+staticexists(id){
+returnNativeModule.map.has(id);
+}
 
-NativeModule.canBeRequiredByUsers=function(id){
-constmod=NativeModule.map.get(id);
-returnmod&&mod.canBeRequiredByUsers;
-};
+staticcanBeRequiredByUsers(id){
+constmod=NativeModule.map.get(id);
+returnmod&&mod.canBeRequiredByUsers;
+}
 
-// Allow internal modules from dependencies to require
-// other modules from dependencies by providing fallbacks.
-functionrequireWithFallbackInDeps(request){
-if(!NativeModule.map.has(request)){
-request=`internal/deps/${request}`;
+// Used by user-land module loaders to compile and load builtins.
+compileForPublicLoader(){
+if(!this.canBeRequiredByUsers){
+// No code because this is an assertion against bugs
+// eslint-disable-next-line no-restricted-syntax
+thrownewError(`Should not compile ${this.id} for public use`);
+}
+this.compileForInternalLoader();
+if(!this.exportKeys){
+// When using --expose-internals, we do not want to reflect the named
+// exports from core modules as this can trigger unnecessary getters.
+constinternal=this.id.startsWith('internal/');
+this.exportKeys=internal ? [] : ObjectKeys(this.exports);
+}
+this.getESMFacade();
+this.syncExports();
+returnthis.exports;
 }
-returnnativeModuleRequire(request);
-}
 
-// This is exposed for public loaders
-NativeModule.prototype.compileForPublicLoader=function(){
-if(!this.canBeRequiredByUsers){
-// No code because this is an assertion against bugs
-// eslint-disable-next-line no-restricted-syntax
-thrownewError(`Should not compile ${this.id} for public use`);
+getESMFacade(){
+if(this.module)returnthis.module;
+const{ ModuleWrap }=internalBinding('module_wrap');
+consturl=`node:${this.id}`;
+constnativeModule=this;
+this.module=newModuleWrap(
+url,undefined,[...this.exportKeys,'default'],
+function(){
+nativeModule.syncExports();
+this.setExport('default',nativeModule.exports);
+});
+// Ensure immediate sync execution to capture exports now
+this.module.instantiate();
+this.module.evaluate(-1,false);
+returnthis.module;
 }
-this.compile();
-if(!this.exportKeys){
-// When using --expose-internals, we do not want to reflect the named
-// exports from core modules as this can trigger unnecessary getters.
-constinternal=this.id.startsWith('internal/');
-this.exportKeys=internal ? [] : ObjectKeys(this.exports);
+
+// Provide named exports for all builtin libraries so that the libraries
+// may be imported in a nicer way for ESM users. The default export is left
+// as the entire namespace (module.exports) and updates when this function is
+// called so that APMs and other behavior are supported.
+syncExports(){
+constnames=this.exportKeys;
+if(this.module){
+for(leti=0;i<names.length;i++){
+constexportName=names[i];
+if(exportName==='default')continue;
+this.module.setExport(exportName,
+getOwn(this.exports,exportName,this.exports));
+}
+}
 }
-this.getESMFacade();
-this.syncExports();
-returnthis.exports;
-};
 
-constgetOwn=(target,property,receiver)=>{
-returnObjectPrototypeHasOwnProperty(target,property) ?
-ReflectGet(target,property,receiver) :
-undefined;
-};
+compileForInternalLoader(){
+if(this.loaded||this.loading){
+returnthis.exports;
+}
 
-NativeModule.prototype.getURL=function(){
-return`node:${this.id}`;
-};
+constid=this.id;
+this.loading=true;
 
-NativeModule.prototype.getESMFacade=function(){
-if(this.module)returnthis.module;
-const{ ModuleWrap }=internalBinding('module_wrap');
-consturl=this.getURL();
-constnativeModule=this;
-this.module=newModuleWrap(
-url,undefined,[...this.exportKeys,'default'],
-function(){
-nativeModule.syncExports();
-this.setExport('default',nativeModule.exports);
-});
-// Ensure immediate sync execution to capture exports now
-this.module.instantiate();
-this.module.evaluate(-1,false);
-returnthis.module;
-};
+try{
+constrequireFn=this.id.startsWith('internal/deps/') ?
+requireWithFallbackInDeps : nativeModuleRequire;
 
-// Provide named exports for all builtin libraries so that the libraries
-// may be imported in a nicer way for ESM users. The default export is left
-// as the entire namespace (module.exports) and updates when this function is
-// called so that APMs and other behavior are supported.
-NativeModule.prototype.syncExports=function(){
-constnames=this.exportKeys;
-if(this.module){
-for(leti=0;i<names.length;i++){
-constexportName=names[i];
-if(exportName==='default')continue;
-this.module.setExport(exportName,
-getOwn(this.exports,exportName,this.exports));
+constfn=compileFunction(id);
+fn(this.exports,requireFn,this,process,internalBinding,primordials);
+
+this.loaded=true;
+}finally{
+this.loading=false;
 }
-}
-};
 
-NativeModule.prototype.compile=function(){
-if(this.loaded||this.loading){
+moduleLoadList.push(`NativeModule ${id}`);
 returnthis.exports;
 }
+}
 
-constid=this.id;
-this.loading=true;
+// Think of this as module.exports in this file even though it is not
+// written in CommonJS style.
+constloaderExports={
+ internalBinding,
+ NativeModule,
+require: nativeModuleRequire
+};
 
-try{
-constrequireFn=this.id.startsWith('internal/deps/') ?
-requireWithFallbackInDeps : nativeModuleRequire;
+functionnativeModuleRequire(id){
+if(id===loaderId){
+returnloaderExports;
+}
 
-constfn=compileFunction(id);
-fn(this.exports,requireFn,this,process,internalBinding,primordials);
+constmod=NativeModule.map.get(id);
+// Can't load the internal errors module from here, have to use a raw error.
+// eslint-disable-next-line no-restricted-syntax
+if(!mod)thrownewTypeError(`Missing internal module '${id}'`);
+returnmod.compileForInternalLoader();
+}
 
-this.loaded=true;
-}finally{
-this.loading=false;
+// Allow internal modules from dependencies to require
+// other modules from dependencies by providing fallbacks.
+functionrequireWithFallbackInDeps(request){
+if(!NativeModule.map.has(request)){
+request=`internal/deps/${request}`;
 }
+returnnativeModuleRequire(request);
+}
 
-moduleLoadList.push(`NativeModule ${id}`);
-returnthis.exports;
-};
-
-// This will be passed to internal/bootstrap/node.js.
+// Pass the exports back to C++ land for C++ internals to use.
 returnloaderExports;