doc: esm features, differences/interoperability with commonjs

Author: GeoffreyBooth

doc/api/esm.md

@@ -120,17 +120,7 @@ You can use the `.mjs` and `.cjs` extensions to mix types within the same packag
 
 - Within a `"type": "commonjs"` package scope, Node.js can be instructed to interpret a particular file as an ES module by naming it with an `.mjs` extension (since both `.js` and `.cjs` files are treated as CommonJS within a `"commonjs"` package scope).
 
-## Features
-
-<!-- type=misc -->
-
-### Supported
-
-Only the CLI argument for the main entry point to the program can be an entry
-point into an ESM graph. Dynamic import can also be used to create entry points
-into ESM graphs at runtime.
-
-#### import.meta
+## import.meta
 
 * {Object}
 
@@ -139,37 +129,44 @@ property:
 
 * `url` {string} The absolute `file:` URL of the module.
 
-### Unsupported
-
-| Feature | Reason |
-| --- | --- |
-| `require('./foo.mjs')` | ES Modules have differing resolution and timing, use dynamic import |
-
-## Notable differences between `import` and `require`
+## Differences Between ES Modules and CommonJS
 
 ### Mandatory file extensions
 
-You must provide a file extension when using the `import` keyword.
+You must provide a file extension when using the `import` keyword. Directory
+indexes (e.g. `'./startup/index.js'`) must also be fully specified.
 
-### No NODE_PATH
+This behavior matches how `import` behaves in browser environments, assuming a
+typically configured server.
+
+### No <code>NODE_PATH</code>
 
 `NODE_PATH` is not part of resolving `import` specifiers. Please use symlinks
 if this behavior is desired.
 
-### No `require.extensions`
+### No <code>require</code>, <code>exports</code>, <code>module.exports</code>, <code>__filename</code>, <code>__dirname</code>
+
+These CommonJS variables are not available in ES modules.
+
+`require` can be imported into an ES module using
+[`module.createRequireFromPath()`][].
+
+An equivalent for `__filename` and `__dirname` is [`import.meta.url`][].
+
+### No <code>require.extensions</code>
 
 `require.extensions` is not used by `import`. The expectation is that loader
 hooks can provide this workflow in the future.
 
-### No `require.cache`
+### No <code>require.cache</code>
 
 `require.cache` is not used by `import`. It has a separate cache.
 
-### URL based paths
+### URL-based paths
 
-ESM are resolved and cached based upon [URL](https://url.spec.whatwg.org/)
-semantics. This means that files containing special characters such as `#` and
-`?` need to be escaped.
+ES modules are resolved and cached based upon
+[URL](https://url.spec.whatwg.org/) semantics. This means that files containing
+special characters such as `#` and `?` need to be escaped.
 
 Modules will be loaded multiple times if the `import` specifier used to resolve
 them have a different query or fragment.
@@ -181,6 +178,58 @@ import './foo.mjs?query=2'; // loads ./foo.mjs with query of "?query=2"
 
 For now, only modules using the `file:` protocol can be loaded.
 
+## Interoperability with CommonJS
+
+### <code>require</code>
+
+`require` always treats the files it references as CommonJS. This applies
+whether `require` is used the traditional way within a CommonJS environment, or
+in an ES module environment using [`module.createRequireFromPath()`][].
+
+To include an ES module into CommonJS, use [`import()`][].
+
+### <code>import</code> statements
+
+An `import` statement can reference either ES module or CommonJS JavaScript.
+Other file types such as JSON and Native modules are not supported. For those,
+use [`module.createRequireFromPath()`][].
+
+`import` statements are permitted only in ES modules. For similar functionality
+in CommonJS, see [`import()`][].
+
+The _specifier_ of an `import` statement (the string after the `from` keyword)
+can either be an URL-style relative path like `'./file.mjs'` or a package name
+like `'fs'`.
+
+Like in CommonJS, files within packages can be accessed by appending a path to
+the package name.
+
+```js
+import { sin, cos } from 'geometry/trigonometry-functions.mjs';
+```
+
+> Currently only the “default export” is supported for CommonJS files or
+> packages:
+>
+> ```js
+> import _ from 'underscore'; // Works
+>
+> import { shuffle } from 'underscore'; // Errors
+> ```
+>
+> There are ongoing efforts to make the latter code possible.
+
+### <code>import()</code> expressions
+
+Dynamic `import()` is supported in both CommonJS and ES modules. It can be used
+to include ES module files from CommonJS code.
+
+```js
+(async () => {
+  await import('./my-app.mjs');
+})();
+```
+
 ## CommonJS, JSON, and Native Modules
 
 CommonJS, JSON, and Native modules can be used with [`module.createRequireFromPath()`][].
@@ -505,4 +554,6 @@ in the import tree.
 [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md
 [dynamic instantiate hook]: #esm_dynamic_instantiate_hook
 [`module.createRequireFromPath()`]: modules.html#modules_module_createrequirefrompath_filename
+[`import.meta.url`]: esm.html#importmeta
+[`import()`]: esm.html#import-expressions
 [ecmascript-modules implementation]: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md