Added design rationale documentation.

design/q0.js

@@ -0,0 +1,22 @@
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            value = _value;
+            for (var i = 0, ii = pending.length; i < ii; i++) {
+                var callback = pending[i];
+                callback(value);
+            }
+            pending = undefined;
+        },
+        then: function (callback) {
+            if (pending) {
+                pending.push(callback);
+            } else {
+                callback(value);
+            }
+        }
+    }
+};
+

design/q1.js

@@ -0,0 +1,26 @@
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = _value;
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    var callback = pending[i];
+                    callback(value);
+                }
+                pending = undefined;
+            } else {
+                throw new Error("A promise can only be resolved once.");
+            }
+        },
+        then: function (callback) {
+            if (pending) {
+                pending.push(callback);
+            } else {
+                callback(value);
+            }
+        }
+    }
+};
+

design/q2.js

@@ -0,0 +1,33 @@
+
+var Promise = function () {
+};
+
+var isPromise = function (value) {
+    return value instanceof Promise;
+};
+
+var defer = function () {
+    var pending = [], value;
+    var promise = new Promise();
+    promise.then = function (callback) {
+        if (pending) {
+            pending.push(callback);
+        } else {
+            callback(value);
+        }
+    };
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = _value;
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    var callback = pending[i];
+                    callback(value);
+                }
+                pending = undefined;
+            }
+        },
+        promise: promise
+    };
+};
+

design/q3.js

@@ -0,0 +1,30 @@
+
+var isPromise = function (value) {
+    return value && typeof value.then === "function";
+};
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = _value;
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    var callback = pending[i];
+                    callback(value);
+                }
+                pending = undefined;
+            }
+        },
+        promise: {
+            then: function (callback) {
+                if (pending) {
+                    pending.push(callback);
+                } else {
+                    callback(value);
+                }
+            }
+        }
+    };
+};
+

design/q4.js

@@ -0,0 +1,48 @@
+
+var isPromise = function (value) {
+    return value && typeof value.then === "function";
+};
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = ref(_value); // values wrapped in a promise
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    var callback = pending[i];
+                    value.then(callback); // then called instead
+                }
+                pending = undefined;
+            }
+        },
+        promise: {
+            then: function (_callback) {
+                var result = defer();
+                // callback is wrapped so that its return
+                // value is captured and used to resolve the promise
+                // that "then" returns
+                var callback = function (value) {
+                    result.resolve(_callback(value));
+                };
+                if (pending) {
+                    pending.push(callback);
+                } else {
+                    value.then(callback);
+                }
+                return result.promise;
+            }
+        }
+    };
+};
+
+var ref = function (value) {
+    if (value && typeof value.then === "function")
+        return value;
+    return {
+        then: function (callback) {
+            return ref(callback(value));
+        }
+    };
+};
+

design/q5.js

@@ -0,0 +1,56 @@
+
+var isPromise = function (value) {
+    return value && typeof value.then === "function";
+};
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = ref(_value);
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    // apply the pending arguments to "then"
+                    value.then.apply(value, pending[i]);
+                }
+                pending = undefined;
+            }
+        },
+        promise: {
+            then: function (_callback, _errback) {
+                var result = defer();
+                var callback = function (value) {
+                    result.resolve(_callback(value));
+                };
+                var errback = function (reason) {
+                    result.resolve(_errback(reason));
+                };
+                if (pending) {
+                    pending.push([callback, errback]);
+                } else {
+                    value.then(callback, errback);
+                }
+                return result.promise;
+            }
+        }
+    };
+};
+
+var ref = function (value) {
+    if (value && typeof value.then === "function")
+        return value;
+    return {
+        then: function (callback) {
+            return ref(callback(value));
+        }
+    };
+};
+
+var reject = function (reason) {
+    return {
+        then: function (callback, errback) {
+            return ref(errback(reason));
+        }
+    };
+};
+

design/q6.js

@@ -0,0 +1,64 @@
+
+var isPromise = function (value) {
+    return value && typeof value.then === "function";
+};
+
+var defer = function () {
+    var pending = [], value;
+    return {
+        resolve: function (_value) {
+            if (pending) {
+                value = ref(_value);
+                for (var i = 0, ii = pending.length; i < ii; i++) {
+                    value.then.apply(value, pending[i]);
+                }
+                pending = undefined;
+            }
+        },
+        promise: {
+            then: function (_callback, _errback) {
+                var result = defer();
+                // provide default callbacks and errbacks
+                _callback = _callback || function (value) {
+                    // by default, forward fulfillment
+                    return value;
+                };
+                _errback = _errback || function (reason) {
+                    // by default, forward rejection
+                    return reject(reason);
+                };
+                var callback = function (value) {
+                    result.resolve(_callback(value));
+                };
+                var errback = function (reason) {
+                    result.resolve(_errback(reason));
+                };
+                if (pending) {
+                    pending.push([callback, errback]);
+                } else {
+                    value.then(callback, errback);
+                }
+                return result.promise;
+            }
+        }
+    };
+};
+
+var ref = function (value) {
+    if (value && typeof value.then === "function")
+        return value;
+    return {
+        then: function (callback) {
+            return ref(callback(value));
+        }
+    };
+};
+
+var reject = function (reason) {
+    return {
+        then: function (callback, errback) {
+            return ref(errback(reason));
+        }
+    };
+};
+