doc: notes from call

Author: GeoffreyBooth

doc/api/esm.md

@@ -17,15 +17,17 @@ specifier resolution, and default behavior.
 
 <!-- type=misc -->
 
-The `--experimental-modules` flag can be used to enable features for loading
-ECMAScript modules.
+The `--experimental-modules` flag can be used to enable support for
+ECMAScript modules (ES modules).
 
-Once this has been set, there are a few different ways to run a file as an ES
-module:
+## Running Node.js with an ECMAScript Module
 
-### <code>.mjs</code> extension
+There are a few ways to start Node.js with an ES module as its input.
 
-Files ending with `.mjs` will be loaded as ES modules.
+### Initial entry point with an <code>.mjs</code> extension
+
+A file ending with `.mjs` passed to Node.js as an initial entry point will be
+loaded as an ES module.
 
 ```sh
 node --experimental-modules my-app.mjs
@@ -55,7 +57,7 @@ to Node.js via `STDIN`.
 node --experimental-modules --type=module --eval \
   "import { sep } from 'path'; console.log(sep);"
 
-coffee --print file-containing-import-statements.coffee | \
+echo "import { sep } from 'path'; console.log(sep);" | \
   node --experimental-modules --type=module
 ```
 
@@ -111,11 +113,11 @@ import './startup/init.js';
 // Loaded as ES module since ./startup contains no package.json file,
 // and therefore inherits the ES module package scope from one level up
 
-import './node_modules/commonjs-package/index.js';
+import 'commonjs-package';
 // Loaded as CommonJS since ./node_modules/commonjs-package/package.json
 // lacks a "type" field or contains "type": "commonjs"
 
-import 'commonjs-package';
+import './node_modules/commonjs-package/index.js';
 // Loaded as CommonJS since ./node_modules/commonjs-package/package.json
 // lacks a "type" field or contains "type": "commonjs"
 ```
@@ -172,23 +174,52 @@ An attempt to `require` the above `es-module-package` would attempt to load
 an error as Node.js would not be able to parse the `export` statement in
 CommonJS.
 
-Even if the `package.json` `"main"` points to a file ending in `.mjs`, the
-`"type": "module"` is required.
-
 As with `import` statements, for ES module usage the value of `"main"` must be
 a full path including extension: `"./index.mjs"`, not `"./index"`.
 
-> Currently a package can define _either_ a CommonJS entry point or an ES module
-> entry point; there is no way to specify separate entry points for CommonJS and
-> ES module usage. This means that a package entry point can be included via
-> `require` or via `import` but not both.
+> Currently a package can define _either_ a CommonJS entry point **or** an ES
+> module entry point; there is no way to specify separate entry points for
+> CommonJS and ES module usage. This means that a package entry point can be
+> included via `require` or via `import` but not both.
 >
 > Such a limitation makes it difficult for packages to support both new versions
 > of Node.js that understand ES modules and older versions of Node.js that
 > understand only CommonJS. There is work ongoing to remove this limitation, and
 > it will very likely entail changes to the behavior of `"main"` as defined
 > here.
 
+## <code>import</code> Specifiers
+
+### Terminology
+
+The _specifier_ of an `import` statement is the string after the `from` keyword,
+e.g. `'path'` in `import { sep } from 'path'`. Specifiers are also used in
+`export from` statements, and as the argument to an `import()` expression.
+
+There are four types of specifiers:
+
+- _Bare specifiers_ like `'some-package'`. They refer to an entry point of a
+  package by the package name.
+
+- _Deep import specifiers_ like `'some-package/lib/shuffle.mjs'`. They refer to
+  a path within a package prefixed by the package name.
+
+- _Relative specifiers_ like `'./startup.js'` or `'../config.mjs'`. They refer
+  to a path relative to the location of the importing file.
+
+- _Absolute specifiers_ like `'file:///opt/nodejs/config.js'`. They refer
+  directly and explicitly to a full path.
+
+Bare specifiers, and the bare specifier portion of deep import specifiers, are
+strings; but everything else in a specifier is a URL.
+
+Only `file://` URLs are supported. A specifier like
+`'https://example.com/app.js'` may be supported by browsers but it is not
+supported in Node.js.
+
+Specifiers may not begin with `/` or `//`. These are reserved for potential
+future use. The root of the current volume may be referenced via `file:///`.
+
 ## import.meta
 
 * {Object}
