feat($q): implement $q.race

Implement $q.race. $q.race takes in an array or hash of promises and
returns a promise that resolves or rejects as soon as one of those promises
resolves or rejects, with the value or reason from that promise.

Closes #12929
Closes #14757

Author: yihangho

src/ng/q.js

@@ -562,6 +562,30 @@ function qFactory(nextTick, exceptionHandler) {
     return deferred.promise;
   }
 
+  /**
+   * @ngdoc method
+   * @name $q#race
+   * @kind function
+   *
+   * @description
+   * Returns a promise that resolves or rejects as soon as one of those promises
+   * resolves or rejects, with the value or reason from that promise.
+   *
+   * @param {Array.<Promise>|Object.<Promise>} promises An array or hash of promises.
+   * @returns {Promise} a promise that resolves or rejects as soon as one of the `promises`
+   * resolves or rejects, with the value or reason from that promise.
+   */
+
+  function race(promises) {
+    var deferred = defer();
+
+    forEach(promises, function(promise) {
+      when(promise).then(deferred.resolve, deferred.reject);
+    });
+
+    return deferred.promise;
+  }
+
   var $Q = function Q(resolver) {
     if (!isFunction(resolver)) {
       throw $qMinErr('norslvr', "Expected resolverFn, got '{0}'", resolver);
@@ -591,6 +615,7 @@ function qFactory(nextTick, exceptionHandler) {
   $Q.when = when;
   $Q.resolve = resolve;
   $Q.all = all;
+  $Q.race = race;
 
   return $Q;
 }

test/ng/qSpec.js

@@ -1972,6 +1972,78 @@ describe('q', function() {
     });
   });
 
+  describe('race (array)', function() {
+    it('should do nothing if given an empty array', function() {
+      q.race([]).then(success(), error());
+      expect(mockNextTick.queue.length).toBe(0);
+      expect(logStr()).toBe('');
+    });
+
+    it('should resolve as soon as the first promise is settled by resolution', function() {
+      var deferred1 = defer(),
+          deferred2 = defer();
+
+      q.race([promise, deferred1.promise, deferred2.promise]).then(success(), error());
+      expect(logStr()).toBe('');
+      syncResolve(deferred1, 'hi');
+      expect(logStr()).toBe('success(hi)->hi');
+      syncResolve(deferred2, 'cau');
+      expect(logStr()).toBe('success(hi)->hi');
+      syncReject(deferred, 'hola');
+      expect(logStr()).toBe('success(hi)->hi');
+    });
+
+    it('should reject as soon as the first promise is settled by rejection', function() {
+      var deferred1 = defer(),
+          deferred2 = defer();
+
+      q.race([promise, deferred1.promise, deferred2.promise]).then(success(), error());
+      expect(logStr()).toBe('');
+      syncReject(deferred1, 'hi');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+      syncResolve(deferred2, 'cau');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+      syncReject(deferred, 'hola');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+    });
+  });
+
+  describe('race (hash)', function() {
+    it('should do nothing if given an empty array', function() {
+      q.race({}).then(success(), error());
+      expect(mockNextTick.queue.length).toBe(0);
+      expect(logStr()).toBe('');
+    });
+
+    it('should resolve as soon as the first promise is settled by resolution', function() {
+      var deferred1 = defer(),
+          deferred2 = defer();
+
+      q.race({a: promise, b: deferred1.promise, c: deferred2.promise}).then(success(), error());
+      expect(logStr()).toBe('');
+      syncResolve(deferred1, 'hi');
+      expect(logStr()).toBe('success(hi)->hi');
+      syncResolve(deferred2, 'cau');
+      expect(logStr()).toBe('success(hi)->hi');
+      syncReject(deferred, 'hola');
+      expect(logStr()).toBe('success(hi)->hi');
+    });
+
+    it('should reject as soon as the first promise is settled by rejection', function() {
+      var deferred1 = defer(),
+          deferred2 = defer();
+
+      q.race({a: promise, b: deferred1.promise, c: deferred2.promise}).then(success(), error());
+      expect(logStr()).toBe('');
+      syncReject(deferred1, 'hi');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+      syncResolve(deferred2, 'cau');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+      syncReject(deferred, 'hola');
+      expect(logStr()).toBe('error(hi)->reject(hi)');
+    });
+  });
+
   describe('exception logging', function() {
     var mockExceptionLogger = {
       log: [],