├── README.md └── draft ├── module.md ├── package.md └── transport.md /README.md: -------------------------------------------------------------------------------- 1 | # Common Module 2 | 3 | Specifications about common module. 4 | 5 | 6 | ## Thanks 7 | 8 | 1. [commonjs](http://wiki.commonjs.org/) 9 | 2. [uncommonjs](https://github.com/kriskowal/uncommonjs) 10 | 3. [nodejs](http://nodejs.org/) 11 | -------------------------------------------------------------------------------- /draft/module.md: -------------------------------------------------------------------------------- 1 | # Common Module Definition / draft 2 | 3 | ------ 4 | 5 | This specification addresses how modules should be written in order to be interoperable in **browser-based** environment. By implication, this specification defines the minimum features that a module system must provide in order to support interoperable modules. 6 | 7 | - Modules are singletons. 8 | - New free variables within the module scope should not be introduced. 9 | - Execution must be lazy. 10 | 11 | 12 | 13 | ## Module Definition 14 | 15 | A module is defined with `define` keyword, which is a function. 16 | 17 | ```js 18 | define(factory); 19 | ``` 20 | 21 | 1. The `define` function accepts a single argument, the module factory. 22 | 1. The `factory` may be a function or other valid values. 23 | 1. If `factory` is a function, the first three parameters of the function, if specified, must be "require", "exports", and "module", in that order. 24 | 1. If `factory` is not a function, then the module's exports are set to that object. 25 | 26 | 27 | 28 | ## Module Context 29 | 30 | In a module, there are three free variables: `require`, `exports` and `module`. 31 | 32 | ```js 33 | define(function(require, exports, module) { 34 | 35 | // The module code goes here 36 | 37 | }); 38 | ``` 39 | 40 | 41 | ### The `require` Function 42 | 43 | 1. `require` is a function 44 | 45 | 1. `require` accepts a module identifier. 46 | 1. `require` returns the exported API of the foreign module. 47 | 1. If requested module cannot be returned, `require` should return null. 48 | 49 | 1. `require.async` is a function 50 | 51 | 1. `require.async` accepts a list of module identifiers and a optional callback function. 52 | 1. The callback function receives module exports as function arguments, listed in the same order as the order in the first argument. 53 | 1. If requested module cannot be returned, the callback should receive null correspondingly. 54 | 55 | 56 | 57 | ### The `exports` Object 58 | 59 | In a module, there is a free variable called "exports", that is an object that the module may add its API to as it executes. 60 | 61 | 62 | ### The `module` Object 63 | 64 | 1. `module.uri` 65 | 66 | The full resolved uri to the module. 67 | 68 | 1. `module.dependencies` 69 | 70 | A list of module identifiers that required by the module. 71 | 72 | 1. `module.exports` 73 | 74 | The exported API of the module. It is the same as `exports` object. 75 | 76 | 77 | 78 | ## Module Identifier 79 | 80 | 1. A module identifier is and must be a **literal** string. 81 | 2. Module identifiers may not have a filename extensions like `.js`. 82 | 3. Module identifiers should be dash-joined string, such as `foo-bar`. 83 | 4. Module identifiers can be a relative path, like `./foo` and `../bar`. 84 | 85 | 86 | 87 | ## Sample Code 88 | 89 | 90 | **A typical sample** 91 | 92 | math.js 93 | ```js 94 | define(function(require, exports, module) { 95 | exports.add = function() { 96 | var sum = 0, i = 0, args = arguments, l = args.length; 97 | while (i < l) { 98 | sum += args[i++]; 99 | } 100 | return sum; 101 | }; 102 | }); 103 | ``` 104 | 105 | increment.js 106 | ```js 107 | define(function(require, exports, module) { 108 | var add = require('math').add; 109 | exports.increment = function(val) { 110 | return add(val, 1); 111 | }; 112 | }); 113 | ``` 114 | 115 | program.js 116 | ```js 117 | define(function(require, exports, module) { 118 | var inc = require('increment').increment; 119 | var a = 1; 120 | inc(a); // 2 121 | 122 | module.id == "program"; 123 | }); 124 | ``` 125 | 126 | 127 | **Wrapped modules with non-function factory** 128 | 129 | object-data.js 130 | ```js 131 | define({ 132 | foo: "bar" 133 | }); 134 | ``` 135 | 136 | array-data.js 137 | ```js 138 | define([ 139 | 'foo', 140 | 'bar' 141 | ]); 142 | ``` 143 | 144 | string-data.js 145 | ``` 146 | define('foo bar'); 147 | ``` 148 | -------------------------------------------------------------------------------- /draft/package.md: -------------------------------------------------------------------------------- 1 | # Packaging / draft 2 | 3 | ----- 4 | 5 | 6 | ## Package Descriptor File 7 | 8 | Each package must provide a top-level package descriptor, "package.json". 9 | 10 | 11 | ### Required Fields 12 | 13 | - family 14 | - name 15 | - version 16 | 17 | 18 | ### Optional Fields 19 | 20 | - description 21 | - keywords 22 | - author 23 | - repository 24 | - bugs 25 | - license 26 | - scripts 27 | 28 | ## Extendable Fields 29 | 30 | 31 | ## Sample Code 32 | 33 | **A typical sample** 34 | 35 | ``` 36 | { 37 | "family": "arale", 38 | "name": "overlay", 39 | "version": "1.0.0", 40 | "description": "Overlay is a mask covering.", 41 | "keywords": ["mask", "dom"], 42 | "author": "Hsiaoming Yang ", 43 | "repository": { 44 | "type": "git", 45 | "url": "https://github.com/arale/overlay.git" 46 | }, 47 | "bugs": { 48 | "url": "https://github.com/arale/overlay/issues" 49 | }, 50 | "license": { 51 | "type": "BSD", 52 | "url": "http://opensource.org/licenses/BSD-2-Clause" 53 | }, 54 | "scripts": { 55 | "prebuild": "prebuild.js", 56 | "test": "make test" 57 | } 58 | } 59 | ``` 60 | 61 | **A mininal sample** 62 | 63 | ``` 64 | { 65 | "family": "arale", 66 | "name": "overlay", 67 | "version": "1.0.0" 68 | } 69 | ``` 70 | -------------------------------------------------------------------------------- /draft/transport.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmdjs/specification/3ec033e973738295d284c00cdf448d29210984dd/draft/transport.md --------------------------------------------------------------------------------