From c4413e353a2c99a5f1e4150d7e114e7f6ce3d3be Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 12:28:01 -0600 Subject: [PATCH 01/31] initial GOALS declaration --- GOALS.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 GOALS.md diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 0000000..4c8c38d --- /dev/null +++ b/GOALS.md @@ -0,0 +1,54 @@ +# Goals + +1. Enable use of ESM in Node without requiring a flag +2. Enable a future where ESM is the default module system across JS environments +3. Have files not collide between module systems or be ambiguous in nature +4. Define a path to write code that runs in both Node and the Browser without a preprocessing step + 1. Define what a preprocessing step is + 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other +5. Define a path to write code that runs in Node versions supporting ESM and in Node versions that do not support ESM +6. Be standards compliant in the nature of our loading of ESM + 1. If not standards compliant by default, have standards compliant form possible +7. Support developer centric workflows for: + 1. Mocking modules + 2. APM integration + 3. Multiple distributions of both ESM and CJS in the same package + 4. Creation of userland module systems (JSDOM) +8. 100% backwards compatibility with existing CJS code bases if left unchanged + +# Non-Goals + +1. Use `.js` file extension for both CJS and ESM without a disambiguation mechanism +2. Interoperability of Module formats with environments that do not support Module formats that Node seeks to support +3. Forwards compatibility support for the transition of existing packages from CJS to ESM + 1. loading unknown file formats and `.js` as CJS + 2. usage of `require.extensions` + 3. usage of `require.cache` + 4. usage of `NODE_PATH`, `~/.node_libraries`, `~/.node_modules`, and `$PREFIX/lib/node` +4. Direct integration with APMs +5. Direct integration with testing libraries +6. Direct integration with transpilers +7. Direct integration with browser stacks +8. Direct integration with package managers + +# Goals that are not expected for the first iteration + +1. 100% stable Loader APIs +2. Treatment of `.js` file extension as ESM by default +3. Support for the following URL schemes: `data:`, `blob:`, and `https:` + +# Direction + +* Build upon the existing work in Node that has designs around using `.mjs` +* Enable usage of `.js` for ESM through compatible means such as package.json flags +* Build upon the existing Loader hooks to aid usability + * Creation of in memory Module records + * Composition of Loaders + * Find a solution to the live-ness problem + * Discuss issues/benefits around static vs dynamic mutation of loader hooks + +# Forwards compatibility concerns + +* Interoperability with browser support for more module formats +* Resource integrity checks +* Scaling of more JS goals and out of band flags From 642a2cf1eeaf9366df15569271fb5a5705d59df5 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 13:20:20 -0600 Subject: [PATCH 02/31] updates --- GOALS.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/GOALS.md b/GOALS.md index 4c8c38d..226af6c 100644 --- a/GOALS.md +++ b/GOALS.md @@ -1,20 +1,19 @@ # Goals 1. Enable use of ESM in Node without requiring a flag -2. Enable a future where ESM is the default module system across JS environments -3. Have files not collide between module systems or be ambiguous in nature -4. Define a path to write code that runs in both Node and the Browser without a preprocessing step +2. Have files be unable collide between module systems +3. Define a path to write code that runs in both Node and the Browser without a preprocessing step 1. Define what a preprocessing step is 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other -5. Define a path to write code that runs in Node versions supporting ESM and in Node versions that do not support ESM -6. Be standards compliant in the nature of our loading of ESM +4. Define a path to write code that runs in Node versions supporting ESM and in Node versions that do not support ESM +5. Be standards compliant in the nature of our loading of ESM 1. If not standards compliant by default, have standards compliant form possible -7. Support developer centric workflows for: +6. Support developer centric workflows for: 1. Mocking modules 2. APM integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) -8. 100% backwards compatibility with existing CJS code bases if left unchanged +7. 100% backwards compatibility with existing CJS code bases if left unchanged # Non-Goals @@ -40,7 +39,7 @@ # Direction * Build upon the existing work in Node that has designs around using `.mjs` -* Enable usage of `.js` for ESM through compatible means such as package.json flags +* Enable usage of `.js` for ESM through compatible means of out of band data * Build upon the existing Loader hooks to aid usability * Creation of in memory Module records * Composition of Loaders @@ -52,3 +51,4 @@ * Interoperability with browser support for more module formats * Resource integrity checks * Scaling of more JS goals and out of band flags +* Enable a future where ESM is the default module system across JS environments \ No newline at end of file From 1bedcb2bc6952aaf65ed25dc740da0ade17bdd32 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 13:38:08 -0600 Subject: [PATCH 03/31] libraries are main target for supporting both ESM and no ESM node targets --- GOALS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 226af6c..efdb8fd 100644 --- a/GOALS.md +++ b/GOALS.md @@ -5,7 +5,9 @@ 3. Define a path to write code that runs in both Node and the Browser without a preprocessing step 1. Define what a preprocessing step is 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other -4. Define a path to write code that runs in Node versions supporting ESM and in Node versions that do not support ESM +4. Define a path to write libraries that support being used by both + * Node versions supporting ESM + * Node versions that do not support ESM 5. Be standards compliant in the nature of our loading of ESM 1. If not standards compliant by default, have standards compliant form possible 6. Support developer centric workflows for: From 4b64cc7f6a35ae22f5f3f2cac1a785d85839f332 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 14:34:41 -0600 Subject: [PATCH 04/31] rephrase mocking to be more generic to cover variety of uses like code instrumentation / transformation as well --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index efdb8fd..e963eaa 100644 --- a/GOALS.md +++ b/GOALS.md @@ -11,7 +11,7 @@ 5. Be standards compliant in the nature of our loading of ESM 1. If not standards compliant by default, have standards compliant form possible 6. Support developer centric workflows for: - 1. Mocking modules + 1. Intercepting dependencies and replacing them 2. APM integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) From ab1acf848971a3e1fa9a239af823746b7655913e Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 15:17:23 -0600 Subject: [PATCH 05/31] platform specific APIs should be under import.meta --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index e963eaa..e5689f0 100644 --- a/GOALS.md +++ b/GOALS.md @@ -9,7 +9,7 @@ * Node versions supporting ESM * Node versions that do not support ESM 5. Be standards compliant in the nature of our loading of ESM - 1. If not standards compliant by default, have standards compliant form possible + 1. All platform specific runtime APIs exposed to ESM will be placed under `import.meta.*` 6. Support developer centric workflows for: 1. Intercepting dependencies and replacing them 2. APM integration From a97ee47d3171a7917a329482b28527a6c33ce478 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 15:20:01 -0600 Subject: [PATCH 06/31] explicitly call out WASM for forwards compat --- GOALS.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index e5689f0..8fe678a 100644 --- a/GOALS.md +++ b/GOALS.md @@ -9,7 +9,7 @@ * Node versions supporting ESM * Node versions that do not support ESM 5. Be standards compliant in the nature of our loading of ESM - 1. All platform specific runtime APIs exposed to ESM will be placed under `import.meta.*` + 1. All platform specific APIs exposed to ESM by default will be placed under `import.meta.*` 6. Support developer centric workflows for: 1. Intercepting dependencies and replacing them 2. APM integration @@ -50,6 +50,7 @@ # Forwards compatibility concerns +* Interoperability with WASM * Interoperability with browser support for more module formats * Resource integrity checks * Scaling of more JS goals and out of band flags From 2f3047e040b276e32fde6be24c718c19740a75aa Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 15:30:23 -0600 Subject: [PATCH 07/31] editorial catch --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 8fe678a..fda586c 100644 --- a/GOALS.md +++ b/GOALS.md @@ -1,7 +1,7 @@ # Goals 1. Enable use of ESM in Node without requiring a flag -2. Have files be unable collide between module systems +2. Have files be unable to collide between module systems 3. Define a path to write code that runs in both Node and the Browser without a preprocessing step 1. Define what a preprocessing step is 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other From 833c18d8b34619233817a3283f4645d904197dd0 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 16:39:22 -0600 Subject: [PATCH 08/31] APM acronym expansion --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index fda586c..51648da 100644 --- a/GOALS.md +++ b/GOALS.md @@ -12,7 +12,7 @@ 1. All platform specific APIs exposed to ESM by default will be placed under `import.meta.*` 6. Support developer centric workflows for: 1. Intercepting dependencies and replacing them - 2. APM integration + 2. Application Performance Monitoring (APM) integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) 7. 100% backwards compatibility with existing CJS code bases if left unchanged From 6e6156886e62ff280f1726651b525bee64467a44 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 16:43:45 -0600 Subject: [PATCH 09/31] call out the exact nature of scaling wrt JS spec --- GOALS.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 51648da..e0982bb 100644 --- a/GOALS.md +++ b/GOALS.md @@ -53,5 +53,7 @@ * Interoperability with WASM * Interoperability with browser support for more module formats * Resource integrity checks -* Scaling of more JS goals and out of band flags +* Preparation for introduction of more JS spec breaking changes + * new parsers added to the JS spec + * new out of band data added to the JS spec * Enable a future where ESM is the default module system across JS environments \ No newline at end of file From f075115af04d258c584bab684dfd08825b32145c Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 17:06:46 -0600 Subject: [PATCH 10/31] callout require fallback to CJS on unknown formats --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index e0982bb..734f511 100644 --- a/GOALS.md +++ b/GOALS.md @@ -20,6 +20,7 @@ # Non-Goals 1. Use `.js` file extension for both CJS and ESM without a disambiguation mechanism + * e.g. `require` falling back to CJS when it is unsure about the format of a resolved path 2. Interoperability of Module formats with environments that do not support Module formats that Node seeks to support 3. Forwards compatibility support for the transition of existing packages from CJS to ESM 1. loading unknown file formats and `.js` as CJS From 543411e51c9b041889011eb68c2bfa4f0abc231e Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 17:11:29 -0600 Subject: [PATCH 11/31] incremental migration --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index 734f511..bec36d7 100644 --- a/GOALS.md +++ b/GOALS.md @@ -15,6 +15,7 @@ 2. Application Performance Monitoring (APM) integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) + 5. Incremental code base migration from CJS to ESM 7. 100% backwards compatibility with existing CJS code bases if left unchanged # Non-Goals From d11b80fd6be73ffa4d34fc49df516a21a7092733 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 17:37:20 -0600 Subject: [PATCH 12/31] phrasing --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index bec36d7..8ed52b7 100644 --- a/GOALS.md +++ b/GOALS.md @@ -9,7 +9,7 @@ * Node versions supporting ESM * Node versions that do not support ESM 5. Be standards compliant in the nature of our loading of ESM - 1. All platform specific APIs exposed to ESM by default will be placed under `import.meta.*` + 1. Contextual module APIs exposed to ESM by default will be placed under `import.meta.*`. This does not relate to per Realm globals nor module specifier resolution. 6. Support developer centric workflows for: 1. Intercepting dependencies and replacing them 2. Application Performance Monitoring (APM) integration From ab2c16a387baffc0f1a509e638f05b59b1a69dd1 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 8 Feb 2018 17:38:33 -0600 Subject: [PATCH 13/31] Loader hook versioning callout --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index 8ed52b7..2c866ef 100644 --- a/GOALS.md +++ b/GOALS.md @@ -37,6 +37,7 @@ # Goals that are not expected for the first iteration 1. 100% stable Loader APIs + * Any Loader APIs shipped must have a forward compatible appraoch towards their usage, such as providing a feature dection mechanism or versioned API. 2. Treatment of `.js` file extension as ESM by default 3. Support for the following URL schemes: `data:`, `blob:`, and `https:` From e8a3499635223f5f6940c6eb06f54a098c2eb754 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Fri, 9 Feb 2018 08:18:35 -0600 Subject: [PATCH 14/31] rephrase "direct" --- GOALS.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/GOALS.md b/GOALS.md index 2c866ef..a71732d 100644 --- a/GOALS.md +++ b/GOALS.md @@ -28,11 +28,11 @@ 2. usage of `require.extensions` 3. usage of `require.cache` 4. usage of `NODE_PATH`, `~/.node_libraries`, `~/.node_modules`, and `$PREFIX/lib/node` -4. Direct integration with APMs -5. Direct integration with testing libraries -6. Direct integration with transpilers -7. Direct integration with browser stacks -8. Direct integration with package managers +4. Standardizing and implementing APIs that explicitly are tailored to APM +5. Standardizing and implementing APIs that explicitly are tailored to testing libraries +6. Standardizing and implementing APIs that explicitly are tailored to transpilers +7. Standardizing and implementing APIs that explicitly are tailored to browser stacks +8. Standardizing and implementing APIs that explicitly are tailored to package managers # Goals that are not expected for the first iteration From 27569a60724ceead53b2ef7d9ce0ec6eabc22115 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Sat, 10 Feb 2018 07:44:49 -0600 Subject: [PATCH 15/31] add singleton reference goal per @sokra comment on React --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index a71732d..bdcc948 100644 --- a/GOALS.md +++ b/GOALS.md @@ -17,6 +17,7 @@ 4. Creation of userland module systems (JSDOM) 5. Incremental code base migration from CJS to ESM 7. 100% backwards compatibility with existing CJS code bases if left unchanged +8. Provide a path to have singleton references that can be obtained in both module systems # Non-Goals From e8f3a575021fbed420c02190398f31fabe9b5210 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Wed, 14 Feb 2018 14:33:41 -0600 Subject: [PATCH 16/31] preface / non-goal of breaking require --- GOALS.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/GOALS.md b/GOALS.md index bdcc948..6d27b05 100644 --- a/GOALS.md +++ b/GOALS.md @@ -1,3 +1,13 @@ +# Preface: Design Principles + +These are a list of commitments that can be used to define reasons for goals existing. + +* We are committed to shipping ESM +* We are committed to ESM being first class in Node.js +* We are committed to having the Node.js and Web platform as first class runtimes for modules. +* Modules installed via npm should be able to run after installation without requiring a build step. +* We are committed to supporting our current users and offering migration paths as necessary. This can be through interoperability or APIs to improve the developer experience of working between module systems. + # Goals 1. Enable use of ESM in Node without requiring a flag @@ -34,6 +44,8 @@ 6. Standardizing and implementing APIs that explicitly are tailored to transpilers 7. Standardizing and implementing APIs that explicitly are tailored to browser stacks 8. Standardizing and implementing APIs that explicitly are tailored to package managers +9. Modification of existing `require` behavior + * Modification of implementation details is allowed only if it would be backwards compatible # Goals that are not expected for the first iteration From 09edf632ea828acbf4e2fb1bbe921dc77e642c58 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Wed, 14 Feb 2018 16:23:01 -0600 Subject: [PATCH 17/31] incremental in terms of individual files --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 6d27b05..a6dbf23 100644 --- a/GOALS.md +++ b/GOALS.md @@ -25,7 +25,7 @@ These are a list of commitments that can be used to define reasons for goals exi 2. Application Performance Monitoring (APM) integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) - 5. Incremental code base migration from CJS to ESM + 5. Incremental code base migration from CJS to ESM by migrating individual files 7. 100% backwards compatibility with existing CJS code bases if left unchanged 8. Provide a path to have singleton references that can be obtained in both module systems From 992e09e46b59bfb5f3c9bfbf1006a54c63bad26b Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 15 Feb 2018 09:29:37 -0600 Subject: [PATCH 18/31] split run on design goal --- GOALS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/GOALS.md b/GOALS.md index a6dbf23..3d75dc3 100644 --- a/GOALS.md +++ b/GOALS.md @@ -2,11 +2,12 @@ These are a list of commitments that can be used to define reasons for goals existing. -* We are committed to shipping ESM +* We are committed to shipping ES Modules (ESM) * We are committed to ESM being first class in Node.js * We are committed to having the Node.js and Web platform as first class runtimes for modules. * Modules installed via npm should be able to run after installation without requiring a build step. -* We are committed to supporting our current users and offering migration paths as necessary. This can be through interoperability or APIs to improve the developer experience of working between module systems. +* We are committed to not breaking our existing ecosystem for modules +* We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. # Goals From 3af65df8a8f7caa063e2b1241971b6e24c2cebf0 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 15 Feb 2018 09:33:27 -0600 Subject: [PATCH 19/31] xref design and goal of preprocessing step definition --- GOALS.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/GOALS.md b/GOALS.md index 3d75dc3..4984127 100644 --- a/GOALS.md +++ b/GOALS.md @@ -5,7 +5,7 @@ These are a list of commitments that can be used to define reasons for goals exi * We are committed to shipping ES Modules (ESM) * We are committed to ESM being first class in Node.js * We are committed to having the Node.js and Web platform as first class runtimes for modules. -* Modules installed via npm should be able to run after installation without requiring a build step. +* Modules installed via npm should be able to run after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). * We are committed to not breaking our existing ecosystem for modules * We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. @@ -14,7 +14,7 @@ These are a list of commitments that can be used to define reasons for goals exi 1. Enable use of ESM in Node without requiring a flag 2. Have files be unable to collide between module systems 3. Define a path to write code that runs in both Node and the Browser without a preprocessing step - 1. Define what a preprocessing step is + 1. Define what a preprocessing step is 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other 4. Define a path to write libraries that support being used by both * Node versions supporting ESM From ec31f5f7b9b0c355166a2ce903643683fb74289d Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Thu, 15 Feb 2018 10:52:41 -0600 Subject: [PATCH 20/31] avoid mentioning specific implementations --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 4984127..ef28817 100644 --- a/GOALS.md +++ b/GOALS.md @@ -5,7 +5,7 @@ These are a list of commitments that can be used to define reasons for goals exi * We are committed to shipping ES Modules (ESM) * We are committed to ESM being first class in Node.js * We are committed to having the Node.js and Web platform as first class runtimes for modules. -* Modules installed via npm should be able to run after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). +* Modules installed though a package manager should be able to run after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). * We are committed to not breaking our existing ecosystem for modules * We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. From ea0e0a86cb3649f49c308dcca728f31b09a77385 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Mon, 19 Feb 2018 11:08:42 -0600 Subject: [PATCH 21/31] typo --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index ef28817..41533d5 100644 --- a/GOALS.md +++ b/GOALS.md @@ -51,7 +51,7 @@ These are a list of commitments that can be used to define reasons for goals exi # Goals that are not expected for the first iteration 1. 100% stable Loader APIs - * Any Loader APIs shipped must have a forward compatible appraoch towards their usage, such as providing a feature dection mechanism or versioned API. + * Any Loader APIs shipped must have a forward compatible approach towards their usage, such as providing a feature dection mechanism or versioned API. 2. Treatment of `.js` file extension as ESM by default 3. Support for the following URL schemes: `data:`, `blob:`, and `https:` From e2954fa08cf6d8441054526fbaebb33869397e0a Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Mon, 19 Feb 2018 11:11:53 -0600 Subject: [PATCH 22/31] security design note --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index 41533d5..6ba59e8 100644 --- a/GOALS.md +++ b/GOALS.md @@ -8,6 +8,7 @@ These are a list of commitments that can be used to define reasons for goals exi * Modules installed though a package manager should be able to run after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). * We are committed to not breaking our existing ecosystem for modules * We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. +* We are commited to having security be a primary concern for ESM in Node.js. # Goals From d2fd3a7249ae2a6b3e4fe259b4fff991eb920604 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 08:45:20 -0600 Subject: [PATCH 23/31] performance concern --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index 6ba59e8..081547f 100644 --- a/GOALS.md +++ b/GOALS.md @@ -9,6 +9,7 @@ These are a list of commitments that can be used to define reasons for goals exi * We are committed to not breaking our existing ecosystem for modules * We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. * We are commited to having security be a primary concern for ESM in Node.js. +* We are commited to having performance be a primary concern for ESM in Node.js. # Goals From a321e02b44bdf26a000b1e25a8e72c13965f80e5 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 12:19:14 -0600 Subject: [PATCH 24/31] call out non-compliance -> complaince goal --- GOALS.md | 1 + 1 file changed, 1 insertion(+) diff --git a/GOALS.md b/GOALS.md index 081547f..7634d59 100644 --- a/GOALS.md +++ b/GOALS.md @@ -23,6 +23,7 @@ These are a list of commitments that can be used to define reasons for goals exi * Node versions that do not support ESM 5. Be standards compliant in the nature of our loading of ESM 1. Contextual module APIs exposed to ESM by default will be placed under `import.meta.*`. This does not relate to per Realm globals nor module specifier resolution. + 2. Should a choice be made to have a feature that is not compliant to ESM for any reason, Node will provide a way to create an ESM compliant implementation. 6. Support developer centric workflows for: 1. Intercepting dependencies and replacing them 2. Application Performance Monitoring (APM) integration From 751eef07baf8c8ec75c609d97e81f0c543a42c59 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 12:19:42 -0600 Subject: [PATCH 25/31] Current Direction --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 7634d59..2dbdfa1 100644 --- a/GOALS.md +++ b/GOALS.md @@ -58,7 +58,7 @@ These are a list of commitments that can be used to define reasons for goals exi 2. Treatment of `.js` file extension as ESM by default 3. Support for the following URL schemes: `data:`, `blob:`, and `https:` -# Direction +# Current Direction * Build upon the existing work in Node that has designs around using `.mjs` * Enable usage of `.js` for ESM through compatible means of out of band data From da35df637a4c3fa83c1e1c7346f42e7742a5eff8 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 13:22:54 -0600 Subject: [PATCH 26/31] removing confusing direction about static/dynamic loader hooks --- GOALS.md | 1 - 1 file changed, 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 2dbdfa1..ed39660 100644 --- a/GOALS.md +++ b/GOALS.md @@ -66,7 +66,6 @@ These are a list of commitments that can be used to define reasons for goals exi * Creation of in memory Module records * Composition of Loaders * Find a solution to the live-ness problem - * Discuss issues/benefits around static vs dynamic mutation of loader hooks # Forwards compatibility concerns From 71f4616314f3145b3bfaf86a78b86419c20ee9ab Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 14:37:53 -0600 Subject: [PATCH 27/31] split direction into state/direction --- GOALS.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index ed39660..c2e9877 100644 --- a/GOALS.md +++ b/GOALS.md @@ -58,9 +58,16 @@ These are a list of commitments that can be used to define reasons for goals exi 2. Treatment of `.js` file extension as ESM by default 3. Support for the following URL schemes: `data:`, `blob:`, and `https:` +# Current State + +* ESM loader is using `.mjs` to load ESM +* ESM loader is using `.js` to load CJS +* ESM loader is using URLs for the Module Map cache +* ESM loader is using a new, but backwards compatibility focused resolution algorithm +* ESM loader hooks are instrumented using the `--loader` command line flag + # Current Direction -* Build upon the existing work in Node that has designs around using `.mjs` * Enable usage of `.js` for ESM through compatible means of out of band data * Build upon the existing Loader hooks to aid usability * Creation of in memory Module records From 04452d4c0f7cd9a5d7d6255f6e8f2599d6ffb9aa Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Tue, 20 Feb 2018 16:52:31 -0600 Subject: [PATCH 28/31] clarify forwards compatibility --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index c2e9877..faca355 100644 --- a/GOALS.md +++ b/GOALS.md @@ -38,7 +38,7 @@ These are a list of commitments that can be used to define reasons for goals exi 1. Use `.js` file extension for both CJS and ESM without a disambiguation mechanism * e.g. `require` falling back to CJS when it is unsure about the format of a resolved path 2. Interoperability of Module formats with environments that do not support Module formats that Node seeks to support -3. Forwards compatibility support for the transition of existing packages from CJS to ESM +3. Require zero code or convention changes when moving from CJS to ESM 1. loading unknown file formats and `.js` as CJS 2. usage of `require.extensions` 3. usage of `require.cache` From 109262fc6743a24ad3a374c8eef9505b315469df Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Wed, 28 Feb 2018 15:31:11 -0600 Subject: [PATCH 29/31] remove/reword details so that they are abstract and dont require specific implementation --- GOALS.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/GOALS.md b/GOALS.md index faca355..f1c77c3 100644 --- a/GOALS.md +++ b/GOALS.md @@ -14,7 +14,7 @@ These are a list of commitments that can be used to define reasons for goals exi # Goals 1. Enable use of ESM in Node without requiring a flag -2. Have files be unable to collide between module systems +2. Have module cache entries be unable to collide between module systems 3. Define a path to write code that runs in both Node and the Browser without a preprocessing step 1. Define what a preprocessing step is 2. A subset of functionality that is compatible between environments, not requiring either environment implement all features of the other @@ -29,7 +29,7 @@ These are a list of commitments that can be used to define reasons for goals exi 2. Application Performance Monitoring (APM) integration 3. Multiple distributions of both ESM and CJS in the same package 4. Creation of userland module systems (JSDOM) - 5. Incremental code base migration from CJS to ESM by migrating individual files + 5. Incremental code base migration from CJS to ESM by migrating individual source texts 7. 100% backwards compatibility with existing CJS code bases if left unchanged 8. Provide a path to have singleton references that can be obtained in both module systems @@ -60,8 +60,8 @@ These are a list of commitments that can be used to define reasons for goals exi # Current State -* ESM loader is using `.mjs` to load ESM -* ESM loader is using `.js` to load CJS +* ESM loader is using the `.mjs` file extension to load ESM +* ESM loader is using the `.js` file extension to load CJS * ESM loader is using URLs for the Module Map cache * ESM loader is using a new, but backwards compatibility focused resolution algorithm * ESM loader hooks are instrumented using the `--loader` command line flag From 6c2b6a54064424fa848f05fea6f89ad55f38ee32 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Wed, 28 Feb 2018 15:32:58 -0600 Subject: [PATCH 30/31] use such as to avoid thinking we are making an abbreviation --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index f1c77c3..8633e8e 100644 --- a/GOALS.md +++ b/GOALS.md @@ -28,7 +28,7 @@ These are a list of commitments that can be used to define reasons for goals exi 1. Intercepting dependencies and replacing them 2. Application Performance Monitoring (APM) integration 3. Multiple distributions of both ESM and CJS in the same package - 4. Creation of userland module systems (JSDOM) + 4. Creation of userland module systems (such as JSDOM) 5. Incremental code base migration from CJS to ESM by migrating individual source texts 7. 100% backwards compatibility with existing CJS code bases if left unchanged 8. Provide a path to have singleton references that can be obtained in both module systems From ce182197b88287d675f622c1c32ab3e8da2537a5 Mon Sep 17 00:00:00 2001 From: Bradley Farias Date: Wed, 28 Feb 2018 16:41:14 -0600 Subject: [PATCH 31/31] specify running in Node.js --- GOALS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GOALS.md b/GOALS.md index 8633e8e..4b91e65 100644 --- a/GOALS.md +++ b/GOALS.md @@ -5,7 +5,7 @@ These are a list of commitments that can be used to define reasons for goals exi * We are committed to shipping ES Modules (ESM) * We are committed to ESM being first class in Node.js * We are committed to having the Node.js and Web platform as first class runtimes for modules. -* Modules installed though a package manager should be able to run after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). +* Modules installed though a package manager should be able to run in Node.js after installation without requiring a [preprocessing step](#goal-define-preprocessing-step). * We are committed to not breaking our existing ecosystem for modules * We are committed to providing APIs or conventions such that users will be able to use both CommonJS (CJS) and ESM with support for both workflows. * We are commited to having security be a primary concern for ESM in Node.js.