From 7674adb21eedf268693d6e68b7c4d440ecc02df1 Mon Sep 17 00:00:00 2001 From: Saleh Abdel Motaal Date: Wed, 25 Jul 2018 14:49:14 -0400 Subject: [PATCH 1/6] Create Terminology.md --- doc/Terminology.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) create mode 100644 doc/Terminology.md diff --git a/doc/Terminology.md b/doc/Terminology.md new file mode 100644 index 0000000..a923f42 --- /dev/null +++ b/doc/Terminology.md @@ -0,0 +1,64 @@ +Terminology +============ + +This document is used to keep track of common terminology related to modules in [Node.js](https://nodejs.org), focusing primarily on ECMAScript Modules as well as other mainstream module formats. + +
+ +Normative Terms +--------------- + +
+ Agnostic Consumers +
+ + The ability for importer modules to be unaware of the imported module type (CJS vs ESM). This implies that the imported module can be migrated from CJS to ESM without impacting the consumer. + + This term alone does not specify in which direction(s) the agnosticism applies. + +
+ Require Interoperability `require()` +
+ + The ability for a module to import an ESM module using the `require(…)` function. + + The module’s namespace is return directly, i.e. it is not wrapped in a promise. + + If it is impossible to load the graph synchronously, it is intended that the call must throw. + +
+ Import Interoperability `import()` +
+ + The ability for an ESM module to import a CJS module. + + Applies to both static `import … from ` and dynamic `import(…)`. + + This term alone does not specify whether named `exports` are extracted from the CJS exports object. + +
+ Named Exports `exportKeys` +
+ + The ability for a CJS module to elect to expose properties of its `exports` object as fixed set of named exports for use by ESM consumers, as opposed to having a single `export default` equal to the exports object. + + Some forms of CJS are not amenable, e.g. those that dynamically delete properties of the exports object. + +
+ +
+ +Deprecated Terms +---------------- + +
+ Transparent Interoperability +
+ + An imprecise term that refers to some subset of the following independent capabilities: + + 1. [Agnostic Consumers](#agnostic-consumers) (in one or both directions) + 2. [Require Interoperability](#require-interop) + 3. [Import Interoperability](#import-interop) (with or without Named Exports from CJS) + +
From 3d94a6d917ed15e4ea1f9cb21b296154cb54b6d1 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Mon, 30 Jul 2018 21:33:21 -0700 Subject: [PATCH 2/6] Fix HTML --- doc/Terminology.md | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/doc/Terminology.md b/doc/Terminology.md index a923f42..fc23ace 100644 --- a/doc/Terminology.md +++ b/doc/Terminology.md @@ -10,14 +10,16 @@ Normative Terms
Agnostic Consumers +
- The ability for importer modules to be unaware of the imported module type (CJS vs ESM). This implies that the imported module can be migrated from CJS to ESM without impacting the consumer. This term alone does not specify in which direction(s) the agnosticism applies. +
- Require Interoperability `require()` + Require Interoperability require() +
The ability for a module to import an ESM module using the `require(…)` function. @@ -25,9 +27,11 @@ Normative Terms The module’s namespace is return directly, i.e. it is not wrapped in a promise. If it is impossible to load the graph synchronously, it is intended that the call must throw. +
- Import Interoperability `import()` + Import Interoperability import() +
The ability for an ESM module to import a CJS module. @@ -35,24 +39,28 @@ Normative Terms Applies to both static `import … from ` and dynamic `import(…)`. This term alone does not specify whether named `exports` are extracted from the CJS exports object. +
- Named Exports `exportKeys` + Named Exports exportKeys +
The ability for a CJS module to elect to expose properties of its `exports` object as fixed set of named exports for use by ESM consumers, as opposed to having a single `export default` equal to the exports object. Some forms of CJS are not amenable, e.g. those that dynamically delete properties of the exports object. - +
+ -
Deprecated Terms ---------------- +
Transparent Interoperability +
An imprecise term that refers to some subset of the following independent capabilities: @@ -60,5 +68,5 @@ Deprecated Terms 1. [Agnostic Consumers](#agnostic-consumers) (in one or both directions) 2. [Require Interoperability](#require-interop) 3. [Import Interoperability](#import-interop) (with or without Named Exports from CJS) - +
From c13a94307d9ba3d117290f6cceeecaaeba7fcf64 Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Mon, 30 Jul 2018 21:40:48 -0700 Subject: [PATCH 3/6] Add consumer- and author-defined disambiguation --- doc/Terminology.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/Terminology.md b/doc/Terminology.md index fc23ace..4c702c0 100644 --- a/doc/Terminology.md +++ b/doc/Terminology.md @@ -51,8 +51,19 @@ Normative Terms Some forms of CJS are not amenable, e.g. those that dynamically delete properties of the exports object. +
+ Consumer-defined Disambiguation +
+
+ When importing a file into an ESM context, the parse goal of the file is determined by the importing module (the consumer). This is often accomplished via syntax, for example by using only `import` statements for ESM or `require` (or other function) for CommonJS.
+
+ Author-defined Disambiguation +
+
+ A file or module’s parse goal is included within itself. This is often achieved via a file extension such as `.mjs` or a field in a `package.json` file. Other suggestions have included a `"use module"` directive or unambiguous syntax, such as parsing the file for `import` or `export` statements. + Deprecated Terms ---------------- From 57b8247c46c71329238d27d409895ebb0d99d5cc Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Mon, 30 Jul 2018 21:41:38 -0700 Subject: [PATCH 4/6] Fix typo --- doc/Terminology.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/Terminology.md b/doc/Terminology.md index 4c702c0..ea6fc29 100644 --- a/doc/Terminology.md +++ b/doc/Terminology.md @@ -56,13 +56,14 @@ Normative Terms
When importing a file into an ESM context, the parse goal of the file is determined by the importing module (the consumer). This is often accomplished via syntax, for example by using only `import` statements for ESM or `require` (or other function) for CommonJS. - +
Author-defined Disambiguation
A file or module’s parse goal is included within itself. This is often achieved via a file extension such as `.mjs` or a field in a `package.json` file. Other suggestions have included a `"use module"` directive or unambiguous syntax, such as parsing the file for `import` or `export` statements. +
Deprecated Terms From 7ba49cb1338fb2987ae032bc37e399bc383fe90a Mon Sep 17 00:00:00 2001 From: Geoffrey Booth Date: Mon, 30 Jul 2018 21:42:36 -0700 Subject: [PATCH 5/6] Damn formatting --- doc/Terminology.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/Terminology.md b/doc/Terminology.md index ea6fc29..5e621b1 100644 --- a/doc/Terminology.md +++ b/doc/Terminology.md @@ -55,14 +55,18 @@ Normative Terms Consumer-defined Disambiguation
+ When importing a file into an ESM context, the parse goal of the file is determined by the importing module (the consumer). This is often accomplished via syntax, for example by using only `import` statements for ESM or `require` (or other function) for CommonJS. +
Author-defined Disambiguation
+ A file or module’s parse goal is included within itself. This is often achieved via a file extension such as `.mjs` or a field in a `package.json` file. Other suggestions have included a `"use module"` directive or unambiguous syntax, such as parsing the file for `import` or `export` statements. +
From e1acbc1a2788234b4b713facfaa4e87da312ea10 Mon Sep 17 00:00:00 2001 From: Saleh Date: Fri, 14 Sep 2018 08:06:26 -0400 Subject: [PATCH 6/6] Add "Stipulative Terms" with "Browser Interop" MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unlike the more linear "normative" counterparts, stipulative terms are more intricate and often require layered definitions. I took a stab at "Browser Interop" not "browser interoperability" because the latter is non-stipulative in general, while the former to us focuses on "browser interoperability" of ES modules intended for Node.js and … --- doc/Terminology.md | 73 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 59 insertions(+), 14 deletions(-) diff --git a/doc/Terminology.md b/doc/Terminology.md index 5e621b1..e7500b0 100644 --- a/doc/Terminology.md +++ b/doc/Terminology.md @@ -3,25 +3,32 @@ Terminology This document is used to keep track of common terminology related to modules in [Node.js](https://nodejs.org), focusing primarily on ECMAScript Modules as well as other mainstream module formats. + +
Normative Terms --------------- - -
+ +
Agnostic Consumers
-
+
The ability for importer modules to be unaware of the imported module type (CJS vs ESM). This implies that the imported module can be migrated from CJS to ESM without impacting the consumer. This term alone does not specify in which direction(s) the agnosticism applies.
-
+
Require Interoperability require()
- + The ability for a module to import an ESM module using the `require(…)` function. The module’s namespace is return directly, i.e. it is not wrapped in a promise. @@ -29,11 +36,11 @@ Normative Terms If it is impossible to load the graph synchronously, it is intended that the call must throw.
-
+
Import Interoperability import()
- + The ability for an ESM module to import a CJS module. Applies to both static `import … from ` and dynamic `import(…)`. @@ -45,7 +52,7 @@ Normative Terms Named Exports exportKeys
- + The ability for a CJS module to elect to expose properties of its `exports` object as fixed set of named exports for use by ESM consumers, as opposed to having a single `export default` equal to the exports object. Some forms of CJS are not amenable, e.g. those that dynamically delete properties of the exports object. @@ -55,21 +62,59 @@ Normative Terms Consumer-defined Disambiguation
- + When importing a file into an ESM context, the parse goal of the file is determined by the importing module (the consumer). This is often accomplished via syntax, for example by using only `import` statements for ESM or `require` (or other function) for CommonJS. - +
Author-defined Disambiguation
- + A file or module’s parse goal is included within itself. This is often achieved via a file extension such as `.mjs` or a field in a `package.json` file. Other suggestions have included a `"use module"` directive or unambiguous syntax, such as parsing the file for `import` or `export` statements.
+ +Stipulative Terms +----------------- + +
+ Browser Interop +
+
+ + The expectation that a module (namely ES modules) can be written once and be used in both Node.js and a "popular browser" that is "reasonably conforming", beyond the implicit requirements of conformance to the behaviours defined by the ECMAScript specificion. + +
+ +
browser interoperability
+
+ + The stipulation for "browser interoperability" of ES modules here extends to the ability to utilize platform-specific features in such a way that would mitigate any potential for irrecoverable runtime exceptions, such as early errors. This stipulation aims to help encourage ES modules adoption rates for both Node.js and "popular browsers". + + It does not exclude interoperability for runtimes where polyfilling can provide a suitable setting, however, that is neither recommended nor considered to determine "browser interoperability". This stipulation aims to help encourage the "responsible use" of tooling as a vital component of the JavaScript ecosystem. +
+ +
reasonably conforming
+
+ + The stipulation for "reasonably conforming" here excludes browsers that do not conform to the ECMAScript 2015 specification as well as all module specific features defined in subsequent revisions. It also excludes all forms of drafts, non-normative specifications, and recommended specifications that are "not considered" and/or are intentionally "removed" by "popular browsers". +
+ +
popular browsers
+
+ + The term "popular browsers" is intentionally left open to interpretation. +
+ +
+
+ +
- + + Deprecated Terms ---------------- @@ -78,9 +123,9 @@ Deprecated Terms Transparent Interoperability
- + An imprecise term that refers to some subset of the following independent capabilities: - + 1. [Agnostic Consumers](#agnostic-consumers) (in one or both directions) 2. [Require Interoperability](#require-interop) 3. [Import Interoperability](#import-interop) (with or without Named Exports from CJS)