doc: first pass at minimal-kernel #180

MylesBorins · 2018-09-12T20:22:03Z

Decided to submit this as a PR to comment and land as documentation.

Thoughts?

doc/minimal-kernel.md

+* removing importing of formats other than ESM
+  - no common.js
+  - no JSON
+  - no nativemodules


doc/minimal-kernel.md

+  - no nativemodules
+* removing of dynamic path searching
+  - no extension adding
+  - no directory resolution


Refs: nodejs#166

MylesBorins · 2018-09-12T21:56:37Z

updated based on feedback.

Biggest changes

expand minimal kernel
- added dynamic import
- added import.meta.url
documented PRs that implement the kernel

doc/minimal-kernel.md

+
+# Why build a Minimal Kernel?
+
+Having a minimal kernel creates a subset that we can build consensus on top of. It will also allow sharing features across proposals that potentially have different end goals and feature sets. Finally, reaching consensus on a minimal kernel is a win for the team, showing that we do indeed have a layer of consensus even if it is not entirely clear.


doc/minimal-kernel.md

+
+* both browser + node need bare imports
+  - implementation to be discussed
+* we cannot have dynamic path searching


doc/minimal-kernel.md

+  - hold off on importing common.js until more progress is made on dynamic modules spec
+* .mjs will be the only way to import ESM
+  - intention is to move forward with format databases to map extensions and support multiple use cases
+* only supporting importing ESM


mcollina

LGTM with a nit

doc/minimal-kernel.md

@@ -0,0 +1,44 @@
+# What is a Minimal Kernel for ESM in Node.js?
+
+A minimal kernel is a subset of features that the @nodejs/modules group have agreed will be necessary for all potential iterations of our ESM implementation. It strips out any features that preclude other features 


doc/minimal-kernel.md

+  - migration strategies also have issue with this
+* common.js backwards compat
+  - createRequireFunction does
+  - import.meta.require does not fail early enough


* Rewrite: emphasize that minimal kernel is just the first phase of a multistage process, add more features and more links to features, use complete sentences.

MylesBorins · 2018-09-20T19:47:03Z

Updated significantly based on feedback I received from @GeoffreyBooth

As such I'm dismissing all current reviews. PTAL

Significant changes since review

guybedford

Seems very clear, nice work.

GeoffreyBooth · 2018-09-20T21:22:04Z

Rich-formatted version: https://github.com/nodejs/modules/blob/aa9a20b1812901d4d858dd7bb556a736ed95b2a6/doc/plan-for-new-modules-implementation.md

Thanks @MylesBorins

SMotaal · 2018-09-21T22:53:10Z

Amazing!

mcollina

LGTM

doc/plan-for-new-modules-implementation.md

