New ESM Implementation

[MylesBorins]

This is what I plan to upstream tomorrow.

—

This PR updates the current --experimental-modules implementation based on the work of the modules team and reflects Phase 2 of our new modules plan.

A longer form description of these changes can be found in our draft blog post.

The largest differences from the current implementation include

• packge.type which can be either module or commonjs
  • type: "commonjs":
    • .js is parsed as commonjs
    • default for entry point without an extension is commonjs
  • type: "module":
    • .js is parsed as esm
    • does not support loading JSON or Native Module by default
    • default for entry point without an extension is esm
• --type=[mode] to let you set the type on entry point. Will override package.type for entry point.
• A new file extension .cjs.
  • this is specifically to support importing commonjs in the module mode.
  • this is only in the esm loader, the commonjs loader remains untouched, but the extension will work in the old loader if you use the full file path.
• --es-module-specifier-resolution=[type]
  • options are explicit (default) and node
  • by default our loader will not allow for optional extensions in the import, the path for a module must include the extension if there is one
  • by default our loader will not allow for importing directories that have an index file
  • developers can use --es-module-specifier-resolution=node to enable the commonjs specifier resolution algorithm
  • This is not a “feature” but rather an implementation for experimentation. It is expected to change before the flag is removed
• --experimental-json-loader
  • the only way to import json when "type": "module"
  • when enable all import 'thing.json' will go through the experimental loader independent of mode
  • based on JSON modules whatwg/html#4315
• You can use package.main to set an entry point for a module
  • the file extensions used in main will be resolved based on the type of the module

—

Did I miss anything?

[aduh95]

this changes the default file extension solution, specifically what .js should be considered

I guess that also changes behavior for extension-less files, right?

[GeoffreyBooth]

I would mention --type next to "type", and bump .cjs down. Also there’s no context for why .cjs is needed, so it seems a bit arbitrary. You could copy the text from the announcement post.

Other new things per the post are:

• import no longer supports JSON (without the new flag) and no longer supports native modules.
• package.main can point to an ES module package entry point; dual packages are not currently supported.

[evanplaice]

Did I miss anything?

Was there ever a consensus on handling hashbang entry points? Is there going to be a node-esm alias for convenience.

[guybedford]

Approved FWIW :)

Should we link to the work-in-progress blog post as part of the PR to give background? I feel like bullets don't exactly give the entire process justice.

Perhaps also mention the --es-module-specifier-resolution flag is experimental while we determine what the default behaviour will be, as opposed to the flag itself being the feature.

[MylesBorins]

updated ptal

[GeoffreyBooth]

It still doesn’t mention that native modules are unsupported in import, and that dual packages are unsupported. Not sure those need to be mentioned. LGTM.

[MylesBorins]

Have now incorporated all fixes from from Q/A

CI: https://ci.nodejs.org/job/node-test-pull-request/21582/

[MylesBorins]

Updated copy for PR message. PTAL

[GeoffreyBooth]

I fixed some missing backticks and other very minor formatting. LGTM.

[MylesBorins]

I've finished incorporating all of @guybedford's suggested changes and rebasing the branch to be pristine. Each individual commit passes the test suite, so this is IMHO ready to upstream.

CI: https://ci.nodejs.org/job/node-test-pull-request/21625/

Once CI is green I'll be opening this PR, ETA 2 - 3 hours

[MylesBorins]

landed in modules-lkgr in 969c63a...484d1fb

upstream PR incoming