Fixed #34. Added AV.Promise#catch,AV.Promise.race etc.

Author: killme2008

lib/promise.js

@@ -8,26 +8,44 @@
    * called when the async task is fulfilled.
    *
    * <p>Typical usage would be like:<pre>
-   *    query.findAsync().then(function(results) {
+   *    query.find().then(function(results) {
    *      results[0].set("foo", "bar");
    *      return results[0].saveAsync();
    *    }).then(function(result) {
    *      console.log("Updated " + result.id);
    *    });
    * </pre></p>
-   *
-   * @see AV.Promise.prototype.next
+   * <p>Another example:<pre>
+   *    var promise = new AV.Promise(function(resolve, reject) {
+   *      resolve(42);
+   *    });
+   *    promise.then(function(value){
+   *      console.log(value);
+   *    }).catch(function(error){
+   *      console.error(error);
+   *    });
+   * </pre></p>
+   * @param {Function} fn An optional function with two arguments resolve
+   *                   and reject.The first argument fulfills the promise,
+   *                   the second argument rejects it. We can call these
+    *                  functions, once our operation is completed.
+   * @see AV.Promise.prototype.then
    * @class
    */
-  AV.Promise = function() {
+  AV.Promise = function(fn) {
     this._resolved = false;
     this._rejected = false;
     this._resolvedCallbacks = [];
     this._rejectedCallbacks = [];
+
+    this.doResolve(fn);
+    return this;
   };
 
   _.extend(AV.Promise, /** @lends AV.Promise */ {
 
+    _isPromisesAPlusCompliant: false,
+
     /**
      * Returns true iff the given object fulfils the Promise interface.
      * @return {Boolean}
@@ -60,12 +78,30 @@
      * Returns a new promise that is fulfilled when all of the input promises
      * are resolved. If any promise in the list fails, then the returned promise
      * will fail with the last error. If they all succeed, then the returned
-     * promise will succeed, with the result being an array with the results of
-     * all the input promises.
+     * promise will succeed, with the results being the results of all the input
+     * promises. For example: <pre>
+     *   var p1 = AV.Promise.as(1);
+     *   var p2 = AV.Promise.as(2);
+     *   var p3 = AV.Promise.as(3);
+     *
+     *   AV.Promise.when(p1, p2, p3).then(function(r1, r2, r3) {
+     *     console.log(r1);  // prints 1
+     *     console.log(r2);  // prints 2
+     *     console.log(r3);  // prints 3
+     *   });</pre>
+     *
+     * The input promises can also be specified as an array: <pre>
+     *   var promises = [p1, p2, p3];
+     *   AV.Promise.when(promises).then(function(r1, r2, r3) {
+     *     console.log(r1);  // prints 1
+     *     console.log(r2);  // prints 2
+     *     console.log(r3);  // prints 3
+     *   });
+     * </pre>
      * @param {Array} promises a list of promises to wait for.
      * @return {AV.Promise} the new promise.
      */
-    when: function(promises) {
+    when: function(promises, isAll) {
       // Allow passing in Promises as separate arguments instead of an Array.
       var objects;
       if (promises && AV._isNullOrUndefined(promises.length)) {
@@ -82,7 +118,11 @@
       errors.length = objects.length;
 
       if (total === 0) {
-        return AV.Promise.as.apply(this, results);
+        if(isAll) {
+          return AV.Promise.as.call(this, results);
+        } else {
+          return AV.Promise.as.apply(this, results);
+        }
       }
 
       var promise = new AV.Promise();
@@ -93,7 +133,11 @@
           if (hadError) {
             promise.reject(errors);
           } else {
-            promise.resolve.apply(promise, results);
+            if(isAll) {
+              promise.resolve.call(promise, results);
+            } else {
+              promise.resolve.apply(promise, results);
+            }
           }
         }
       };
@@ -117,6 +161,82 @@
       return promise;
     },
 
+    /**
+     * Returns a promise that resolves or rejects as soon as one
+     * of the promises in the iterable resolves or rejects, with
+     * the value or reason from that promise.Returns a new promise
+     * that is fulfilled when one of the input promises.
+     * For example: <pre>
+     *   var p1 = AV.Promise.as(1);
+     *   var p2 = AV.Promise.as(2);
+     *   var p3 = AV.Promise.as(3);
+     *
+     *   AV.Promise.race(p1, p2, p3).then(function(result) {
+     *     console.log(result);  // prints 1
+     *   });</pre>
+     *
+     * The input promises can also be specified as an array: <pre>
+     *   var promises = [p1, p2, p3];
+     *   AV.Promise.when(promises).then(function(result) {
+     *     console.log(result);  // prints 1
+     *   });
+     * </pre>
+     * @param {Array} promises a list of promises to wait for.
+     * @return {AV.Promise} the new promise.
+     */
+    race: function(promises) {
+      // Allow passing in Promises as separate arguments instead of an Array.
+      var objects;
+      if (promises && AV._isNullOrUndefined(promises.length)) {
+        objects = arguments;
+      } else {
+        objects = promises;
+      }
+
+      var total = objects.length;
+      var hadError = false;
+      var isResolved = false;
+      var results = [];
+      var errors = [];
+
+      results.length = errors.length = objects.length;
+
+      if (total === 0) {
+        return AV.Promise.as.apply(this, result);
+      }
+
+      var promise = new AV.Promise();
+
+      var resolveOne = function(i) {
+        if (!isResolved) {
+          isResolved = true;
+          if (hadError) {
+            promise.reject(errors[i]);
+          } else {
+            promise.resolve.call(promise, results[i]);
+          }
+        }
+      };
+
+      AV._arrayEach(objects, function(object, i) {
+        if (AV.Promise.is(object)) {
+          object.then(function(result) {
+            results[i] = result;
+            resolveOne(i);
+          }, function(error) {
+            errors[i] = error;
+            hadError = true;
+            resolveOne(i);
+          });
+        } else {
+          results[i] = object;
+          resolveOne();
+        }
+      });
+
+      return promise;
+    },
+
     /**
      * Runs the given asyncFunction repeatedly, as long as the predicate
      * function returns a truthy value. Stops repeating if asyncFunction returns
@@ -134,6 +254,15 @@
     }
   });
 
+  /**
+   * Just like AV.Promise.when, but it calls resolveCallbck function
+   * with one results array.
+   * @see AV.Promise.all
+   */
+  AV.Promise.all = function(promises) {
+    return AV.Promise.when(promises, true);
+  };
+
   _.extend(AV.Promise.prototype, /** @lends AV.Promise.prototype */ {
 
     /**
@@ -155,6 +284,27 @@
       this._rejectedCallbacks = [];
     },
 
+    doResolve: function(fn){
+      if (!fn) return;
+      var done = false;
+      var self = this;
+      try {
+        fn(function (value) {
+          if (done) return;
+          done = true;
+          self.resolve(value);
+        }, function (reason) {
+             if (done) return;
+             done = true;
+             self.reject(reason);
+        })
+      } catch (ex) {
+        if (done) return;
+        done = true;
+        self.reject(ex);
+      }
+    },
+
     /**
      * Marks this promise as fulfilled, firing any callbacks waiting on it.
      * @param {Object} error the error to pass to the callbacks.
@@ -198,7 +348,15 @@
       var wrappedResolvedCallback = function() {
         var result = arguments;
         if (resolvedCallback) {
-          result = [resolvedCallback.apply(this, result)];
+          if (AV.Promise._isPromisesAPlusCompliant) {
+            try {
+              result = [resolvedCallback.apply(this, result)];
+            } catch (e) {
+              result = [AV.Promise.error(e)];
+            }
+          } else {
+            result = [resolvedCallback.apply(this, result)];
+          }
         }
         if (result.length === 1 && AV.Promise.is(result[0])) {
           result[0].then(function() {
@@ -214,27 +372,57 @@
       var wrappedRejectedCallback = function(error) {
         var result = [];
         if (rejectedCallback) {
-          result = [rejectedCallback(error)];
+          if (AV.Promise._isPromisesAPlusCompliant) {
+            try {
+              result = [rejectedCallback(error)];
+            } catch (e) {
+              result = [AV.Promise.error(e)];
+            }
+          } else {
+            result = [rejectedCallback(error)];
+          }
           if (result.length === 1 && AV.Promise.is(result[0])) {
             result[0].then(function() {
               promise.resolve.apply(promise, arguments);
             }, function(error) {
               promise.reject(error);
             });
           } else {
-            // A Promises/A+ compliant implementation would call:
-            // promise.resolve.apply(promise, result);
-            promise.reject(result[0]);
+            if (AV.Promise._isPromisesAPlusCompliant) {
+              promise.resolve.apply(promise, result);
+            } else {
+              promise.reject(result[0]);
+            }
           }
         } else {
           promise.reject(error);
         }
       };
 
+      var runLater = function(func) {
+        func.call();
+      };
+      if (AV.Promise._isPromisesAPlusCompliant) {
+        if (typeof(window) !== 'undefined' && window.setTimeout) {
+          runLater = function(func) {
+            window.setTimeout(func, 0);
+          };
+        } else if (typeof(process) !== 'undefined' && process.nextTick) {
+          runLater = function(func) {
+            process.nextTick(func);
+          };
+        }
+      }
+
+      var self = this;
       if (this._resolved) {
-        wrappedResolvedCallback.apply(this, this._result);
+        runLater(function() {
+          wrappedResolvedCallback.apply(self, self._result);
+        });
       } else if (this._rejected) {
-        wrappedRejectedCallback(this._error);
+        runLater(function() {
+          wrappedRejectedCallback(self._error);
+        });
       } else {
         this._resolvedCallbacks.push(wrappedResolvedCallback);
         this._rejectedCallbacks.push(wrappedRejectedCallback);
@@ -243,6 +431,50 @@
       return promise;
     },
 
+    /**
+     * Appends a rejection handler callback to the promise,
+     * and returns a new promise resolving to the return value
+     * of the callback if it is called, or to its original
+     * fulfillment value if the promise is instead fulfilled.In fact,
+     * it is equals to promise.then(undefined, onRejected).
+     *
+     * @see AV.Promise.prototype.then
+     * @param {Function} onRejected Function that is called when this
+     * Promise is rejected with an error. Once the callback is complete, then
+     * the promise returned by "then" with be resolved successfully. If
+     * rejectedCallback is null, or it returns a rejected Promise, then the
+     * Promise returned by "then" will be rejected with that error.
+     * @return {AV.Promise} A new Promise that will be fulfilled after this
+     * Promise is fulfilled and either callback has completed. If the callback
+     * returned a Promise, then this Promise will not be fulfilled until that
+     * one is.
+     */
+    catch: function(onRejected) {
+      return this.then(undefined, onRejected);
+    },
+
+    /**
+     * Add handlers to be called when the promise
+     * is either resolved or rejected
+     */
+    always: function(callback) {
+      return this.then(callback, callback);
+    },
+
+    /**
+     * Add handlers to be called when the Promise object is resolved
+     */
+    done: function(callback) {
+      return this.then(callback);
+    },
+
+    /**
+     * Add handlers to be called when the Promise object is rejected
+     */
+    fail: function(callback) {
+      return this.then(null, callback);
+    },
+
     /**
      * Run the given callbacks after this promise is fulfilled.
      * @param optionsOrCallback {} A Backbone-style options callback, or a