Modules/AsynchronousDefinition

STATUS: PROPOSAL

Implementations

[[Implementations/RequireJS|]], [[Implementations/Nodules|]], [[Implementations/Yabble (partial)|]], [[Implementations/Dojo|]], [[Implementations/Transporter|]], [[Implementations/Teleport|]], [[Implementations/PINF (partial)|]], [[Implementations/curl.js|]]

NOTE: This document is retained for historical purposes, but the evolution of this API is now tracked on the amdjs wiki. Please use the amdjs wiki as the definitive API source.

The Asynchronous Module Definition API specifies a mechanism for defining modules such that the module and its dependencies can be asynchronously loaded. This is particularly well suited for the browser environment where synchronous loading of modules incurs performance, usability, debugging, and cross-domain access problems. This specification used to be called Modules Transport/C, but this is specification is not primarily geared for transported existing CommonJS modules, but for defining modules (although it can be used as a transport).

Specification

define() function

The specification defines a single function "define" that is available as a free variable or a global variable. The signature of the function:

define(id?, dependencies?, factory);

The first argument, id, specifies the id of the module being defined. This argument is optional, and if it not present, the module id should default to the id of the module that the loader was requesting for the given response script. When present, the module id MUST be an absolute id (relative ids are not allowed.

The second argument, dependencies, is an array of the dependencies that are required by the module that is being defined. The dependencies must be resolved prior to execution of the module factory function, and the resolved values should be passed as arguments to the factory function with argument positions corresponding to index in the dependencies array. The dependencies ids may be relative ids, and should be resolved relative the module being defined. This specification defines three special dependency names that have a distinct resolution. If the value of "require", "exports", or "module" appear in the dependency list, the argument should be resolved to the corresponding free variable as defined by the CommonJS modules specification. This argument is optional. If omitted, it should default to ["require", "exports", "module"]. However, if the factory function's arity (length property) is less than 3, than the loader may choose to only call the factory with the number of arguments corresponding to the function's arity or length.

The third argument, factory, is a function that should be executed to instantiate the module or an object. If the factory is a function it should only be executed once. If the factory argument is an object, that object should be assigned as the exported value of the module.

If the factory function returns a value (an object, function, or any value that coerces to true), and then that value should be assigned as the exported value for the module.

If both the first argument (module id) and the second argument (dependencies) are omitted, the module loader MAY choose to scan the factory function for dependencies in the form of require statements (literally in the form of require("module-string")). The first argument must literally be named require for this to work. In some situations module loaders may choose not to scan for dependencies due to code size limitations or lack of toString support on functions (Opera Mobile is known to lack toString support for functions). If either the first or second argument is present, the module loader SHOULD NOT scan for dependencies within the factory function.

define.amd property

To allow a clear indicator that a global define function (as needed for script src browser loading) conforms to the AMD API, any global define function SHOULD have a property called "amd" whose value is an object. This helps avoid conflict with any other existing JavaScript code that could have defined a define() function that does not conform to the AMD API.

The properties inside the define.amd object are not specified at this time. It can be used by implementers who want to inform what other capabilities beyond the basic API that the implementation supports.

Existence of the define.amd property with an object value indicates conformance with this API. If there is another version of the API, it will likely define another property, like define.amd2, to indicate implementations that conform to that version of the API.

An example of how it may be defined for an implementation that allows loading more than one version of a module in an environment:

 define.amd = {
   multiversion: true
 };

The minimum definition:

 define.amd = {};

Transporting more than one module at a time

Multiple define calls can be made within a single script. The order of the define calls SHOULD NOT be significant. Earlier module definitions may specify dependencies that are defined later in the same script. It is the responsibility of the module loader to defer loading unresolved dependencies until the entire script is loaded to prevent unnecessary requests.

Examples

Using require and exports

Sets up the module with ID of "alpha", that uses require, exports and the module with ID of "beta":

define("alpha", ["require", "exports", "beta"], function (require, exports, beta) {
    exports.verb = function() {
        return beta.verb();
        //Or:
        return require("beta").verb();
    }
});

An anonymous module could be defined (module id derived from filename) that returns an object literal:

define(["alpha"], function (alpha) {
    return {
      verb: function(){
        return alpha.verb() + 2;
      }
    };
});

A dependency-free module can define a direct object literal:

define({
  add: function(x, y){
    return x + y;
  }
});

Global Variables

This specification reserves the global variable "define" for use in implementing this specification, the package metadata asynchronous definition API and is reserved for other future CommonJS APIs. Module loaders SHOULD not add additional methods or properties to this function.

This specification reserves the global variable "require" for use by module loaders. Module loaders are free to use this global variable as they see fit. They may use the variable and add any properties or functions to it as desired for module loader specific functionality. They can also choose not to use "require" as well.

Usage notes

It is recommended that define calls be in the literal form of 'define(...)' in order to work properly with static analysis tools (like build tools).

This specification has used require.def() as the entry point in the past. Module loaders may choose to alias define() to require.def() to provide backwards compatibility (this is within the module loader's reserved namespace, so this is the prerogative of the module loader).