dherman/loader-api.md

## loader-api.md

      
    Raw
  

              loader-api.md
            
          
    Notational Conventions
This section describes the conventions used here to describe type signatures.
A [T] is an array-like value (only ever used read-only in this API), i.e., one with an integer length and whose indexed properties from 0 to length - 1 are of type T.
A type T? should be read as T | undefined -- that is, an optional value that may be undefined.
Loaders
The Loader class is conceptually parameterized over two types:
// Loader<ModuleAddress, ModuleSource>
The type parameters combine to define a protocol for communication between the steps of the pipeline hooks.
Loader Constructor
l = new Loader({
  realm,      // Realm?
  normalize,  // ((string, NormalizedModuleName, ModuleAddress) -> Promise<stringable>)?
  locate,     // (({ name: NormalizedModuleName, metadata: object })
              //     -> Promise<ModuleAddress>)?
  fetch,      // (({ name: NormalizedModuleName, address: ModuleAddress, metadata: object })
              //     -> Promise<ModuleSource>)?
  translate,  // (({ name: NormalizedModuleName?, address: ModuleAddress?, source: ModuleSource, metadata: object })
              //     -> Promise<string>)?
  instantiate // (({ name: NormalizedModuleName?, address: ModuleAddress?, source: ModuleSource, metadata: object })
              //     -> Promise<ModuleFactory?)?>
}) // : Loader<ModuleAddress, ModuleSource>
A NormalizedModuleName is a string obtained by coercing the resolved value of the normalize hook to a string.
A ModuleFactory is an object of the form:
{
  deps: [string],
  execute: () -> Module
}
The realm option is a Realm object -- see the Realm API gist for more details. The default value is the realm of this Loader constructor.
Loader Properties
realm
Returns the realm associated with the loader.
global
Convenience: returns the global associated with the loader's realm.
Loader Hooks
These are the loader hooks. They appear as instance properties when a loader is constructed via the Loader constructor.
Normalization
The normalize hook is used to normalize context-sensitive module names that appear within a source context. Since the hook may be called multiple times and normalize to the same module name, it acts as a "fan in" at the head of the loading pipeline.
The result of the normalize hook is coerced into a string, which is then used as the NormalizedModuleName throughout the pipeline.
normalize
// normalize : (string, NormalizedModuleName, ModuleAddress) -> Promise<stringable>
l.normalize = function(name, refererName, refererAddress) { ... }
Loading pipeline
When the pipeline begins, the system constructs a new metadata object, which is threaded through all the steps in the pipeline. If a loader wants to carry information through the pipeline, it can either include it in the data representation of the loader's type parameters (e.g., a ModuleSource object could include a field that contains the ModuleAddress where it was loaded from), or it can attach it mutably to the metadata object.
The pipeline is not fed any information about the un-normalized module name, since there can be multiple requests for the same normalized name triggered from different contexts (and potentially at different times). If userland code really wants to get access to that information it can save it in a side table.
locate
// locate : ({ name: NormalizedModuleName,
//             metadata: object })
//       -> Promise<ModuleAddress>
l.locate = function({ name, metadata }) { ... }
fetch
// fetch : ({ name: NormalizedModuleName,
//            address: ModuleAddress,
//            metadata: object })
//      -> Promise<ModuleSource>
l.fetch = function({ name, address, metadata }) { ... }
translate
// translate : ({ name: NormalizedModuleName?,
//                address: ModuleAddress?,
//                source: ModuleSource,
//                metadata: object })
//          -> Promise<string>
l.translate = function({ name, address, source, metadata }) { ... }
Since loader.module() may not provide a name or address, the name and address options may be undefined.
instantiate
// instantiate : ({ name: NormalizedModuleName?,
//                  address: ModuleAddress?,
//                  source: ModuleSource,
//                  metadata: object })
//            -> Promise<ModuleFactory?>
l.instantiate = function({ name, address, source, metadata }) { ... }
Since loader.module() may not provide a name or address, the name and address options may be undefined.
Loader Methods
These methods provide the core loader API.
Installation
These methods can be used to install modules, and none of them directly causes the installed modules to be executed. (They may indirectly cause modules to be executed if they trigger custom hooks that do so.)
define
Installs a module in the registry from source.
Extensible web: This is the dynamic equivalent of a <module> tag in HTML.
// define : (NormalizedModuleName, ModuleSource, { address: ModuleAddress?, metadata: object? }?) -> Promise<undefined>
p = l.define(name, defn[, options])
load
Installs a module into the registry by name or address.
Extensible web: This is almost the dynamic equivalent (when combined with normalization) of a declarative import statement, except it does not force the modules to be executed.
// load : (NormalizedModuleName, { address: ModuleAddress? }?) -> Promise<undefined>
p = l.load(name[, options])
Execution
These methods all execute code and none of them directly causes modules to be installed. (They may indirectly cause modules to be installed by virtue of imports in the code refering to modules that haven't yet been installed.)
module
Execute a top-level, anonymous module. In particular, it does not take a name and does not install the module.
Extensible web: This is the dynamic equivalent of an anonymous <module> in HTML.
// module : (string, { address: ModuleAddress? }?) -> Promise<Module>
p = l.module(src)
Installation and execution
import
Installs and executes a module by name, producing its instance object as the result.
Extensible web: This is the dynamic equivalent (when combined with normalization) of a declarative import statement.
// import : (NormalizedModuleName, { address: ModuleAddress? }) -> Promise<Module>
p = l.import(name[, options])
This is essentially a convenience method for executing and extracting a module after loading it. That is,
l.import(x)
is roughly equivalent to
l.load(x).then(() => Promise.resolve(l.get(x)))
Registry manipulation
These methods work with the module registry.
get
Gets the module associated with the given (normalized) key, first executing the module if it hasn't yet been executed.
// get : (string) -> Module?
m = l.get(name)
set
// set : (string, Module) -> undefined
l.set(name, m)
delete
// delete : (string) -> undefined
l.delete(name)
has
// has : (string) -> boolean
l.has(name)
keys
// keys : Iterator<string>
for (let name of l.keys()) { ... }
values
// values : Iterator<Module>
for (let m of l.values()) { ... }
entries
// entries : Iterator<[string,Module]>
for (let [name, m] of l.entries()) { ... }
Module Objects
A module instance object is a runtime instantiation of a module. They can be constructed reflectively using the Module constructor. A module instance object is non-extensible and its [[Prototype]] is null.
Extensible web: This is the dynamic equivalent of a module loaded from source.
Module Constructor
m = new Module(object); // object?
If object is undefined it defaults to an empty object. Otherwise if it's not an object a TypeError is thrown.
This creates a module instance object whose exported names are the keys (i.e., own enumerable property names) of object and whose export values are the result of calling [[Get]] on each key of object.
Rationale
Loader entry points
The Loader top-level API provides entry points for all steps in the pipeline that we don't deliberately want to avoid exposing.

NormalizedModuleName → locate: load
ModuleAddress → fetch: load
ModuleSource → translate: define
ModuleSource → instantiate: error-prone; circumvents translation
ModuleFactory → done: factories are a compatibility layer but not for general use

Reflection of declarative features

<module>: loader.module(...)
<module id='foo'>: loader.define('foo', ...)
<script>: realm.eval(...) (perhaps deferred to ES7)
<iframe>: new Realm(...) (perhaps deferred to ES7)
import from: loader.import(...)
module from: loader.import(...)
module source: new Module(...)

Deliberate omissions

no installing scripts (loaders only deal with modules, scripts can't be named or imported from)
no remote script execution (loaders deal only with modules, require fetch since import is language syntax; no corresponding syntax for script execution)
no version of define that executes the modules (can do this by calling l.get() after installation completes)
no version of define etc. that take an array (can do this with a sequence of calls since it's all async)
no tracking redirects; a given loader can use a mutable type for ModuleAddress and update it as it goes