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: https://github.com/nodejs/node/pull/20403
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Jan Krems <jan.krems@gmail.com>

1 files changed, 30 insertions, 3 deletions

diff --git a/doc/api/esm.md b/doc/api/esm.md
index a1e3cb149a..459f877718 100644
--- a/doc/api/esm.md
+++ b/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
-import fs from 'fs';
-fs.readFile('./foo.txt', (err, body) => {
+// foo.js
+module.exports = { one: 1 };
+
+// bar.js
+import foo from './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
+import EventEmitter from 'events';
+const e = new EventEmitter();
+```
+
+```js
+import { readFile } from 'fs';
+readFile('./foo.txt', (err, source) => {
   if (err) {
     console.error(err);
   } else {
-    console.log(body);
+    console.log(source);
   }
 });
 ```
 
+```js
+import fs, { readFileSync } from 'fs';
+
+fs.readFileSync = () => Buffer.from('Hello, ESM');
+
+fs.readFileSync === readFileSync;
+```
+
 ## Loader hooks
 
 <!-- type=misc -->