This repository has been archived by the owner on Sep 2, 2023. It is now read-only.
Rewrite readme #482
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -2,75 +2,64 @@ | |||||||||||||||||
|
|
||||||||||||||||||
| ## Purpose | ||||||||||||||||||
|
|
||||||||||||||||||
| The Node.js Modules Team maintains and actively develops the ECMAScript Modules (ESM) implementation in Node.js core. | ||||||||||||||||||
|
|
||||||||||||||||||
| Work includes: | ||||||||||||||||||
|
|
||||||||||||||||||
| * ESM loader implementation | ||||||||||||||||||
| * ESM specifier resolution | ||||||||||||||||||
| * Loader hooks | ||||||||||||||||||
| * ESM and CommonJS interoperability | ||||||||||||||||||
| * Node.js and browser interoperability | ||||||||||||||||||
| * VM modules implementation | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Current Efforts | ||||||||||||||||||
|
|
||||||||||||||||||
| ### To Do / In Progress | ||||||||||||||||||
|
There was a problem hiding this comment. To be very blunt then, since you have asked me to be, I simply do not think this content is suitable for our readme. Since it is rapidly changing, likely to get out of date, and not the right information for someone "interested in the Node.js modules group". As said before, I think we should separate this out into There was a problem hiding this comment. Latest commit in my PR to this branch may be what you're after. There was a problem hiding this comment.
Would it be better to have something like a project board for the roadmap? So it can properly link to issues/PRs, including automatic status updates as things get closed? There was a problem hiding this comment. @jkrems, the argument against that approach, which was brought up to me when I proposed the exact same idea to @GeoffreyBooth, is that these things need to be archivable and a more-static public record of them needs to be kept. |
||||||||||||||||||
|
|
||||||||||||||||||
| * [Loader hooks](https://nodejs.org/api/esm.html#esm_hooks) (work in progress). The goal is to create hooks that provide enough functionality to enable users to build loaders that can achieve many of the remaining [features](./doc/features.md) we hope to support. | ||||||||||||||||||
| - Overview: https://github.com/nodejs/modules/issues/351. | ||||||||||||||||||
| - A [design](https://github.com/nodejs/node/pull/30986) that enables [transpilation](https://github.com/nodejs/modules/issues/96) and [arbitrary sources](https://github.com/nodejs/modules/issues/97) and [specifier customization](https://github.com/nodejs/modules/issues/110) shipped in Node 13.7.0. | ||||||||||||||||||
| - **Status**: Work remains to be done to support further use cases including [code coverage/instrumentation](https://github.com/nodejs/modules/issues/95) and [mocks/stubs](https://github.com/nodejs/modules/issues/98). | ||||||||||||||||||
|
|
||||||||||||||||||
| * [WASM modules](https://nodejs.org/api/esm.html#esm_experimental_wasm_modules) (work in progress). | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Wish List (Blocked) | ||||||||||||||||||
|
|
||||||||||||||||||
| * Named exports for CommonJS modules, e.g. `import { shuffle } from 'cjs-pkg'` in addition to the currently supported `import _ from 'cjs-pkg'`. | ||||||||||||||||||
| - Overview: https://github.com/nodejs/modules/issues/264. | ||||||||||||||||||
| - Discussion: https://github.com/nodejs/modules/issues/448. | ||||||||||||||||||
| - Proposal: https://github.com/nodejs/modules/issues/252. | ||||||||||||||||||
| - **Status**: As far as we can tell, currently there is no spec-compliant way to achieve this. | ||||||||||||||||||
|
|
||||||||||||||||||
| CommonJS is not statically analyzable (that’s one of the primary benefits of `import`/`export` syntax) and therefore the exported names cannot be known to Node.js simply by parsing JavaScript source code: the code needs to actually be evaluated in order for Node.js to discover what identifiers get attached to `module.exports` for each file. But evaluating the CommonJS code in what the ECMAScript Modules spec calls the “linking” phase (when the module graph is determined) is not permitted; this would mean that CommonJS code is evaluated early, before any ES module code, whereas the spec defines the order of modules’ evaluation based on the depth of imports. This early evaluation presents other issues in that if a dependency gets converted from CommonJS to ESM, its order of evaluation would change in the user’s application; and early evaluation might trigger side effects if reading the values from `module.exports` were getters or proxies. | ||||||||||||||||||
|
There was a problem hiding this comment.
This is a separate point that isn't about early evaluation. This is specifically about There was a problem hiding this comment. Can you please rephrase the text so that it’s correct? Maybe offer a suggestion? There was a problem hiding this comment.
Suggested change
|
||||||||||||||||||
|
|
||||||||||||||||||
| A [“dynamic modules” proposal](https://github.com/nodejs/modules/issues/252) was created and presented to TC39, the standards body responsible for the ECMAScript Modules spec. This was a proposal to allow new export names to be discovered during the execution phase, which happens after linking. This made named exports from CommonJS work, but had the caveat that `export *` would not be supported for CommonJS sources. Without a solution for this edge case, TC39 deemed the proposal inadequate. There are currently no other proposals in development to try to surmount these obstacles. | ||||||||||||||||||
|
|
||||||||||||||||||
| The approach taken by the [`standard-things/esm`](https://github.com/standard-things/esm) package is to transpile ES module sources into CommonJS on the fly, and have Node.js evaluate the CommonJS sources. This is not considered a viable option for Node.js because it means that the actual source code being executed by the V8 JavaScript engine is not the code that the user wrote. | ||||||||||||||||||
|
|
||||||||||||||||||
| * `require` of ES modules: Support using `require` (in addition to `import()`) to load ES modules into a CommonJS context. | ||||||||||||||||||
| - Discussion: https://github.com/nodejs/modules/issues/299. | ||||||||||||||||||
| - PR: https://github.com/nodejs/node/pull/30891. | ||||||||||||||||||
| - **Status**: Blocked due to various issues discussed in https://github.com/nodejs/modules/issues/454. | ||||||||||||||||||
|
|
||||||||||||||||||
| ### Not Planned | ||||||||||||||||||
|
|
||||||||||||||||||
| * Limited module type detection. | ||||||||||||||||||
| - PR: https://github.com/nodejs/ecmascript-modules/pull/69. | ||||||||||||||||||
| - Upstream PR: https://github.com/nodejs/node/pull/27808. | ||||||||||||||||||
| - **Status**: The group’s current thinking is to encourage explicit source type definition via file extension or the `"type"` field. Source type detection via parsing source code is not 100% accurate and should therefore be left to userland where users can choose to accept its risks. | ||||||||||||||||||
|
|
||||||||||||||||||
| * Provide a way to make ESM the default instead of CommonJS. | ||||||||||||||||||
| - Discussion: https://github.com/nodejs/modules/issues/318. | ||||||||||||||||||
| - Proposal: https://github.com/nodejs/modules/issues/335. | ||||||||||||||||||
| - **Status**: Currently one can add `--input-type=module` to `NODE_OPTIONS` to flip the default for `--input-type`; at the moment the group is deciding not to pursue providing an ability to flip the default for the `package.json` `type` field. We instead want to encourage all packages, both ESM and CommonJS, to include an explicit `type` field; leaving it out and relying on a default is something we want to discourage. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Archives | ||||||||||||||||||
|
|
||||||||||||||||||
| - **[Features](./doc/archive/features.md)**: As part of creating the ECMAScript Modules implementation for Node.js 12.0.0, [use cases](./doc/use-cases.md) were brainstormed, which led to a list of features. This feature list, which previously existed as a section in this repo's root README, informed what became the [plan for the implementation](./doc/archive/plan-for-new-modules-implementation.md). | ||||||||||||||||||
|
|
||||||||||||||||||
| - **[Plan for New Modules Implementation](./doc/archive/plan-for-new-modules-implementation.md)**: This document summarized the work that went into the new ECMAScript Modules implementation that shipped in Node.js 12.0.0. | ||||||||||||||||||
|
|
||||||||||||||||||
| ## Members | ||||||||||||||||||
|
|
||||||||||||||||||
|
|
||||||||||||||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| > _This document has been archived._ | ||
| > | ||
| > As part of creating the ECMAScript Modules implementation for Node.js 12.0.0, use cases were brainstormed, which led to a list of features. This feature list, which previously existed as a section in this repo's root [README](../../README.md), informed what became the [plan for the implementation](./plan-for-new-modules-implementation.md). | ||
|
|
||
| # Features | ||
|
|
||
| Based on [these use cases](./doc/use-cases.md) ([#55](https://github.com/nodejs/modules/issues/55)), our implementation aims to support the following features (subject to change): | ||
|
|
||
| ### Baseline Modules Implementation Features: | ||
| * Spec compliance ([#132](https://github.com/nodejs/modules/issues/132)) | ||
| * Browser equivalence ([#133](https://github.com/nodejs/modules/issues/133)) | ||
| * Don’t break CommonJS ([#112](https://github.com/nodejs/modules/issues/112)) | ||
| * No refactoring ([#87](https://github.com/nodejs/modules/issues/87)) | ||
|
|
||
| #### Browser Interop: | ||
| * Browser and Node compatibility without building ([#107](https://github.com/nodejs/modules/issues/107)) | ||
| * Browser-compatible specifier resolution ([#109](https://github.com/nodejs/modules/issues/109)) | ||
| * Browser-compatible builds for ESM and CommonJS ([#108](https://github.com/nodejs/modules/issues/108)) | ||
|
|
||
| #### CommonJS Interop: | ||
| * Named exports when importing CJS ([#81](https://github.com/nodejs/modules/issues/81)) | ||
| * Multi-mode packages ([#94](https://github.com/nodejs/modules/issues/94)) | ||
| * Transparent interoperability for ESM importing CommonJS ([#100](https://github.com/nodejs/modules/issues/100)) | ||
| * Consumer-agnostic imports ([#105](https://github.com/nodejs/modules/issues/105)) | ||
| * Mixed module types within app/module; gradual migration from CommonJS to ESM ([#99](https://github.com/nodejs/modules/issues/99)) | ||
| * ESM in .js files ([#151](https://github.com/nodejs/modules/issues/151)) | ||
|
|
||
| ### Existing Node.js Utility Features: | ||
|
|
||
| * Importing non-JavaScript files ([#115](https://github.com/nodejs/modules/issues/115)) | ||
| * NodeJS contextual pathing use cases ([#121](https://github.com/nodejs/modules/issues/121)) | ||
| * ESM in executable files ([#152](https://github.com/nodejs/modules/issues/152)) | ||
| * Callable resolver ([#157](https://github.com/nodejs/modules/issues/157)) | ||
|
|
||
| ### Loader Features: | ||
|
|
||
| * Code coverage/instrumentation ([#95](https://github.com/nodejs/modules/issues/95)) | ||
| * Pluggable Loaders to support multiple use cases ([#82](https://github.com/nodejs/modules/issues/82)) | ||
| * Runtime loaders, transpilation at import time ([#96](https://github.com/nodejs/modules/issues/96)) | ||
| * Arbitrary sources for module source text ([#97](https://github.com/nodejs/modules/issues/97)) | ||
| * Mock modules (injection) ([#98](https://github.com/nodejs/modules/issues/98)) | ||
| * Specifier resolution customization ([#110](https://github.com/nodejs/modules/issues/110)) | ||
| * Package encapsulation ([#111](https://github.com/nodejs/modules/issues/111)) | ||
| * Conditional imports ([#113](https://github.com/nodejs/modules/issues/113)) | ||
|
|
||
| ### WASM Features: | ||
|
|
||
| * WASM modules (#[106](https://github.com/nodejs/modules/issues/106)) | ||
|
|
||
| ### Developer and Tooling Features: | ||
|
|
||
| * File / path / URL resolving (#[103](https://github.com/nodejs/modules/issues/103)) | ||
| * Import CommonJS without needing asynchronous syntax (#[116](https://github.com/nodejs/modules/issues/116)) | ||
| * Tree shaking (#[102](https://github.com/nodejs/modules/issues/102)) | ||
| * Polyfillability (#[101](https://github.com/nodejs/modules/issues/101)) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It would be nice if we could include a
Current Statussection before all the experimental / new stuff, that captures what the group has already achieved.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It sounds like a good idea, I'm just a bit unclear on what you have in mind. What would the different statuses be? Here's an idea I had for displaying different statuses of various features, it might be similar to what you're after.