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.
@@ -385,6 +416,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,6 +534,8 @@ READ_PACKAGE_JSON(_packageURL_)
 >    1. Throw an _Invalid Package Configuration_ error.
 > 1. Return the parsed JSON source of the file at _pjsonURL_.
 
+</details>
+
 [Node.js EP for ES Modules]: https://github.com/nodejs/node-eps/blob/master/002-es-modules.md
 [`module.createRequireFromPath()`]: modules.html#modules_module_createrequirefrompath_filename
 [`import.meta.url`]: esm.html#importmeta