CommonJS Reference Framework (version 0.5, this post is still under edit!)
To get order in the chaos the CommonJS Reference Framework is defined which describes the interaction between the basic CommonJS layers:
In this picture three main blocks can be depicted:
In the next chapters the high level use of those layers will be described.
This is the basic CommonJS layer with stores for Module, Package and Context definitions and functions for manipulating those stores and the host environment. The total CommonJS Environment consists of an ECMAScript execution environment embedded in an application such as a web browser or scripting host, known as the host environment. In an addition to the ECMAScript interpreter, the CommonJS environment provides a facility for loading and executing ECMAScript known as the CommonJS module and package system, and bootstrapping facilities that allow us to initialize and execute CommonJS scripts.
In this layer several specific subsystems can be defined, depending on the required level of implementation of CommonJS core elements (Module, Package, Context). Those subsystems work together as a sort of Matryoshka doll. The lowest level of implementation of the CommonJS System Layer is the implementation of the Module System. The second level is the use of Packages to group modules in 'package environments' for easy deployability and shareability. The last layer is the use of Contexts to be able to implement separate module/package environments in one host
The notion of Context is not yet defined or even discussed in the CommonJS group!! Just defined to show how easy it can be to add new functionality to the Core System Layer.
The relation between the host environment and the core CommonJS elements are depicted in the next image:
Add distinction that in the same context environment module exports of the same module in the same package are identical. This is not the case between module exports of the same package in another context environment!! So between context environments only the Factory Function is reused not the created exports!!
If we look at implementing those core elements in the Core Systems Layer we get the following picture:
In the host at least one (secure) contexts will exist. A context has one (and only one) context environment. A context environment can be seen as a configurable package and its package UID is 'commonjs.org'. In the host initialization phase at least one context will be defined. The standard configuration of that context environment will be defined in the 'Context' standards. The CommonJS Context System performs x main tasks:
The context environment (with UID = 'commonjs.org') has a defined module namespace root. This is the location of which the module identifiers are resolved. This location can be a root in a database, a directory or folder in a file system or a URI to a remote or local location with context environment modules. See the newest Context/x.x specification for more information about the CommonJS Context System.
The CommonJS package system performs x main tasks:
In the Package Definition Store the static and dynamically obtained Package Descriptors are stored for later use by the other Systems. The data in the store can be used to get the Mappings field of a Package Descriptor or other package meta information.
In the Registry Store static and dynamic learned Package UID to Package URI translations are stored for later use by the Generic Loader System. The data in the store can be used to get a location for a package only referenced by a Package UID in for example the Mappings field of a loaded Package Configuration or a call to the mappings function of the Module API.
I've put the Registry store in this system but it could be argued to implement a seperate Registry System like Context/Package/Module Systems
The CommonJS module system performs x main tasks:
The CommonJS Core system performs x main tasks:
The Generic Module System performs x main tasks:
<Add generic description>
The Generic Loader System performs x main tasks:
The module.registerPlugin function accepts an object with the following possible properties referring to an function:
The registerPlugin function returns an object describing access to the Loader API functions.
A CommonJS module code section (Module Environment) is the group of expressions contained within a module factory function. Any series of ECMAScript expressions that can be parsed as an ECMAScript FunctionBody may be used as a module code section.
CommonJS modules may be stored as any type of resource, including local files, remote URLs, database entries, and so on. The storage mechanism of a module is relevant only to the environment’s built-in module provider and not to the defined module itself.
The module environment has at a minimum access to three APIs
Those three APIs are injected as free variables in the Module Environment via arguments in the Module Factory Function (browser hosts) or via other kind of implementations (scripting hosts).
How are Specific Loader System Plugins with specific loader functions coupled with the Core CommonJS System (Loader API/Generic Loader System). Think of plugins being coupled from within modules or plugins coupled from the extra module environment i.e. basic global script code
This layer defines methods/protocols for transmitting module source code, package definitions, registry information or repository information from a (web) server to a scripting host (like a browser page).
Describe some basic Transport Protocols in a high level fashion. Details must be specified in specific Transport specification documents.
High level Examples of flow cases. For example Module dynamically requests another module but that module is not available in exports and Module Store System so it needs to be loaded through the loader etc etc.
Here all definitions need to be inserted. Please help with definitions!!!
General Article To do:
What needs to be investigated and added to this article: