Initial commit

Author: Kevin Smith

.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+_*
+node_modules

README.md

@@ -0,0 +1,199 @@
+# A Modest Proposal for ES6 Modules in Node.js
+
+## Guiding Principles
+
+- The solution must be 100% backward-compatible.
+- In the far future, developers should be able to write Node programs and libraries without knowledge of the CommonJS module system.
+- Module resolution rules should be reasonably compatible with the module resolution rules used by browsers.
+- The ability to import a legacy package is important for adoption.
+
+## Design Summary
+
+**1. There is no change to the behavior of `require`. It cannot be used to import ES6 modules.**
+
+This ensures 100% backward-compatibility, while still allowing some freedom of design.
+
+**2. The only folder entry point for ES6 modules is "default.js". "package.json" files are not used for resolving ES6 module paths.**
+
+A distinct entry point file name ("default.js") allows us to detect when a user is attempting to import from a legacy package or a folder containing legacy modules.
+
+**3. When `import`ing a file path, file extensions are not automatically appended.**
+
+The default resolution algorithm used by web browsers will not automatically append file extensions.
+
+**4. When `import`ing a directory, if a "default.js" file cannot be found, the algorithm will attempt to find an entry point using legacy `require` rules, by consulting "package.json" and looking for "index.*" files.**
+
+This provides users with the ability to `import` from legacy packages.
+
+**5. `require.import(modulePath)` synchronously imports an ES6 module.**
+
+This allows old-style modules to `import` from new-style modules.
+
+## Use Cases
+
+### Existing modules
+
+Since there is no change to the behavior of `require`, there is no change to the behavior of existing modules and packages.
+
+### Supporting `import` for old-style packages
+
+If a "default.js" file does not exist in the package root, then it will be loaded as an old-style module with no further changes.  It just works.
+
+### Supporting `require` for ES6 packages
+
+Since `require` cannot be directly used to import ES6 modules, we need to provide an old-style "index.js" entry point if we want to allow consumers to `require` our package:
+
+```
+src/
+  [ES6 modules]
+default.js -> src/default.js
+index.js
+```
+
+The purpose of the "index.js" file will be to map the ES6 module into an old-style module and can be as simple as:
+
+```js
+// [index.js]
+module.exports = require.import('./src/default.js');
+```
+
+### Distributing both transpiled and native ES6 modules
+
+In this usage scenario, a package is authored in ES6 modules and transpiled to old-style modules using a compiler like Babel.  A typical directory layout for such a project is:
+
+```
+lib/
+  [Transpiled modules]
+src/
+  [ES6 modules]
+index.js -> lib/index.js
+```
+
+Users that `require` the package will load the transpiled version of the code.  If we want to allow `import`ing of this package, we can add a "default.js" file.
+
+```
+lib/
+  [Transpiled modules]
+src/
+  [ES6 modules]
+index.js -> lib/index.js
+default.js -> src/index.js
+```
+
+We might also want our transpiler to rename "default.js" source files to "index.js".
+
+```
+lib/
+  [Transpiled modules]
+src/
+  [ES6 modules]
+index.js -> lib/index.js
+default.js -> src/default.js
+```
+
+### Gradually migrating a project to ES modules
+
+In this scenario, a user has a large project and wants to convert old-style modules to new style modules gradually.
+
+**Option 1: Using a transpiler**
+
+The project uses a transpiler to convert all code to old-style modules.  Old-style modules are distributed to consumers.  When all modules have been migrated, the transpiler can be removed.
+
+**Option 2: Replacing require sites**
+
+When converting an old-style module to the ES module syntax, use a script to update all internal modules which reference the converted module.  The script would change occurrences of:
+
+```js
+var someModule = require('./some-module');
+```
+
+to:
+
+```js
+var someModule = require.import('./some-module.js').default;
+```
+
+### Deep-linking into a package
+
+A common practice with old-style packages is to allow the user to `require` individual modules within the package source:
+
+```js
+// Loads node_modules/foo/bar.js
+var deepModule = require('foo/bar');
+```
+
+If the package author wants to support both `require`ing and `import`ing into a nested module, they can do so by creating a folder for each "deep link", which contains both an old-style and new-style entry point:
+
+```
+bar/
+  index.js (Entry point for require)
+  default.js (Entry point for import)
+```
+
+## Why "default.js"?
+
+- "default.html" is frequently used as a folder entry point for web servers.
+- The word "default" has a special, and similar meaning in ES6 modules.
+- Despite "default" being a common English word, "default.js" is not widely used as a file name.
+
+In a random sampling of 25,000 NPM packages (10% of the total number of packages), "default.js" was only found one time in a package root.  This particular "default.js" file was already an ES6 module.  As a filename, "default.js" was found only 174 times.  By contrast, "index.js" was found 22,607 times, and in the package root 10,282 times.
+
+## Running Modules from the Command Line
+
+When a user executes
+
+```sh
+$ node my-module.js
+```
+
+from the command line, there is absolutely no way for Node to tell whether "my-module.js" is a legacy CJS module or an ES6 module.  In the interest of backward compatibility, Node should probably attempt to load the file as a CJS module, and fallback to ES6 if there is a syntax error indicating the presence of `import` declarations.  As people move away from CJS modules in general, future Node versions can assume that the file is an ES6 module.
+
+## Lookup Algorithm Psuedo-Code
+
+### LOAD_MODULE(X, Y, T)
+
+Loads _X_ from a module at path _Y_.  _T_ is either "require" or "import".
+
+1. If X is a core module, then
+    1. return the core module
+    1. STOP
+1. If X begins with './' or '/' or '../'
+    1. LOAD_AS_FILE(Y + X, T)
+    1. LOAD_AS_DIRECTORY(Y + X, T)
+1. LOAD_NODE_MODULES(X, dirname(Y), T)
+1. THROW "not found"
+
+### LOAD_AS_FILE(X, T)
+
+1. If T is "import",
+    1. If X is a file, then
+        1. If extname(X) is ".js", load X as ES6 module text. STOP
+        1. If extname(X) is ".json", parse X to a JavaScript Object.  STOP
+        1. If extname(X) is ".node", load X as binary addon.  STOP
+        1. THROW "not found"
+1. Else,
+    1. Assert: T is "require"
+    1. If X is a file, load X as CJS module text.  STOP
+    1. If X.js is a file, load X.js as CJS module text.  STOP
+    1. If X.json is a file, parse X.json to a JavaScript Object.  STOP
+    1. If X.node is a file, load X.node as binary addon.  STOP
+
+### LOAD_AS_DIRECTORY(X, T)
+
+1. If T is "import",
+    1. If X/default.js is a file, load X/default.js as ES6 module text.  STOP
+    1. NOTE: If X/default.js is not a file, then fallback to legacy behavior
+1. If X/package.json is a file,
+    1. Parse X/package.json, and look for "main" field.
+    1. let M = X + (json main field)
+    1. LOAD_AS_FILE(M, "require")
+1. If X/index.js is a file, load X/index.js as JavaScript text.  STOP
+1. If X/index.json is a file, parse X/index.json to a JavaScript object. STOP
+1. If X/index.node is a file, load X/index.node as binary addon.  STOP
+
+### LOAD_NODE_MODULES(X, START, T)
+
+1. let DIRS=NODE_MODULES_PATHS(START)
+2. for each DIR in DIRS:
+    1. LOAD_AS_FILE(DIR/X, T)
+    1. LOAD_AS_DIRECTORY(DIR/X, T)