feat($q): implement $q.race

Implement $q.race. $q.race takes in an array or hash of promises and
returns a promsie that is resolved as soon as the first promise is
resolved.

Closes angular#12929

Author: yihangho

src/ng/q.js

@@ -636,6 +636,34 @@ function qFactory(nextTick, exceptionHandler, errorOnUnhandledRejections) {
     return deferred.promise;
   }
 
+  /**
+   * @ngdoc method
+   * @name $q#race
+   * @kind function
+   *
+   * @description
+   * Returns a promise that is resolved similarly as the first promise to resolve.
+   *
+   * @param {Array.<Promise>|Object.<Promise>} promises An array or hash of promises.
+   * @returns {Promise} Returns a promise that will be resolved as soon as the first promise in
+   *   `promises` is resolved. The resolved value will be the same as the value of the first
+   *   resolved promise.
+   */
+
+  function race(promises) {
+    var deferred = new Deferred();
+
+    forEach(promises, function(promise) {
+      when(promise).then(function(value) {
+        deferred.resolve(value);
+      }, function(reason) {
+        deferred.reject(reason);
+      });
+    });
+
+    return deferred.promise;
+  }
+
   var $Q = function Q(resolver) {
     if (!isFunction(resolver)) {
       throw $qMinErr('norslvr', "Expected resolverFn, got '{0}'", resolver);
@@ -665,6 +693,7 @@ function qFactory(nextTick, exceptionHandler, errorOnUnhandledRejections) {
   $Q.when = when;
   $Q.resolve = resolve;
   $Q.all = all;
+  $Q.race = race;
 
   return $Q;
 }

test/ng/qSpec.js

@@ -1986,6 +1986,42 @@ describe('q', function() {
     });
   });
 
+  describe('race', 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('exception logging', function() {
     var mockExceptionLogger = {
       log: [],