+
+* `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.


Refs: nodejs/modules#180

Refs: nodejs/modules#180 PR-URL: #6 PR-URL: #12 Co-authored-by: Myles Borins <MylesBorins@google.com> Co-authored-by: John-David Dalton <john.david.dalton@gmail.com>

Refs: https://github.com/GeoffreyBooth/node-import-file-specifier-resolution-proposal Refs: nodejs/modules#180 Refs: #6 Refs: #12 Refs: #28 Co-authored-by: Myles Borins <MylesBorins@google.com> Co-authored-by: John-David Dalton <john.david.dalton@gmail.com>

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. 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 * `--entry-type=[mode]` - allows you set the type on 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 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 Refs: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md Refs: https://github.com/GeoffreyBooth/node-import-file-specifier-resolution-proposal Refs: nodejs/modules#180 Refs: nodejs/ecmascript-modules#6 Refs: nodejs/ecmascript-modules#12 Refs: nodejs/ecmascript-modules#28 Refs: nodejs/modules#255 Refs: whatwg/html#4315 Refs: WICG/webcomponents#770 Co-authored-by: Myles Borins <MylesBorins@google.com> Co-authored-by: John-David Dalton <john.david.dalton@gmail.com> Co-authored-by: Evan Plaice <evanplaice@gmail.com> Co-authored-by: Geoffrey Booth <webmaster@geoffreybooth.com> Co-authored-by: Michaël Zasso <targos@protonmail.com> PR-URL: nodejs#26745 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

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. 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 * `--entry-type=[mode]` - allows you set the type on 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 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 Refs: https://github.com/nodejs/modules/blob/master/doc/plan-for-new-modules-implementation.md Refs: https://github.com/GeoffreyBooth/node-import-file-specifier-resolution-proposal Refs: nodejs/modules#180 Refs: nodejs/ecmascript-modules#6 Refs: nodejs/ecmascript-modules#12 Refs: nodejs/ecmascript-modules#28 Refs: nodejs/modules#255 Refs: whatwg/html#4315 Refs: WICG/webcomponents#770 Co-authored-by: Myles Borins <MylesBorins@google.com> Co-authored-by: John-David Dalton <john.david.dalton@gmail.com> Co-authored-by: Evan Plaice <evanplaice@gmail.com> Co-authored-by: Geoffrey Booth <webmaster@geoffreybooth.com> Co-authored-by: Michaël Zasso <targos@protonmail.com> PR-URL: #26745 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Guy Bedford <guybedford@gmail.com> Reviewed-By: Ben Coe <bencoe@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de> Reviewed-By: Сковорода Никита Андреевич <chalkerx@gmail.com>

MylesBorins force-pushed the minimal-kernel branch from 6569081 to 2cb7451 Compare Sep 12, 2018

MylesBorins mentioned this pull request Sep 12, 2018

Managing fork and agreed upon minimal kernel #166

Closed

michael-ciniawsky reviewed Sep 12, 2018

View changes

MylesBorins force-pushed the minimal-kernel branch from 2cb7451 to 6f3f5c9 Compare Sep 12, 2018

doc: first pass at minimal-kernel

a40b8a9

Refs: nodejs#166

MylesBorins force-pushed the minimal-kernel branch from 6f3f5c9 to a40b8a9 Compare Sep 12, 2018

ljharb reviewed Sep 12, 2018

View changes

guybedford previously approved these changes Sep 13, 2018

View changes

mcollina previously approved these changes Sep 14, 2018

View changes

Edit of minimal kernel doc (#2)

aa9a20b

* Rewrite: emphasize that minimal kernel is just the first phase of a multistage process, add more features and more links to features, use complete sentences.

guybedford approved these changes Sep 20, 2018

View changes

targos approved these changes Sep 22, 2018

View changes

mcollina approved these changes Sep 22, 2018

View changes

jkrems approved these changes Sep 22, 2018

View changes

MylesBorins added the modules-agenda To be discussed in a meeting label Sep 25, 2018

MylesBorins mentioned this pull request Sep 25, 2018

Node.js Foundation Modules Team Meeting 2018-09-26 #187

Closed

SimenB mentioned this pull request Sep 28, 2018

[babel-jest] mjs files facebook/jest#4637

Closed

MylesBorins added a commit to nodejs/ecmascript-modules that referenced this pull request Oct 2, 2018

esm: remove .js support

7e5aba7

Refs: nodejs/modules#180

GeoffreyBooth removed modules-agenda To be discussed in a meeting labels May 9, 2019

doc: first pass at minimal-kernel #180

doc: first pass at minimal-kernel #180

MylesBorins commented Sep 12, 2018

This comment was marked as off-topic.

This comment was marked as off-topic.

MylesBorins commented Sep 12, 2018

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

mcollina left a comment

This comment was marked as off-topic.

This comment was marked as off-topic.

MylesBorins commented Sep 20, 2018

guybedford left a comment

GeoffreyBooth commented Sep 20, 2018

SMotaal commented Sep 21, 2018

mcollina left a comment

This comment was marked as off-topic.

This comment was marked as off-topic.


		# Why build a Minimal Kernel?

		Having a minimal kernel creates a subset that we can build consensus on top of. It will also allow sharing features across proposals that potentially have different end goals and feature sets. Finally, reaching consensus on a minimal kernel is a win for the team, showing that we do indeed have a layer of consensus even if it is not entirely clear.

		@@ -0,0 +1,44 @@
		# What is a Minimal Kernel for ESM in Node.js?

		A minimal kernel is a subset of features that the @nodejs/modules group have agreed will be necessary for all potential iterations of our ESM implementation. It strips out any features that preclude other features

doc: first pass at minimal-kernel #180

doc: first pass at minimal-kernel #180

Conversation

MylesBorins commented Sep 12, 2018

This comment was marked as off-topic.

This comment was marked as off-topic.

MylesBorins commented Sep 12, 2018

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

This comment was marked as off-topic.

mcollina left a comment

This comment was marked as off-topic.

This comment was marked as off-topic.

MylesBorins commented Sep 20, 2018

guybedford left a comment

GeoffreyBooth commented Sep 20, 2018

SMotaal commented Sep 21, 2018

mcollina left a comment

This comment was marked as off-topic.

This comment was marked as off-topic.