@@ -282,9 +313,9 @@ import { sin, cos } from 'geometry/trigonometry-functions.mjs';
 >
 > <!-- eslint-disable no-duplicate-imports -->
 > ```js
-> import _ from 'underscore'; // Works
+> import packageMain from 'commonjs-package'; // Works
 >
-> import { shuffle } from 'underscore'; // Errors
+> import { method } from 'commonjs-package'; // Errors
 > ```
 >
 > There are ongoing efforts to make the latter code possible.
@@ -349,6 +380,127 @@ fs.readFileSync = () => Buffer.from('Hello, ESM');
 fs.readFileSync === readFileSync;
 ```
 
+## Experimental Loader hooks
+
+**Note: This API is currently being redesigned and will still change.**.
+
+<!-- type=misc -->
+
+To customize the default module resolution, loader hooks can optionally be
+provided via a `--loader ./loader-name.mjs` argument to Node.js.
+
+When hooks are used they only apply to ES module loading and not to any
+CommonJS modules loaded.
+
+### Resolve hook
+
+The resolve hook returns the resolved file URL and module format for a
+given module specifier and parent file URL:
+
+```js
+const baseURL = new URL('file://');
+baseURL.pathname = `${process.cwd()}/`;
+
+export async function resolve(specifier,
+                              parentModuleURL = baseURL,
+                              defaultResolver) {
+  return {
+    url: new URL(specifier, parentModuleURL).href,
+    format: 'esm'
+  };
+}
+```
+
+The `parentModuleURL` is provided as `undefined` when performing main Node.js
+load itself.
+
+The default Node.js ES module resolution function is provided as a third
+argument to the resolver for easy compatibility workflows.
+
+In addition to returning the resolved file URL value, the resolve hook also
+returns a `format` property specifying the module format of the resolved
+module. This can be one of the following:
+
+| `format` | Description |
+| --- | --- |
+| `'module'` | Load a standard JavaScript module |
+| `'commonjs'` | Load a Node.js CommonJS module |
+| `'builtin'` | Load a Node.js builtin module |
+| `'dynamic'` | Use a [dynamic instantiate hook][] |
+
+For example, a dummy loader to load JavaScript restricted to browser resolution
+rules with only JS file extension and Node.js builtin modules support could
+be written:
+
+```js
+import path from 'path';
+import process from 'process';
+import Module from 'module';
+
+const builtins = Module.builtinModules;
+const JS_EXTENSIONS = new Set(['.js', '.mjs']);
+
+const baseURL = new URL('file://');
+baseURL.pathname = `${process.cwd()}/`;
+
+export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) {
+  if (builtins.includes(specifier)) {
+    return {
+      url: specifier,
+      format: 'builtin'
+    };
+  }
+  if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) {
+    // For node_modules support:
+    // return defaultResolve(specifier, parentModuleURL);
+    throw new Error(
+      `imports must begin with '/', './', or '../'; '${specifier}' does not`);
+  }
+  const resolved = new URL(specifier, parentModuleURL);
+  const ext = path.extname(resolved.pathname);
+  if (!JS_EXTENSIONS.has(ext)) {
+    throw new Error(
+      `Cannot load file with non-JavaScript file extension ${ext}.`);
+  }
+  return {
+    url: resolved.href,
+    format: 'esm'
+  };
+}
+```
+
+With this loader, running:
+
+```console
+NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js
+```
+
+would load the module `x.js` as an ES module with relative resolution support
+(with `node_modules` loading skipped in this example).
+
+### Dynamic instantiate hook
+
+To create a custom dynamic module that doesn't correspond to one of the
+existing `format` interpretations, the `dynamicInstantiate` hook can be used.
+This hook is called only for modules that return `format: 'dynamic'` from
+the `resolve` hook.
+
+```js
+export async function dynamicInstantiate(url) {
+  return {
+    exports: ['customExportName'],
+    execute: (exports) => {
+      // Get and set functions provided for pre-allocated export names
+      exports.customExportName.set('value');
+    }
+  };
+}
+```
+
+With the list of module exports provided upfront, the `execute` function will
+then be called at the exact point of module evaluation order for that module
+in the import tree.
+
 ## Resolution Algorithm
 
 ### Features
@@ -385,6 +537,9 @@ entirely for the CommonJS loader.
 If the top-level `--type` is _"module"_, then the ESM resolver is used
 as described here, with the conditional `--type` check in **ESM_FORMAT**.
 
+<details>
+<summary>Resolver algorithm psuedocode</summary>
+
 **ESM_RESOLVE(_specifier_, _parentURL_, _isMain_)**
 > 1. Let _resolvedURL_ be **undefined**.
 > 1. If _specifier_ is a valid URL, then
@@ -500,126 +655,7 @@ READ_PACKAGE_JSON(_packageURL_)
 >    1. Throw an _Invalid Package Configuration_ error.
 > 1. Return the parsed JSON source of the file at _pjsonURL_.
 
-## Experimental Loader hooks
-
-**Note: This API is currently being redesigned and will still change.**.
-
-<!-- type=misc -->
-
-To customize the default module resolution, loader hooks can optionally be
-provided via a `--loader ./loader-name.mjs` argument to Node.js.
-
-When hooks are used they only apply to ES module loading and not to any
-CommonJS modules loaded.
-
-### Resolve hook
-
-The resolve hook returns the resolved file URL and module format for a
-given module specifier and parent file URL:
-
-```js
-const baseURL = new URL('file://');
-baseURL.pathname = `${process.cwd()}/`;
-
-export async function resolve(specifier,
-                              parentModuleURL = baseURL,
-                              defaultResolver) {
-  return {
-    url: new URL(specifier, parentModuleURL).href,
-    format: 'esm'
-  };
-}
-```
-
-The `parentModuleURL` is provided as `undefined` when performing main Node.js
-load itself.
-
-The default Node.js ES module resolution function is provided as a third
-argument to the resolver for easy compatibility workflows.
-
-In addition to returning the resolved file URL value, the resolve hook also
-returns a `format` property specifying the module format of the resolved
-module. This can be one of the following:
-
-| `format` | Description |
-| --- | --- |
-| `'module'` | Load a standard JavaScript module |
-| `'commonjs'` | Load a Node.js CommonJS module |
-| `'builtin'` | Load a Node.js builtin module |
-| `'dynamic'` | Use a [dynamic instantiate hook][] |
-
-For example, a dummy loader to load JavaScript restricted to browser resolution
-rules with only JS file extension and Node.js builtin modules support could
-be written:
-
-```js
-import path from 'path';
-import process from 'process';
-import Module from 'module';
-
-const builtins = Module.builtinModules;
-const JS_EXTENSIONS = new Set(['.js', '.mjs']);
-
-const baseURL = new URL('file://');
-baseURL.pathname = `${process.cwd()}/`;
-
-export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) {
-  if (builtins.includes(specifier)) {
-    return {
-      url: specifier,
-      format: 'builtin'
-    };
-  }
-  if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) {
-    // For node_modules support:
-    // return defaultResolve(specifier, parentModuleURL);
-    throw new Error(
-      `imports must begin with '/', './', or '../'; '${specifier}' does not`);
-  }
-  const resolved = new URL(specifier, parentModuleURL);
-  const ext = path.extname(resolved.pathname);
-  if (!JS_EXTENSIONS.has(ext)) {
-    throw new Error(
-      `Cannot load file with non-JavaScript file extension ${ext}.`);
-  }
-  return {
-    url: resolved.href,
-    format: 'esm'
-  };
-}
-```
-
-With this loader, running:
-
-```console
-NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js
-```
-
-would load the module `x.js` as an ES module with relative resolution support
-(with `node_modules` loading skipped in this example).
-
-### Dynamic instantiate hook
-
-To create a custom dynamic module that doesn't correspond to one of the
-existing `format` interpretations, the `dynamicInstantiate` hook can be used.
-This hook is called only for modules that return `format: 'dynamic'` from
-the `resolve` hook.
-
-```js
-export async function dynamicInstantiate(url) {
-  return {
-    exports: ['customExportName'],
-    execute: (exports) => {
-      // Get and set functions provided for pre-allocated export names
-      exports.customExportName.set('value');
-    }
-  };
-}
-```
-
-With the list of module exports provided upfront, the `execute` function will
-then be called at the exact point of module evaluation order for that module
-in the import tree.
+</details>
 
 [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