feat($rootScope): implement $applyAsync to support combining calls to $apply into a single digest.

It is now possible to queue up multiple expressions to be evaluated in a single digest using
$applyAsync. The asynchronous expressions will be evaluated either 1) the next time $apply or
$rootScope.$digest is called, or 2) after after the queue flushing scheduled for the next turn
occurs (roughly ~10ms depending on browser and application).

Author: caitp

src/ng/rootScope.js

@@ -71,6 +71,7 @@ function $RootScopeProvider(){
   var TTL = 10;
   var $rootScopeMinErr = minErr('$rootScope');
   var lastDirtyWatch = null;
+  var applyAsyncId = null;
 
   this.digestTtl = function(value) {
     if (arguments.length) {
@@ -134,6 +135,7 @@ function $RootScopeProvider(){
       this.$$listeners = {};
       this.$$listenerCount = {};
       this.$$isolateBindings = {};
+      this.$$applyAsyncQueue = [];
     }
 
     /**
@@ -688,6 +690,13 @@ function $RootScopeProvider(){
 
         beginPhase('$digest');
 
+        if (this === $rootScope && applyAsyncId !== null) {
+          // If this is the root scope, and $applyAsync has scheduled a deferred $apply(), then
+          // cancel the scheduled $apply and flush the queue of expressions to be evaluated.
+          $browser.defer.cancel(applyAsyncId);
+          flushApplyAsync();
+        }
+
         lastDirtyWatch = null;
 
         do { // "while dirty" loop
@@ -997,6 +1006,33 @@ function $RootScopeProvider(){
         }
       },
 
+      /**
+       * @ngdoc method
+       * @name $rootScope.Scope#$applyAsync
+       * @kind function
+       *
+       * @description
+       * Schedule the invokation of $apply to occur at a later time. The actual time difference
+       * varies across browsers, but is typically around ~10 milliseconds.
+       *
+       * This can be used to queue up multiple expressions which need to be evaluated in the same
+       * digest.
+       *
+       * @param {(string|function())=} exp An angular expression to be executed.
+       *
+       *    - `string`: execute using the rules as defined in {@link guide/expression expression}.
+       *    - `function(scope)`: execute the function with current `scope` parameter.
+       */
+      $applyAsync: function(expr) {
+        var scope = this;
+        expr && $rootScope.$$applyAsyncQueue.push($applyAsyncExpression);
+        scheduleApplyAsync();
+
+        function $applyAsyncExpression() {
+          scope.$eval(expr);
+        }
+      },
+
       /**
        * @ngdoc method
        * @name $rootScope.Scope#$on
@@ -1229,5 +1265,25 @@ function $RootScopeProvider(){
      * because it's unique we can easily tell it apart from other values
      */
     function initWatchVal() {}
+
+    function flushApplyAsync() {
+      var queue = $rootScope.$$applyAsyncQueue;
+      while (queue.length) {
+        try {
+          queue.shift()();
+        } catch(e) {
+          $exceptionHandler(e);
+        }
+      }
+      applyAsyncId = null;
+    }
+
+    function scheduleApplyAsync() {
+      if (applyAsyncId === null) {
+        applyAsyncId = $browser.defer(function() {
+          $rootScope.$apply(flushApplyAsync);
+        });
+      }
+    }
   }];
 }

test/ng/rootScopeSpec.js

@@ -1399,6 +1399,91 @@ describe('Scope', function() {
   });
 
 
+  describe('$applyAsync', function() {
+    beforeEach(module(function($exceptionHandlerProvider) {
+      $exceptionHandlerProvider.mode('log');
+    }));
+
+
+    it('should evaluate in the context of specific $scope', inject(function($rootScope, $browser) {
+      var scope = $rootScope.$new();
+      scope.$applyAsync('x = "CODE ORANGE"');
+
+      $browser.defer.flush();
+      expect(scope.x).toBe('CODE ORANGE');
+      expect($rootScope.x).toBeUndefined();
+    }));
+
+
+    it('should evaluate queued expressions in order', inject(function($rootScope, $browser) {
+      $rootScope.x = [];
+      $rootScope.$applyAsync('x.push("expr1")');
+      $rootScope.$applyAsync('x.push("expr2")');
+
+      $browser.defer.flush();
+      expect($rootScope.x).toEqual(['expr1', 'expr2']);
+    }));
+
+
+    it('should evaluate subsequently queued items in same turn', inject(function($rootScope, $browser) {
+      $rootScope.x = [];
+      $rootScope.$applyAsync(function() {
+        $rootScope.x.push('expr1');
+        $rootScope.$applyAsync('x.push("expr2")');
+        expect($browser.deferredFns.length).toBe(0);
+      });
+
+      $browser.defer.flush();
+      expect($rootScope.x).toEqual(['expr1', 'expr2']);
+    }));
+
+
+    it('should pass thrown exceptions to $exceptionHandler', inject(function($rootScope, $browser, $exceptionHandler) {
+      $rootScope.$applyAsync(function() {
+        throw 'OOPS';
+      });
+
+      $browser.defer.flush();
+      expect($exceptionHandler.errors).toEqual([
+        'OOPS'
+      ]);
+    }));
+
+
+    it('should evaluate subsequent expressions after an exception is thrown', inject(function($rootScope, $browser) {
+      $rootScope.$applyAsync(function() {
+        throw 'OOPS';
+      });
+      $rootScope.$applyAsync('x = "All good!"');
+
+      $browser.defer.flush();
+      expect($rootScope.x).toBe('All good!');
+    }));
+
+
+    it('should be cancelled if a $rootScope digest occurs before the next tick', inject(function($rootScope, $browser) {
+      var apply = spyOn($rootScope, '$apply').andCallThrough();
+      var cancel = spyOn($browser.defer, 'cancel').andCallThrough();
+      var expression = jasmine.createSpy('expr');
+
+      $rootScope.$applyAsync(expression);
+      $rootScope.$digest();
+      expect(expression).toHaveBeenCalledOnce();
+      expect(cancel).toHaveBeenCalledOnce();
+      expression.reset();
+      cancel.reset();
+
+      // assert that we no longer are waiting to execute
+      expect($browser.deferredFns.length).toBe(0);
+
+      // assert that another digest won't call the function again
+      $rootScope.$digest();
+      expect(expression).not.toHaveBeenCalled();
+      expect(cancel).not.toHaveBeenCalled();
+    }));
+  });
+
+
   describe('events', function() {
 
     describe('$on', function() {