From a40b8a9ad50c3921f22d75bf14f9e25f1193a282 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Wed, 12 Sep 2018 16:13:40 -0400 Subject: [PATCH 1/6] doc: first pass at minimal-kernel Refs: https://github.com/nodejs/modules/issues/166 --- doc/minimal-kernel.md | 44 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 doc/minimal-kernel.md diff --git a/doc/minimal-kernel.md b/doc/minimal-kernel.md new file mode 100644 index 0000000..8bb90d4 --- /dev/null +++ b/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 + +# 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. + +# What is our minimal kernel + +* both browser + node need bare imports + - implementation to be discussed +* we cannot have dynamic path searching + - requiring the full path is an issue for tooling and a long term solution is required + - migration strategies also have issue with this +* common.js backwards compat + - createRequireFunction does + - import.meta.require does not fail early enough + - 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 + - no JSON + - no native modules + - createRequireFunction used to get these + - will come back with format database +* import.meta.url +* dynamic import + +# How will we get from where we are to the minimal kernel + +* removing importing of formats other than ESM + - no common.js + - no JSON + - no native modules + - implemented in https://github.com/nodejs/ecmascript-modules/pull/3 +* removing of dynamic path searching + - no extension adding + - no directory resolution + - no support for index.js + - still maintaining support for the main field + - implemented in https://github.com/nodejs/ecmascript-modules/pull/2 +* adding createRequireFunction + - implemented in https://github.com/nodejs/node/pull/19360 From aa9a20b1812901d4d858dd7bb556a736ed95b2a6 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Thu, 20 Sep 2018 12:43:42 -0700 Subject: [PATCH 2/6] Edit of minimal kernel doc (#2) * 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. --- doc/minimal-kernel.md | 44 ------------------- doc/plan-for-new-modules-implementation.md | 50 ++++++++++++++++++++++ 2 files changed, 50 insertions(+), 44 deletions(-) delete mode 100644 doc/minimal-kernel.md create mode 100644 doc/plan-for-new-modules-implementation.md diff --git a/doc/minimal-kernel.md b/doc/minimal-kernel.md deleted file mode 100644 index 8bb90d4..0000000 --- a/doc/minimal-kernel.md +++ /dev/null @@ -1,44 +0,0 @@ -# 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 - -# 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. - -# What is our minimal kernel - -* both browser + node need bare imports - - implementation to be discussed -* we cannot have dynamic path searching - - requiring the full path is an issue for tooling and a long term solution is required - - migration strategies also have issue with this -* common.js backwards compat - - createRequireFunction does - - import.meta.require does not fail early enough - - 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 - - no JSON - - no native modules - - createRequireFunction used to get these - - will come back with format database -* import.meta.url -* dynamic import - -# How will we get from where we are to the minimal kernel - -* removing importing of formats other than ESM - - no common.js - - no JSON - - no native modules - - implemented in https://github.com/nodejs/ecmascript-modules/pull/3 -* removing of dynamic path searching - - no extension adding - - no directory resolution - - no support for index.js - - still maintaining support for the main field - - implemented in https://github.com/nodejs/ecmascript-modules/pull/2 -* adding createRequireFunction - - implemented in https://github.com/nodejs/node/pull/19360 diff --git a/doc/plan-for-new-modules-implementation.md b/doc/plan-for-new-modules-implementation.md new file mode 100644 index 0000000..e5382f2 --- /dev/null +++ b/doc/plan-for-new-modules-implementation.md @@ -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. + - 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. From 3632b6a623ccc006fb730773c30431a601b41cd4 Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Tue, 2 Oct 2018 01:43:23 -0400 Subject: [PATCH 3/6] fixup: update to point to new pr --- doc/plan-for-new-modules-implementation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/plan-for-new-modules-implementation.md b/doc/plan-for-new-modules-implementation.md index e5382f2..8668ac2 100644 --- a/doc/plan-for-new-modules-implementation.md +++ b/doc/plan-for-new-modules-implementation.md @@ -36,14 +36,13 @@ These features will be part of the first phase of development: - 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. - - Implemented in https://github.com/nodejs/ecmascript-modules/pull/2 +These changes are implemented in https://github.com/nodejs/ecmascript-modules/pull/6 ## Later Phases From 8bf0a5aaad01bcd006c9f8579a6dd7123b1abede Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Tue, 2 Oct 2018 01:44:30 -0400 Subject: [PATCH 4/6] fixup: minor tweaks --- doc/plan-for-new-modules-implementation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/plan-for-new-modules-implementation.md b/doc/plan-for-new-modules-implementation.md index 8668ac2..f3d5ce7 100644 --- a/doc/plan-for-new-modules-implementation.md +++ b/doc/plan-for-new-modules-implementation.md @@ -21,7 +21,7 @@ These features will be part of the first phase of development: * `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. + - No JSON or native modules; `createRequireFromPath` can be used to get these. * `import.meta.url`. - Already in the existing implementation. @@ -29,7 +29,6 @@ These features will be part of the first phase of development: * 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: From b50ad7eede44cbff4a3b9adf07be9c047ef5aa3a Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Wed, 3 Oct 2018 11:16:25 -0400 Subject: [PATCH 5/6] fixup: remove vm + loader as per jdd --- doc/plan-for-new-modules-implementation.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/plan-for-new-modules-implementation.md b/doc/plan-for-new-modules-implementation.md index f3d5ce7..c4b41c1 100644 --- a/doc/plan-for-new-modules-implementation.md +++ b/doc/plan-for-new-modules-implementation.md @@ -40,6 +40,10 @@ These features will be part of the first phase of development: - No extension adding. - No directory resolution, including no support for `index.js` or `index.mjs`. - No support for `main` field for ESM. + +* Remove current VM implementation + +* Remove current Loader implementation These changes are implemented in https://github.com/nodejs/ecmascript-modules/pull/6 From efa87ef93eaf31be0a1aee7307f61d8665ef7eae Mon Sep 17 00:00:00 2001 From: Myles Borins Date: Wed, 3 Oct 2018 12:06:54 -0400 Subject: [PATCH 6/6] fixup: explicitly mention builtins --- doc/plan-for-new-modules-implementation.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/plan-for-new-modules-implementation.md b/doc/plan-for-new-modules-implementation.md index c4b41c1..fd0ce14 100644 --- a/doc/plan-for-new-modules-implementation.md +++ b/doc/plan-for-new-modules-implementation.md @@ -29,6 +29,9 @@ These features will be part of the first phase of development: * Dynamic `import()`. - Already in the existing implementation. +* Support for built-in modules with named exports + - 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: