diff --git a/GOALS.md b/GOALS.md new file mode 100644 index 0000000..4b91e65 --- /dev/null +++ b/GOALS.md @@ -0,0 +1,85 @@ +# Preface: Design Principles + +These are a list of commitments that can be used to define reasons for goals existing. + +* 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 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. +* We are commited to having performance be a primary concern for ESM in Node.js. + +# Goals + +1. Enable use of ESM in Node without requiring a flag +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 +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. 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 + 3. Multiple distributions of both ESM and CJS in the same package + 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 + +# 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. 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` + 4. usage of `NODE_PATH`, `~/.node_libraries`, `~/.node_modules`, and `$PREFIX/lib/node` +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 +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 + +1. 100% stable Loader APIs + * 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:` + +# Current State + +* 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 + +# Current Direction + +* 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 + * Find a solution to the live-ness problem + +# Forwards compatibility concerns + +* Interoperability with WASM +* Interoperability with browser support for more module formats +* Resource integrity checks +* 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