Merge pull request #36 from nodejs/reorg-design-docs

Author: GeoffreyBooth

README.md

@@ -14,7 +14,7 @@ This team is spun off from the [Modules team](https://github.com/nodejs/modules)
 
 - [Use cases](./doc/use-cases.md)
 
-- [Design](./doc/design.md)
+- [Design](./doc/design/overview.md)
 
 - [Project board](https://github.com/nodejs/node/projects/17)
 

doc/design/overview.md

@@ -0,0 +1,36 @@
+# Loaders Design
+
+There are currently [three loader hooks](https://github.com/nodejs/node/tree/master/doc/api/esm.html#esm_hooks):
+
+1. `resolve`: Takes a specifier (the string after `from` in an `import` statement) and converts it into an URL to be loaded.
+
+1. `load`: Takes the resolved URL and returns runnable code (JavaScript, Wasm, etc.) as well as the name of one of Node’s ESM loader’s [“translators”](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/translators.js):
+   * `commonjs`
+   * `module`
+   * `builtin` (a Node internal module, like `fs`)
+   * `json` (with `--experimental-json-modules`)
+   * `wasm` (with `--experimental-wasm-modules`)
+
+* `globalPreload`: Defines a string of JavaScript to be injected into the application global scope.
+
+## Chaining
+
+Custom loaders are intended to chain to support various concerns beyond the scope of core, such as build tooling, mocking, transpilation, etc.
+
+### Proposals
+
+* [Recursive chaining](./proposal-chaining-recursive.md)
+
+## History
+
+### Hook consolidation
+
+The initial experimental implementation consisted of 5 hooks:
+
+* `resolve`
+* `getFormat`
+* `getSource`
+* `transformSource`
+* `getGlobalPreloadCode`
+
+These were consolidated (in [nodejs/node#37468](https://github.com/nodejs/node/pull/37468)) to avoid counter-intuitive and paradoxical behaviour when used in multiple custom loaders.

doc/design.md renamed to doc/design/proposal-chaining-recursive.md

@@ -1,14 +1,4 @@
-# Loaders Design
-
-## Hooks
-
-There are currently [three loader hooks](https://nodejs.org/api/esm.html#esm_hooks):
-
-- `resolve`: Take a specifier (the string after `from` in an `import` statement) and convert it into an URL to be loaded.
-
-- `load`: Take the resolved URL and return runnable code (JavaScript, Wasm, etc.) as well as the name of one of Node’s ESM loader’s [“translators”](https://github.com/nodejs/node/blob/master/lib/internal/modules/esm/translators.js): `commonjs`, `module`, `builtin` (a Node internal module like `fs`), `json` (with `--experimental-json-modules`) or `wasm` (with `--experimental-wasm-modules`).
-
-- `globalPreload`: Define a string of JavaScript to be injected into the application global scope.
+# Chaining Hooks “Recursive” Design
 
 ## Chaining `resolve` hooks