esm: provide named exports for builtin libs

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 wrapped in a proxy such
that APMs and other behavior are still left intact.
PR-URL: #20403
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Jan Krems <jan.krems@gmail.com>

Author: devsnek

doc/api/esm.md

@@ -95,16 +95,43 @@ When loaded via `import` these modules will provide a single `default` export
 representing the value of `module.exports` at the time they finished evaluating.
 
 ```js
-importfsfrom'fs';
-fs.readFile('./foo.txt', (err, body) => {
+// foo.js
+module.exports= { one:1 };
+
+// bar.js
+importfoofrom'./foo.js';
+foo.one===1; // true
+```
+
+Builtin modules will provide named exports of their public API, as well as a
+default export which can be used for, among other things, modifying the named
+exports. Named exports of builtin modules are updated when the corresponding
+exports property is accessed, redefined, or deleted.
+
+```js
+importEventEmitterfrom'events';
+conste=newEventEmitter();
+```
+
+```js
+import { readFile } from'fs';
+readFile('./foo.txt', (err, source) => {
 if (err) {
 console.error(err);
  } else {
-console.log(body);
+console.log(source);
  }
 });
 ```
 
+```js
+importfs, { readFileSync } from'fs';
+
+fs.readFileSync= () =>Buffer.from('Hello, ESM');
+
+fs.readFileSync=== readFileSync;
+```
+
 ## Loader hooks
 
 <!-- type=misc -->

lib/internal/bootstrap/loaders.js

