Merge pull request #187 from ParsePlatform/promises_es6

Implement Promise.catch, Promise.all, Promise.race

Author: andrewimm

src/ParsePromise.js

@@ -207,12 +207,21 @@ export default class ParsePromise {
 
   /**
    * Add handlers to be called when the Promise object is rejected
+   * Alias for catch().
    * @method fail
    */
   fail(callback) {
     return this.then(null, callback);
   }
 
+  /**
+   * Add handlers to be called when the Promise object is rejected
+   * @method catch
+   */
+  catch(callback) {
+    return this.then(null, callback);
+  }
+
   /**
    * Run the given callbacks after this promise is fulfilled.
    * @method _thenRunCallbacks
@@ -435,6 +444,115 @@ export default class ParsePromise {
     return promise;
   }
 
+  /**
+   * Returns a new promise that is fulfilled when all of the promises in the
+   * iterable argument are resolved. If any promise in the list fails, then
+   * the returned promise will be immediately rejected with the reason that
+   * single promise rejected. If they all succeed, then the returned promise
+   * will succeed, with the results being the results of all the input
+   * promises. If the iterable provided is empty, the returned promise will
+   * be immediately resolved.
+   * 
+   * For example: <pre>
+   *   var p1 = Parse.Promise.as(1);
+   *   var p2 = Parse.Promise.as(2);
+   *   var p3 = Parse.Promise.as(3);
+   *
+   *   Parse.Promise.all([p1, p2, p3]).then(function([r1, r2, r3]) {
+   *     console.log(r1);  // prints 1
+   *     console.log(r2);  // prints 2
+   *     console.log(r3);  // prints 3
+   *   });</pre>
+   *
+   * @method all
+   * @param {Iterable} promises an iterable of promises to wait for.
+   * @static
+   * @return {Parse.Promise} the new promise.
+   */
+  static all(promises) {
+    let total = 0;
+    let objects = [];
+
+    for (let p of promises) {
+      objects[total++] = p;
+    }
+
+    if (total === 0) {
+      return ParsePromise.as([]);
+    }
+
+    let hadError = false;
+    let promise = new ParsePromise();
+    let resolved = 0;
+    let results = [];
+    objects.forEach((object, i) => {
+      if (ParsePromise.is(object)) {
+        object.then((result) => {
+          if (hadError) {
+            return false;
+          }
+          results[i] = result;
+          resolved++;
+          if (resolved >= total) {
+            promise.resolve(results);
+          }
+        }, (error) => {
+          // Reject immediately
+          promise.reject(error);
+          hadError = true;
+        });
+      } else {
+        results[i] = object;
+        resolved++;
+        if (!hadError && resolved >= total) {
+          promise.resolve(results);
+        }
+      }
+    });
+
+    return promise;
+  }
+
+  /**
+   * Returns a new promise that is immediately fulfilled when any of the
+   * promises in the iterable argument are resolved or rejected. If the
+   * first promise to complete is resolved, the returned promise will be
+   * resolved with the same value. Likewise, if the first promise to
+   * complete is rejected, the returned promise will be rejected with the
+   * same reason.
+   *
+   * @method race
+   * @param {Iterable} promises an iterable of promises to wait for.
+   * @static
+   * @return {Parse.Promise} the new promise.
+   */
+  static race(promises) {
+    let completed = false;
+    let promise = new ParsePromise();
+    for (let p of promises) {
+      if (ParsePromise.is(p)) {
+        p.then((result) => {
+          if (completed) {
+            return;
+          }
+          completed = true;
+          promise.resolve(result);
+        }, (error) => {
+          if (completed) {
+            return;
+          }
+          completed = true;
+          promise.reject(error);
+        });
+      } else if (!completed) {
+        completed = true;
+        promise.resolve(p);
+      }
+    }
+
+    return promise;
+  }
+
   /**
    * Runs the given asyncFunction repeatedly, as long as the predicate
    * function returns a truthy value. Stops repeating if asyncFunction returns

src/__tests__/ParsePromise-test.js

@@ -14,6 +14,18 @@ var ParsePromise = require('../ParsePromise');
 var asyncHelper = require('./test_helpers/asyncHelper');
 
 describe('Promise', () => {
+  it('can disable A+ compliance', () => {
+    ParsePromise.disableAPlusCompliant();
+    expect(ParsePromise.isPromisesAPlusCompliant()).toBe(false);
+  });
+
+  it('can enable A+ compliance', () => {
+    ParsePromise.enableAPlusCompliant();
+    expect(ParsePromise.isPromisesAPlusCompliant()).toBe(true);
+  });
+});
+
+function promiseTests() {
   it('can be initially resolved', () => {
     var promise = ParsePromise.as('foo');
     promise.then((result) => {
@@ -297,6 +309,27 @@ describe('Promise', () => {
     jest.runAllTimers();
   }));
 
+  it('immediately resolves when processing an empty array in parallel', asyncHelper((done) => {
+    ParsePromise.when([]).then((result) => {
+      expect(result).toEqual([]);
+      done();
+    });
+  }));
+
+  it('can handle rejected promises in parallel', asyncHelper((done) => {
+    ParsePromise.when([ParsePromise.as(1), ParsePromise.error('an error')]).then(null, (errors) => {
+      expect(errors).toEqual([undefined, 'an error']);
+      done();
+    });
+  }));
+
+  it('can automatically resolve non-promises in parallel', asyncHelper((done) => {
+    ParsePromise.when([1,2,3]).then((results) => {
+      expect(results).toEqual([1,2,3]);
+      done();
+    });
+  }));
+
   it('passes on errors', () => {
     ParsePromise.error('foo').then(() => {
       // This should not be reached
@@ -428,6 +461,40 @@ describe('Promise', () => {
     });
   });
 
+  it('runs catch callbacks on error', () => {
+    var promise = ParsePromise.error('foo');
+    promise.fail((error) => {
+      expect(error).toBe('foo');
+    }).then((result) => {
+      if (ParsePromise.isPromisesAPlusCompliant()) {
+        expect(result).toBe(undefined);
+      } else {
+        // This should not be reached
+        expect(true).toBe(false);
+      }
+    }, (error) => {
+      if (ParsePromise.isPromisesAPlusCompliant()) {
+        // This should not be reached
+        expect(true).toBe(false);
+      } else {
+        expect(error).toBe(undefined);
+      }
+    });
+  });
+
+  it('does not run catch callbacks on success', () => {
+    var promise = ParsePromise.as('foo');
+    promise.catch((error) => {
+      // This should not be reached
+      expect(true).toBe(false);
+    }).then((result) => {
+      expect(result).toBe('foo');
+    }, (error) => {
+      // This should not be reached
+      expect(true).toBe(false);
+    });
+  });
+
   it('operates asynchonously', () => {
     var triggered = false;
     ParsePromise.as().then(() => {
@@ -518,4 +585,130 @@ describe('Promise', () => {
       done();
     });
   }));
+
+  it('resolves Promise.all with the set of resolved results', asyncHelper((done) => {
+    let firstSet = [
+      new ParsePromise(),
+      new ParsePromise(),
+      new ParsePromise(),
+      new ParsePromise()
+    ];
+
+    let secondSet = [5,6,7];
+
+    ParsePromise.all([]).then((results) => {
+      expect(results).toEqual([]);
+
+      return ParsePromise.all(firstSet);
+    }).then((results) => {
+      expect(results).toEqual([1,2,3,4]);
+      return ParsePromise.all(secondSet);
+    }).then((results) => {
+      expect(results).toEqual([5,6,7]);
+      done();
+    });
+    firstSet[0].resolve(1);
+    firstSet[1].resolve(2);
+    firstSet[2].resolve(3);
+    firstSet[3].resolve(4);
+  }));
+
+  it('rejects Promise.all with the first rejected promise', asyncHelper((done) => {
+    let promises = [
+      new ParsePromise(),
+      new ParsePromise(),
+      new ParsePromise()
+    ];
+
+    ParsePromise.all(promises).then(() => {
+      // this should not be reached
+    }, (error) => {
+      expect(error).toBe('an error');
+      done();
+    });
+    promises[0].resolve(1);
+    promises[1].reject('an error');
+    promises[2].resolve(3);
+  }));
+
+  it('resolves Promise.race with the first resolved result', asyncHelper((done) => {
+    let firstSet = [
+      new ParsePromise(),
+      new ParsePromise(),
+      new ParsePromise()
+    ];
+
+    let secondSet = [4, 5, ParsePromise.error()];
+
+    ParsePromise.race(firstSet).then((result) => {
+      expect(result).toBe(2);
+
+      return ParsePromise.race(secondSet);
+    }).then((result) => {
+      expect(result).toBe(4);
+      done();
+    });
+    firstSet[1].resolve(2);
+    firstSet[0].resolve(1);
+  }));
+
+  it('rejects Promise.race with the first rejected reason', asyncHelper((done) => {
+    let promises = [
+      new ParsePromise(),
+      new ParsePromise(),
+      new ParsePromise()
+    ];
+
+    ParsePromise.race(promises).fail((error) => {
+      expect(error).toBe('error 2');
+      done();
+    });
+    promises[1].reject('error 2');
+    promises[0].resolve('error 1');
+  }));
+
+  it('can implement continuations', asyncHelper((done) => {
+    let count = 0;
+    let loop = () => {
+      count++;
+      return ParsePromise.as();
+    }
+    ParsePromise._continueWhile(
+      () => { return count < 5 },
+      loop
+    ).then(() => {
+      expect(count).toBe(5);
+      done();
+    });
+  }));
+
+  it('can attach a universal callback to a promise', asyncHelper((done) => {
+    ParsePromise.as(15)._continueWith((result, err) => {
+      expect(result).toEqual([15]);
+      expect(err).toBe(null);
+
+      ParsePromise.error('an error')._continueWith((result, err) => {
+        expect(result).toBe(null);
+        expect(err).toBe('an error');
+
+        done();
+      });
+    });
+  }));
+}
+
+describe('Promise (A Compliant)', () => {
+  beforeEach(() => {
+    ParsePromise.disableAPlusCompliant();
+  });
+
+  promiseTests();
+});
+
+describe('Promise (A+ Compliant)', () => {
+  beforeEach(() => {
+    ParsePromise.enableAPlusCompliant();
+  });
+
+  promiseTests();
 });