Skip to content

Edit of minimal kernel doc #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Sep 20, 2018
Merged

Edit of minimal kernel doc #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
79d8fff
Rewrite: emphasize that minimal kernel is just the first phase of a m…
GeoffreyBooth Sep 14, 2018
6148b83
Revisions per Myles' notes
GeoffreyBooth Sep 14, 2018
7392f9f
Move up features that are already part of the existing implementation
GeoffreyBooth Sep 17, 2018
d79cad9
Don't name formats
GeoffreyBooth Sep 17, 2018
1ec5469
Remove specific later phases plans
GeoffreyBooth Sep 17, 2018
7597e0b
some minor changes to satisfy myles
MylesBorins Sep 20, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 0 additions & 44 deletions doc/minimal-kernel.md
View file
Open in desktop

This file was deleted.

50 changes: 50 additions & 0 deletions doc/plan-for-new-modules-implementation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# Plan for New Modules Implementation

This document outlines the plan for building a new implementation to support ECMAScript modules in Node.js. The general idea is to start with a “minimal kernel” as Phase 1, which consists of features that the @nodejs/modules group have agreed will be necessary for all potential iterations of our ESM implementation. Phase 1 does _not_ include features that preclude other potential features or implementation approaches; and Phase 1 also does not include some features that should naturally be built in a later phase of development, for example because those features depend on features planned for Phase 1. The minimal kernel/phase 1 is _not_ intended to be merged into Node core or released; it is only a starting point for gradually building layers of consensus.

At every phase, the following standards must be maintained:

* Spec compliance ([#132](https://github.com/nodejs/modules/issues/132)): We must always follow the ES spec.
* Browser equivalence ([#133](https://github.com/nodejs/modules/issues/133)): There’s room for debate in specific cases, but in general if Node is doing something that browsers also do, Node should do it in the same way. Alternatively, code that executes in both environments should produce identical results.
* Don’t break CommonJS ([#112](https://github.com/nodejs/modules/issues/112)): We cannot cause breaking changes with regards to CommonJS.

See also the [features list in the README](https://github.com/nodejs/modules#features).

## Phase 1: The Minimal Kernel

These features will be part of the first phase of development:

* `module.createRequireFromPath` ([nodejs/node#19360](https://github.com/nodejs/node/pull/19360)) is the only way to import CommonJS into an ES module, for now.
- `import.meta.require` fails at runtime as opposed to import time. This is not desireable to all committee members
- Hold off on `import` statements for CommonJS until more progress is made on the dynamic modules spec.
- landed in https://github.com/nodejs/node/commit/246f6332e5a5f395d1e39a3594ee5d6fe869d622

* `import` statements will only support files with an `.mjs` extension, and will import only ES modules, for now.
- In a later phase, the intention is to move forward with format databases to map extensions and support multiple use cases.
- No JSON or native modules; `createRequireFunction` can be used to get these.

* `import.meta.url`.
- Already in the existing implementation.

* Dynamic `import()`.
- Already in the existing implementation.


### How will we get from where we are to Phase 1

* Remove support in the `import` statement of formats other than ESM:
- No CommonJS.
- No JSON.
- No native modules.
- Implemented in https://github.com/nodejs/ecmascript-modules/pull/3

* Remove dynamic path searching:
- No extension adding.
- No directory resolution, including no support for `index.js` or `index.mjs`.
- No support for `main` field for ESM.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was not part of the initial decision on the minimal kernel. Have real mixed feelings about removing this, but can understand why we may not want to make this decision right now, especially if we are going to use another keyword. I'd rather punt this conversation to review on the original PR rather than making the decision here

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Have real mixed feelings about removing this

I put this here because I was assuming there would be no bare imports resolution algorithm of any kind (not require‘s algorithm nor package name maps) in Phase 1. If there are no bare imports in Phase 1, of what use is a main field?

Don’t be like everyone else concerned that their priority isn’t part of the minimal kernel. 😄 Obviously we’ll have some way to do bare imports in the final implementation. It doesn’t need to be in Phase 1, and probably shouldn’t, since figuring it out will take a lot of discussion. I think it’s more important to show progress and get a Phase 1 nailed down than get sidetracked on bare imports for weeks.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

bare imports + main is not the require algorithm.

This was what was discussed and in the original document. From the conversation we initially had (me + @bmeck + @guybedford) it was discussed that any implementation, including the browsers, would require bare imports to be useful. A practical argument against this for right now is that we don't have consensus for main, so it would make sense to potentially drop.

Don’t be like everyone else concerned that their priority isn’t part of the minimal kernel.

I see where you are coming from this but don't find this particular kind of rhetoric helpful or productive. Say what you need to say from a technical stand point and don't make it personal.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it was discussed that any implementation, including the browsers, would require bare imports to be useful

Of course it would. But again, we’re not shipping Phase 1, are we? So Phase 1 doesn’t need to be useful in a technical sense. Phase 1 will be useful that it will start to establish consensus and show that we can make forward progress, and give people a starting point for further PRs. There absolutely is value in pulling together a single commit on the repo that does that, even if it lacks support for huge obvious use cases that we all agree need to be covered in a final release.

I think “whatever we can merge together right now without needing further debate” is a good dividing line for what goes into Phase 1 versus later on. And if Phase 1 is incomplete technically, that’s all the better, in that it reassures everyone that there will be later phases.

Copy link

@michael-ciniawsky michael-ciniawsky Sep 17, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Supporting th main field for ESM at this point doesn't make a lot of sense in my point of view since 99.9% of existing main fields are CJS and one would have to explicitly write an ESM package to make it work, which I hope isn't the final intend. It's very confusing and in the worst case leads to folks starting to publish name-esm packages for 'testing proposes or 'because that's what node does now'. pkg.module is already a thing for tooling and while it shouldn't be final to support it in the future it would definitely be sufficient for testing atm. Otherwise it's better to not support anything related to package.json and the NRA (Node Resolution Algorithm) in the first iteration of the minimal kernel (for ESM)

- Implemented in https://github.com/nodejs/ecmascript-modules/pull/2


## Later Phases

There **will** be future phases. We will **not** ship the code produced by Phase 1. This first phase lacks support for important use cases and will not be released as the new modules implementation.