@@ -41,10 +41,26 @@
 
 (functionbootstrapInternalLoaders(process,getBinding,getLinkedBinding,
 getInternalBinding){
+const{
+apply: ReflectApply,
+deleteProperty: ReflectDeleteProperty,
+get: ReflectGet,
+getOwnPropertyDescriptor: ReflectGetOwnPropertyDescriptor,
+has: ReflectHas,
+set: ReflectSet,
+}=Reflect;
+const{
+prototype: {
+hasOwnProperty: ObjectHasOwnProperty,
+},
+create: ObjectCreate,
+defineProperty: ObjectDefineProperty,
+keys: ObjectKeys,
+}=Object;
 
 // Set up process.moduleLoadList
 constmoduleLoadList=[];
-Object.defineProperty(process,'moduleLoadList',{
+ObjectDefineProperty(process,'moduleLoadList',{
 value: moduleLoadList,
 configurable: true,
 enumerable: true,
@@ -53,7 +69,7 @@
 
 // Set up process.binding() and process._linkedBinding()
 {
-constbindingObj=Object.create(null);
+constbindingObj=ObjectCreate(null);
 
 process.binding=functionbinding(module){
 module=String(module);
@@ -77,7 +93,7 @@
 // Set up internalBinding() in the closure
 letinternalBinding;
 {
-constbindingObj=Object.create(null);
+constbindingObj=ObjectCreate(null);
 internalBinding=functioninternalBinding(module){
 letmod=bindingObj[module];
 if(typeofmod!=='object'){
@@ -95,6 +111,8 @@
 this.filename=`${id}.js`;
 this.id=id;
 this.exports={};
+this.reflect=undefined;
+this.exportKeys=undefined;
 this.loaded=false;
 this.loading=false;
 }
@@ -193,6 +211,12 @@
 '\n});'
 ];
 
+constgetOwn=(target,property,receiver)=>{
+returnReflectApply(ObjectHasOwnProperty,target,[property]) ?
+ReflectGet(target,property,receiver) :
+undefined;
+};
+
 NativeModule.prototype.compile=function(){
 letsource=NativeModule.getSource(this.id);
 source=NativeModule.wrap(source);
@@ -208,6 +232,60 @@
 NativeModule.require;
 fn(this.exports,requireFn,this,process);
 
+if(config.experimentalModules&&!NativeModule.isInternal(this.id)){
+this.exportKeys=ObjectKeys(this.exports);
+
+constupdate=(property,value)=>{
+if(this.reflect!==undefined&&
+ReflectApply(ObjectHasOwnProperty,
+this.reflect.exports,[property]))
+this.reflect.exports[property].set(value);
+};
+
+consthandler={
+__proto__: null,
+defineProperty: (target,prop,descriptor)=>{
+// Use `Object.defineProperty` instead of `Reflect.defineProperty`
+// to throw the appropriate error if something goes wrong.
+ObjectDefineProperty(target,prop,descriptor);
+if(typeofdescriptor.get==='function'&&
+!ReflectHas(handler,'get')){
+handler.get=(target,prop,receiver)=>{
+constvalue=ReflectGet(target,prop,receiver);
+if(ReflectApply(ObjectHasOwnProperty,target,[prop]))
+update(prop,value);
+returnvalue;
+};
+}
+update(prop,getOwn(target,prop));
+returntrue;
+},
+deleteProperty: (target,prop)=>{
+if(ReflectDeleteProperty(target,prop)){
+update(prop,undefined);
+returntrue;
+}
+returnfalse;
+},
+set: (target,prop,value,receiver)=>{
+constdescriptor=ReflectGetOwnPropertyDescriptor(target,prop);
+if(ReflectSet(target,prop,value,receiver)){
+if(descriptor&&typeofdescriptor.set==='function'){
+for(constkeyofthis.exportKeys){
+update(key,getOwn(target,key,receiver));
+}
+}else{
+update(prop,getOwn(target,prop,receiver));
+}
+returntrue;
+}
+returnfalse;
+}
+};
+
+this.exports=newProxy(this.exports,handler);
+}
+
 this.loaded=true;
 }finally{
 this.loading=false;

lib/internal/modules/esm/create_dynamic_module.js

@@ -52,9 +52,10 @@ const createDynamicModule = (exports, url = '', evaluate) => {
 constmodule=newModuleWrap(reexports,`${url}`);
 module.link(async()=>reflectiveModule);
 module.instantiate();
+reflect.namespace=module.namespace();
 return{
  module,
- reflect
+ reflect,
 };
 };
 

lib/internal/modules/esm/translators.js

@@ -59,11 +59,18 @@ translators.set('cjs', async (url) => {
 // through normal resolution
 translators.set('builtin',async(url)=>{
 debug(`Translating BuiltinModule ${url}`);
-returncreateDynamicModule(['default'],url,(reflect)=>{
-debug(`Loading BuiltinModule ${url}`);
-constexports=NativeModule.require(url.slice(5));
-reflect.exports.default.set(exports);
-});
+// slice 'node:' scheme
+constid=url.slice(5);
+NativeModule.require(id);
+constmodule=NativeModule.getCached(id);
+returncreateDynamicModule(
+[...module.exportKeys,'default'],url,(reflect)=>{
+debug(`Loading BuiltinModule ${url}`);
+module.reflect=reflect;
+for(constkeyofmodule.exportKeys)
+reflect.exports[key].set(module.exports[key]);
+reflect.exports.default.set(module.exports);
+});
 });
 
 // Strategy for loading a node native module

test/es-module/test-esm-dynamic-import.js

@@ -52,6 +52,7 @@ function expectFsNamespace(result) {
 Promise.resolve(result)
 .then(common.mustCall(ns=>{
 assert.strictEqual(typeofns.default.writeFile,'function');
+assert.strictEqual(typeofns.writeFile,'function');
 }));
 }
 

test/es-module/test-esm-live-binding.mjs

@@ -0,0 +1,143 @@
+// Flags: --experimental-modules
+
+import'../common';
+importassertfrom'assert';
+
+importfs,{readFile,readFileSync}from'fs';
+importevents,{defaultMaxListeners}from'events';
+importutilfrom'util';
+
+constreadFileDescriptor=Reflect.getOwnPropertyDescriptor(fs,'readFile');
+constreadFileSyncDescriptor=
+Reflect.getOwnPropertyDescriptor(fs,'readFileSync');
+
+consts=Symbol();
+constfn=()=>s;
+
+Reflect.deleteProperty(fs,'readFile');
+
+assert.deepStrictEqual([fs.readFile,readFile],[undefined,undefined]);
+
+fs.readFile=fn;
+
+assert.deepStrictEqual([fs.readFile(),readFile()],[s,s]);
+
+Reflect.defineProperty(fs,'readFile',{
+value: fn,
+configurable: true,
+writable: true,
+});
+
+assert.deepStrictEqual([fs.readFile(),readFile()],[s,s]);
+
+Reflect.deleteProperty(fs,'readFile');
+
+assert.deepStrictEqual([fs.readFile,readFile],[undefined,undefined]);
+
+letcount=0;
+
+Reflect.defineProperty(fs,'readFile',{
+get(){returncount;},
+configurable: true,
+});
+
+count++;
+
+assert.deepStrictEqual([readFile,fs.readFile,readFile],[0,1,1]);
+
+letotherValue;
+
+Reflect.defineProperty(fs,'readFile',{// eslint-disable-line accessor-pairs
+set(value){
+Reflect.deleteProperty(fs,'readFile');
+otherValue=value;
+},
+configurable: true,
+});
+
+Reflect.defineProperty(fs,'readFileSync',{
+get(){
+returnotherValue;
+},
+configurable: true,
+});
+
+fs.readFile=2;
+
+assert.deepStrictEqual([readFile,readFileSync],[undefined,2]);
+
+Reflect.defineProperty(fs,'readFile',readFileDescriptor);
+Reflect.defineProperty(fs,'readFileSync',readFileSyncDescriptor);
+
+constoriginDefaultMaxListeners=events.defaultMaxListeners;
+constutilProto=util.__proto__;// eslint-disable-line no-proto
+
+count=0;
+
+Reflect.defineProperty(Function.prototype,'defaultMaxListeners',{
+configurable: true,
+enumerable: true,
+get: function(){return++count;},
+set: function(v){
+Reflect.defineProperty(this,'defaultMaxListeners',{
+configurable: true,
+enumerable: true,
+writable: true,
+value: v,
+});
+},
+});
+
+assert.strictEqual(defaultMaxListeners,originDefaultMaxListeners);
+assert.strictEqual(events.defaultMaxListeners,originDefaultMaxListeners);
+
+assert.strictEqual(++events.defaultMaxListeners,
+originDefaultMaxListeners+1);
+
+assert.strictEqual(defaultMaxListeners,originDefaultMaxListeners+1);
+assert.strictEqual(Function.prototype.defaultMaxListeners,1);
+
+Function.prototype.defaultMaxListeners='foo';
+
+assert.strictEqual(Function.prototype.defaultMaxListeners,'foo');
+assert.strictEqual(events.defaultMaxListeners,originDefaultMaxListeners+1);
+assert.strictEqual(defaultMaxListeners,originDefaultMaxListeners+1);
+
+count=0;
+
+constp={
+getfoo(){return++count;},
+setfoo(v){
+Reflect.defineProperty(this,'foo',{
+configurable: true,
+enumerable: true,
+writable: true,
+value: v,
+});
+},
+};
+
+util.__proto__=p;// eslint-disable-line no-proto
+
+assert.strictEqual(util.foo,1);
+
+util.foo='bar';
+
+assert.strictEqual(count,1);
+assert.strictEqual(util.foo,'bar');
+assert.strictEqual(p.foo,2);
+
+p.foo='foo';
+
+assert.strictEqual(p.foo,'foo');
+
+events.defaultMaxListeners=originDefaultMaxListeners;
+util.__proto__=utilProto;// eslint-disable-line no-proto
+
+Reflect.deleteProperty(util,'foo');
+Reflect.deleteProperty(Function.prototype,'defaultMaxListeners');
+
+assert.throws(
+()=>Object.defineProperty(events,'defaultMaxListeners',{value: 3}),
+/TypeError:Cannotredefine/
+);

test/es-module/test-esm-namespace.mjs

@@ -2,5 +2,13 @@
 import'../common';
 import*asfsfrom'fs';
 importassertfrom'assert';
+importModulefrom'module';
 
-assert.deepStrictEqual(Object.keys(fs),['default']);
+constkeys=Object.entries(
+Object.getOwnPropertyDescriptors(newModule().require('fs')))
+.filter(([name,d])=>d.enumerable)
+.map(([name])=>name)
+.concat('default')
+.sort();
+
+assert.deepStrictEqual(Object.keys(fs).sort(),keys);