feat($qRaf): introduce requestAnimationFrame-based promise service

Author: matsko

lib/promises-aplus/promises-aplus-test-adapter.js

@@ -11,7 +11,8 @@ var minErr = function minErr (module, constructor) {
   };
 };
 
-var $q = qFactory(process.nextTick, function noopExceptionHandler() {});
+var noop = function() {};
+var $q = qFactory(noop, process.nextTick, noop);
 
 exports.resolved = $q.resolve;
 exports.rejected = $q.reject;

src/AngularPublic.js

@@ -74,6 +74,7 @@
   $RootScopeProvider,
   $QProvider,
   $$QProvider,
+  $QRafProvider,
   $$SanitizeUriProvider,
   $SceProvider,
   $SceDelegateProvider,
@@ -231,6 +232,7 @@ function publishExternalAPI(angular) {
         $rootScope: $RootScopeProvider,
         $q: $QProvider,
         $$q: $$QProvider,
+        $qRaf: $QRafProvider,
         $sce: $SceProvider,
         $sceDelegate: $SceDelegateProvider,
         $sniffer: $SnifferProvider,

src/ng/q.js

@@ -213,32 +213,72 @@
  * @returns {Promise} The newly created promise.
  */
 function $QProvider() {
-
   this.$get = ['$rootScope', '$exceptionHandler', function($rootScope, $exceptionHandler) {
-    return qFactory(function(callback) {
+    return qFactory(noop, function(callback, data) {
       $rootScope.$evalAsync(callback);
     }, $exceptionHandler);
   }];
 }
 
 function $$QProvider() {
   this.$get = ['$browser', '$exceptionHandler', function($browser, $exceptionHandler) {
-    return qFactory(function(callback) {
+    return qFactory(noop, function(callback, data) {
       $browser.defer(callback);
     }, $exceptionHandler);
   }];
 }
 
+/**
+ * @ngdoc service
+ * @name $qRaf
+ *
+ * @description
+ * `$qRaf` is a promise library that coordinates itself based on calls to `requestAnimationFrame`. The
+ * purpose of `$qRaf` is to allow animation-based code to be sequenced together without the need
+ * to hook into the digest cycle (which is how `$q` works).
+ *
+ * `$qRaf` is gauranteed to be delivered once one or more animation frames have passed. This means that
+ * even if the promise is resolved immediately then it will not be delivered until the next frame has passed.
+ * However if an animation does occur in between promise creation and resolution then the promise
+ * will be delivered immediately. This simple mechanism of flow control allows for animation callback
+ * code to avoid any unnecessary pauses. Any pause that occurs within an animation may lead to an
+ * unexpected reflow or page flicker and `$qRaf` aims to avoid this problem completely.
+ *
+ * Note that the API for `$qRaf` is the exact same as for `$q`.
+ *
+ * @param {function(function, function)} resolver Function which is responsible for resolving or
+ *   rejecting the newly created promise. The first parameter is a function which resolves the
+ *   promise, the second parameter is a function which rejects the promise.
+ *
+ * @returns {Promise} The newly created promise.
+ */
+function $QRafProvider() {
+  this.$get = ['$$rAF', '$exceptionHandler', function($$rAF, $exceptionHandler) {
+    return qFactory(
+      function(data) {
+        $$rAF(function() {
+          data.$$rafCleared = true;
+        });
+      },
+      function(callback, data) {
+        data.$$rafCleared ? callback() : $$rAF(callback);
+      }, $exceptionHandler);
+  }];
+}
+
 /**
  * Constructs a promise manager.
  *
+ * @param {function(function)} initFn Function callback function which is called upon defer.
  * @param {function(function)} nextTick Function for executing functions in the next turn.
  * @param {function(...*)} exceptionHandler Function into which unexpected exceptions are passed for
  *     debugging purposes.
  * @returns {object} Promise manager.
  */
-function qFactory(nextTick, exceptionHandler) {
+function qFactory(initFn, nextTick, exceptionHandler) {
   var $qMinErr = minErr('$q', TypeError);
+  var promiseData = {};
+
   function callOnce(self, resolveFn, rejectFn) {
     var called = false;
     function wrap(fn) {
@@ -263,6 +303,7 @@ function qFactory(nextTick, exceptionHandler) {
    * @returns {Deferred} Returns a new instance of deferred.
    */
   var defer = function() {
+    initFn(promiseData);
     return new Deferred();
   };
 
@@ -328,7 +369,7 @@ function qFactory(nextTick, exceptionHandler) {
   function scheduleProcessQueue(state) {
     if (state.processScheduled || !state.pending) return;
     state.processScheduled = true;
-    nextTick(function() { processQueue(state); });
+    nextTick(function() { processQueue(state); }, promiseData);
   }
 
   function Deferred() {
@@ -399,7 +440,7 @@ function qFactory(nextTick, exceptionHandler) {
               exceptionHandler(e);
             }
           }
-        });
+        }, promiseData);
       }
     }
   };
@@ -491,6 +532,7 @@ function qFactory(nextTick, exceptionHandler) {
 
   var when = function(value, callback, errback, progressBack) {
     var result = new Deferred();
+    initFn(promiseData);
     result.resolve(value);
     return result.promise.then(callback, errback, progressBack);
   };

test/ng/qSpec.js

@@ -182,7 +182,7 @@ describe('q', function() {
 
 
   beforeEach(function() {
-    q = qFactory(mockNextTick.nextTick, noop),
+    q = qFactory(noop, mockNextTick.nextTick, noop),
     defer = q.defer;
     deferred =  defer();
     promise = deferred.promise;
@@ -195,7 +195,6 @@ describe('q', function() {
     expect(mockNextTick.queue.length).toBe(0);
   });
 
-
   describe('$Q', function() {
     var resolve, reject, resolve2, reject2;
     var createPromise = function() {
@@ -210,7 +209,7 @@ describe('q', function() {
       });
     };
 
-    afterEach(function() {
+    beforeEach(function() {
       resolve = reject = resolve2 = reject2 = null;
     });
 
@@ -1965,7 +1964,7 @@ describe('q', function() {
 
 
     beforeEach(function() {
-      q = qFactory(mockNextTick.nextTick, mockExceptionLogger.logger),
+      q = qFactory(noop, mockNextTick.nextTick, mockExceptionLogger.logger),
       defer = q.defer;
       deferred =  defer();
       promise = deferred.promise;
@@ -2079,7 +2078,7 @@ describe('q', function() {
       errorSpy = jasmine.createSpy('errorSpy');
 
 
-      q = qFactory(mockNextTick.nextTick, exceptionExceptionSpy);
+      q = qFactory(noop, mockNextTick.nextTick, exceptionExceptionSpy);
       deferred = q.defer();
     });
 
@@ -2107,4 +2106,126 @@ describe('q', function() {
       expect(errorSpy).toHaveBeenCalled();
     });
   });
+
+});
+
+describe('$qRaf', function() {
+
+  it('should only allow itself to resolve after one or more rAFs has occurred',
+    inject(function($qRaf, $$rAF) {
+
+    var signature = 'A';
+    var defer = $qRaf.defer();
+    defer.resolve();
+
+    defer.promise.then(function() {
+      signature += 'B';
+    });
+    signature += 'C';
+
+    expect(signature).toBe('AC');
+    $$rAF.flush();
+
+    expect(signature).toBe('ACB');
+  }));
+
+  it('should synchronously resolve itself if a rAF has already occurred',
+    inject(function($qRaf, $$rAF) {
+
+    var signature = 'A';
+    var defer = $qRaf.defer();
+    defer.promise.then(function() {
+      signature += 'B';
+    });
+    defer.resolve();
+
+    expect(signature).toBe('A');
+
+    $$rAF.flush();
+    signature += 'C';
+    expect(signature).toBe('ABC');
+  }));
+
+  it('should synchronously resolve itself and all subsequent promises if a rAF has already occurred',
+    inject(function($qRaf, $$rAF) {
+
+    var signature = '';
+    var defer = $qRaf.defer();
+    var chain = defer.promise.then(function() {
+      signature += 'A';
+    });
+    chain = chain.then(function() {
+      signature += 'B';
+    });
+    chain = chain.then(function() {
+      signature += 'C';
+    });
+    defer.resolve();
+
+    expect(signature).toBe('');
+
+    $$rAF.flush();
+    expect(signature).toBe('ABC');
+  }));
+
+  it('should resolve itself within the same rAF when multiple promises are used with all()',
+    inject(function($qRaf, $$rAF) {
+
+    var i;
+    var defers = [];
+    var promises = [];
+    for (i = 0; i < 5; i++) {
+      var defer = $qRaf.defer();
+      defers.push(defer);
+      promises.push(defer.promise);
+    }
+
+    var completed = false;
+    $qRaf.all(promises).then(function() {
+      completed = true;
+    });
+
+    $$rAF.flush();
+    for (i = 0; i < 5; i++) {
+      defers[i].resolve();
+    }
+
+    expect(completed).toBe(true);
+  }));
+
+  it('should resolve itself within the same rAF when multiple chained promises are used with all()',
+    inject(function($qRaf, $$rAF) {
+
+    var i = 0;
+    var defers = [];
+    var promises = [];
+    for (i = 0; i < 5; i++) {
+      var defer = $qRaf.defer();
+      defers.push(defer);
+      promises.push(defer.promise);
+    }
+
+    var lastDefer;
+    promises[0] = promises[0].then(function() {
+      lastDefer = $qRaf.defer();
+      return lastDefer.promise;
+    });
+
+    var completed = false;
+    $qRaf.all(promises).then(function() {
+      completed = true;
+    });
+
+    $$rAF.flush();
+    for (i = 0; i < 5; i++) {
+      defers[i].resolve();
+    }
+
+    expect(completed).toBe(false);
+
+    $$rAF.flush();
+    lastDefer.resolve();
+
+    expect(completed).toBe(true);
+  }));
 });