include docs

Author: guybedford

docs/circular-references-bindings.md

@@ -0,0 +1,48 @@
+### Circular References & Bindings
+
+#### Zebra-Striping
+
+All [AMD](http://requirejs.org/docs/api.html#circular), [CommonJS](http://nodejs.org/api/modules.html#modules_cycles), and [ES6](https://github.com/ModuleLoader/es6-module-loader#circular-references--bindings) treat circular dependencies differently. 
+Handling this problem is one of the innovations of the loader spec, using a technique called **zebra-striping**. This involves analyzing the dependency tree and forming alternate layers of ES6 / non-ES6 modules with circular references in each layer for linking.
+The layers are then individually linked, with the appropriate circular reference handling being done within each layer. This allows CommonJS circular references to interact with ES6 circular references. Inter-format circular references are not supported as they
+would be across layers.
+
+This loader implementation handles zebra-striping automatically, allowing a loader like [SystemJS](https://github.com/systemjs/systemjs) to support all module formats with exact circular reference support.
+
+#### ES6 Circular References & Bindings
+
+ES6 circular references and bindings behave in the following way:
+
+* Bindings are set up before module execution.
+* Execution is run from depth-first left to right on the module tree stopping at circular references.
+* Bindings are live - an adjustment to an export of one module affects all modules importing it, but it can only be modified in the defining module.
+
+even.js
+```javascript
+  import { odd } from './odd'
+
+  export var counter = 0;
+
+  export function even(n) {
+    counter++;
+    return n == 0 || odd(n - 1);
+  }
+```
+
+odd.js
+```javascript
+  import { even } from './even';
+
+  export function odd(n) {
+    return n != 0 && even(n - 1);
+  }
+```
+
+```javascript
+  System.import('even').then(function(m) {
+    m.even(10);
+    m.counter;
+    m.even(20);
+    m.counter;
+  });
+```

docs/loader-config.md

@@ -0,0 +1,73 @@
+### baseURL
+
+All modules are loaded relative to the `baseURL`, which by default is set to the current page path.
+
+We can alter this with:
+
+```javascript
+  System.baseURL = '/js/lib/';
+  System.import('module'); // now loads "/js/lib/module.js"
+```
+
+> Note that using `System.import` to load URLs is not currently supported, instead use paths for this as documented below.
+
+### Paths Implementation
+
+The System loader provides paths rules used by the standard `locate` function.
+
+For example, we might want to load `jquery` from a CDN location. For this we can provide a paths rule:
+
+```javascript
+  System.paths['jquery'] = '//ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js';
+  System.import('jquery').then(function($) {
+    // ...
+  });
+```
+
+Any reference to `jquery` in other modules will also use this same version.
+
+**Be careful**：When developing, System loader uses xhr method to load script from CDN site, so there might be some Cross-Origin problems.
+
+It is also possible to define wildcard paths rules. The most specific rule will be used:
+
+```javascript
+  System.paths['lodash/*'] = '/js/lodash/*.js'
+  System.import('lodash/map').then(function(map) {
+    // ...
+  });
+```
+
+Rule specificity is determined by an exact paths match first, followed by the last deepest wildcard match.
+
+### Custom Compilation Options
+
+Custom [Traceur compilation options](https://github.com/google/traceur-compiler/wiki/Options-for-Compiling) can be set through `System.traceurOptions`, eg:
+
+```javascript
+System.traceurOptions = { annotations = true };
+```
+
+or if using Babel:
+
+```javascript
+System.babelOptions = { experimental: true };
+```
+
+### Finding the Transpiler
+
+For Babel use the `browser.js` file contained in the `babel-core` npm module. For Traceur use the `traceur.js` file contained in the `traceur` npm module bin folder.
+
+The transpiler is loaded as a module itself, so will follow normal paths rules.
+
+To set custom paths to Babel or Traceur use paths configuration:
+
+```javascript
+System.paths['traceur'] = 'path/to/traceur.js';
+```
+
+Alternatively if you know that the transpiler will be needed, it will be detected from the global (`window[System.transpiler]`) when the first module is loaded, so can be loaded before ES6 Module Loader:
+
+```html
+<script src="traceur.js"></script>
+<script src="es6-module-loader.js"></script>
+```

docs/loader-extensions.md

@@ -0,0 +1,128 @@
+### Extending the ES6 Loader
+
+The ES6 specification defines a loader through five hooks:
+
+* Normalize: Given the import name, provide the canonical module name.
+* Locate: Given a canonical module name, provide the URL for the resource.
+* Fetch: Given a URL for a resource, fetch its content.
+* Translate: Given module source, make any source modifications.
+* Instantiate: Given module source, determine its dependencies, and how to execute it.
+
+Variations of these hooks can allow creating many different styles of loader.
+
+Each hook can either return a result directly, or a promise for the result.
+
+To use custom loader hooks, one would typically override the System loader hooks on the `System` global directly:
+
+```javascript
+  // store the old normalization function
+  var systemNormalize = System.normalize;
+  // override the normalization function
+  System.normalize = function(name, parentName, parentAddress) {
+    if (name == 'my/custom/rule')
+      return 'custom/name';
+    else
+      return systemNormalize.call(this, name, parentName, parentAddress);
+  }
+```
+
+### Custom Extension Example - Cache Busting Extension
+
+```javascript
+var systemLocate = System.locate;
+System.locate = function(load) {
+  var System = this; // its good to ensure exact instance-binding
+  return Promise.resolve(systemLocate.call(this, load)).then(function(address) {
+    return address + System.cacheBust;
+  });
+}
+System.cacheBust = '?bust=' + Date.now();
+```
+
+The above will add a customizable cache-busting query parameter to all requests. Custom filtering could even be added as well to only do this for certain requests.
+
+### Creating a Custom Loader
+
+A custom loader can be created with:
+
+```javascript
+  var myLoader = new LoaderPolyfill({
+    normalize: ...,
+    locate: ...,
+    fetch: ...,
+    translate: ...,
+    instantiate: ...
+  });
+```
+
+### Loader Hooks
+
+The signatures for all the loader hooks is provided below:
+
+```javascript
+
+/*
+ * name: the unnormalized module name
+ * parentName: the canonical module name for the requesting module
+ * parentAddress: the address of the requesting module
+ */
+function normalize(name, parentName, parentAddress) {
+  return resolvedName;
+}
+
+/*
+ * load.name the canonical module name
+ * load.metadata a metadata object that can be used to store
+ *   derived metadata for reference in other hooks
+ */
+function locate(load) {
+  return this.baseURL + '/' + load.name + '.js';
+}
+
+/*
+ * load.name: the canonical module name
+ * load.address: the URL returned from locate
+ * load.metadata: the same metadata object by reference, which
+ *   can be modified
+ */
+function fetch(load) {
+  return new Promise(function(resolve, reject) {
+    myFetchMethod.get(load.address, resolve, reject);
+  });
+}
+
+/*
+ * load.name
+ * load.address
+ * load.metadata
+ * load.source: the fetched source
+ */
+function translate(load) {
+  return load.source;
+}
+
+/*
+ * load identical to previous hooks, but load.source
+ * is now the translated source
+ */
+function instantiate(load) {
+  // an empty return indicates standard ES6 linking and execution
+  return;
+
+  // a return value creates a "dynamic" module linking
+  return {
+    deps: ['some', 'dependencies'],
+    execute: function() {
+      return loader.newModule({
+        some: 'export'
+      });
+    }
+  };
+}
+```
+
+For a more in-depth overview of creating with custom loaders, some resources are provided below:
+
+* The [System Loader implementation](https://github.com/ModuleLoader/es6-module-loader/blob/master/src/loader.js#L867)
+* [ES6 Loader API guide](https://gist.github.com/dherman/7568080)
+* [Yehuda Katz's essay](https://gist.github.com/wycats/51c96e3adcdb3a68cbc3) (outdated)

docs/overview.md

@@ -0,0 +1,109 @@
+## Background
+
+### Modules and Module Loaders
+
+A module is simply a JavaScript file written with module syntax. Modules _export_ values, which can then be _imported_ by other modules.
+
+[CommonJS](http://wiki.commonjs.org/wiki/CommonJS) and [AMD](https://github.com/amdjs/amdjs-api/wiki/AMD) JavaScript files are modules.
+
+A module loader provides the ability to dynamically load modules, and also keeps track of all loaded modules in a module registry.
+
+Typically, in production, the module registry would be populated by an initial compiled bundle of modules. Later in the page state, it may become necessary to dynamically
+load a new module. This module can then share dependencies with the initial page bundle without having to reload any dependencies.
+
+Module code is treated differently to scripts due to the nature of exports and imports. This is why the `<script type="module">` tag is introduced to distinguish script code from module code.
+
+### Module Names and baseURL
+
+Module names are just like moduleIDs in RequireJS. Non-relative module names (not starting with `.`) are converted to a URL with the following rule:
+
+```javascript
+  URL = absolutePath(baseURL, ModuleName + '.js')
+```
+
+Relative module names can be written `'./local-module'` to load relative to their parent module name. `..` syntax is also supported allowing easily portable modules.
+
+## ES6 Module Syntax
+
+### Exporting
+
+ES6 module syntax is most similar to the `exports.method = function() {}` pattern in NodeJS of creating multiple named exports.
+
+In CommonJS one might write:
+
+```javascript
+  exports.someMethod = function() {
+
+  };
+
+  exports.another = {};
+```
+
+In ES6, this same code would be written:
+
+exporter.js:
+```javascript
+  export function someMethod() {
+
+  }
+
+  export var another = {};
+```
+
+Notice that the name of the function, class or variable gets used as the export name.
+
+### Importing
+
+When importing, we import any exports we need by name, and can also choose to rename them:
+
+importer.js:
+```javascript
+  import { someMethod, another as newName } from './exporter';
+
+  someMethod();
+  typeof newName == 'object';
+```
+
+### Default Import and Export
+
+Sometimes one doesn't want to write an import name at all. For this we can use the default export:
+
+export-default.js:
+```javascript
+  export default function foo() {
+    console.log('foo');
+  }
+```
+
+import-default.js:
+```javascript
+  import customName from './export-default';
+
+  customName(); // -> 'foo'
+```
+
+### All Supported Syntax
+
+There are a few other variations of module syntax, the full list of supported statements is listed below.
+
+```javascript
+import 'jquery';                        // import a module without any import bindings
+import $ from 'jquery';                 // import the default export of a module
+import { $ } from 'jquery';             // import a named export of a module
+import { $ as jQuery } from 'jquery';   // import a named export to a different name
+
+export var x = 42;                      // export a named variable
+export function foo() {};               // export a named function
+
+export default 42;                      // export the default export
+export default function foo() {};       // export the default export as a function
+
+export { encrypt };                     // export an existing variable
+export { decrypt as dec };              // export a variable as a new name
+export { encrypt as en } from 'crypto'; // export an export from another module
+export * from 'crypto';                 // export all exports from another module
+
+import * as crypto from 'crypto';    // import an entire module instance object
+```
+
+Note that any valid declaration can be exported. In ES6, this includes `class` (as in the example above), `const`, and `let`.