perf(*): more performant interpolation and lazy one-time binding

BEAKING CHANGE:
Lazy-binding now happens on the scope watcher level.

What this means is that given `parseFn = $parse('::foo')`,
bind-once will only kick in when `parseFn` is being watched by a scope
(i.e. `scope.$watch(parseFn)`)

Bind-once will have no effect when directily invoking `parseFn` (i.e. `parseFn()`)

Author: rodyhaddad

docs/content/guide/expression.ngdoc

@@ -200,3 +200,122 @@ expose a `$event` object within the scope of that expression.
 
 Note in the example above how we can pass in `$event` to `clickMe`, but how it does not show up
 in `{{$event}}`. This is because `$event` is outside the scope of that binding.
+
+
+## One-time binding
+
+An expression that starts with `::` is considered a one-time expression. One-time expressions
+will stop recalculating once they are stable, which happens after the first digest if the expression
+result is a non-undefined value (see value stabilization algorithm below).
+
+<example module="oneTimeBidingExampleApp">
+  <file name="index.html">
+    <div ng-controller="EventController">
+      <button ng-click="clickMe($event)">Click Me</button>
+      <p id="one-time-binding-example">One time binding: {{::name}}</p>
+      <p id="normal-binding-example">Normal binding: {{name}}</p>
+    </div>
+  </file>
+  <file name="script.js">
+    angular.module('oneTimeBidingExampleApp', []).
+      controller('EventController', ['$scope', function($scope) {
+        var counter = 0;
+        var names = ['Igor', 'Misko', 'Chirayu', 'Lucas'];
+        /*
+         * expose the event object to the scope
+         */
+        $scope.clickMe = function(clickEvent) {
+          $scope.name = names[counter % names.length];
+          counter++;
+        };
+      }]);
+  </file>
+  <file name="protractor.js" type="protractor">
+    it('should freeze binding after its value has stabilized', function() {
+      var oneTimeBiding = element(by.id('one-time-binding-example'));
+      var normalBinding = element(by.id('normal-binding-example'));
+
+      expect(oneTimeBiding.getText()).toEqual('One time binding:');
+      expect(normalBinding.getText()).toEqual('Normal binding:');
+      element(by.buttonText('Click Me')).click();
+
+      expect(oneTimeBiding.getText()).toEqual('One time binding: Igor');
+      expect(normalBinding.getText()).toEqual('Normal binding: Igor');
+      element(by.buttonText('Click Me')).click();
+
+      expect(oneTimeBiding.getText()).toEqual('One time binding: Igor');
+      expect(normalBinding.getText()).toEqual('Normal binding: Misko');
+
+      element(by.buttonText('Click Me')).click();
+      element(by.buttonText('Click Me')).click();
+
+      expect(oneTimeBiding.getText()).toEqual('One time binding: Igor');
+      expect(normalBinding.getText()).toEqual('Normal binding: Lucas');
+    });
+  </file>
+</example>
+
+
+### Why this feature
+
+The main purpose of one-time binding expression is to provide a way to create a binding
+that gets deregistered and frees up resources once the binding is stabilized.
+Reducing the number of expressions being watched makes the digest loop faster and allows more
+information to be displayed at the same time.
+
+
+### Value stabilization algorithm
+
+One-time binding expressions will retain the value of the expression at the end of the
+digest cycle as long as that value is not undefined. If the value of the expression is set
+within the digest loop and later, within the same digest loop, it is set to undefined,
+then the expression is not fulfilled and will remain watched.
+
+  1. Given an expression that starts with `::` when a digest loop is entered and expression
+     is dirty-checked store the value as V
+  2. If V is not undefined mark the result of the expression as stable and schedule a task
+     to deregister the watch for this expression when we exit the digest loop
+  3. Process the digest loop as normal
+  4. When digest loop is done and all the values have settled process the queue of watch
+     deregistration tasks. For each watch to be deregistered check if it still evaluates
+     to value that is not `undefined`. If that's the case, deregister the watch. Otherwise
+     keep dirty-checking the watch in the future digest loops by following the same
+     algorithm starting from step 1
+
+
+### How to benefit from one-time binding
+
+When interpolating text or attributes. If the expression, once set, will not change
+then it is a candidate for one-time expression.
+
+```html
+  <div name="attr: {{::color}}">text: {{::name}}</div>
+```
+
+When using a directive with bidirectional binding and the parameters will not change
+
+```js
+someModule.directive('someDirective', function() {
+  return {
+    scope: {
+      name: '=',
+      color: '@'
+    },
+    template: '{{name}}: {{color}}'
+  };
+});
+```
+
+```html
+  <div some-directive name=“::myName” color=“My color is {{::myColor}}”></div>
+```
+
+
+When using a directive that takes an expression
+
+```html
+<ul>
+  <li ng-repeat="item in ::items">{{item.name}};</li>
+</ul>
+```
+

src/ng/compile.js

@@ -1492,8 +1492,7 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
                       attrs[attrName], newIsolateScopeDirective.name);
                 };
                 lastValue = isolateScope[scopeName] = parentGet(scope);
-                isolateScope.$watch(function parentValueWatch() {
-                  var parentValue = parentGet(scope);
+                scope.$watch($parse(attrs[attrName], function parentValueWatch(parentValue) {
                   if (!compare(parentValue, isolateScope[scopeName])) {
                     // we are out of sync and need to copy
                     if (!compare(parentValue, lastValue)) {
@@ -1505,7 +1504,8 @@ function $CompileProvider($provide, $$sanitizeUriProvider) {
                     }
                   }
                   return lastValue = parentValue;
-                }, null, parentGet.literal);
+                }), null, parentGet.literal);
+
                 break;
 
               case '&':

src/ng/directive/ngBind.js

@@ -173,10 +173,14 @@ var ngBindHtmlDirective = ['$sce', '$parse', function($sce, $parse) {
   return function(scope, element, attr) {
     element.addClass('ng-binding').data('$binding', attr.ngBindHtml);
 
-    var parsed = $parse(attr.ngBindHtml);
-    function getStringValue() { return (parsed(scope) || '').toString(); }
+    var parsed = $parse(attr.ngBindHtml),
+        changeDetector = $parse(attr.ngBindHtml, function getStringValue(value) {
+          return (value || '').toString();
+        });
 
-    scope.$watch(getStringValue, function ngBindHtmlWatchAction(value) {
+    scope.$watch(changeDetector, function ngBindHtmlWatchAction() {
+      // we re-evaluate the expr because we want a TrustedValueHolderType
+      // for $sce, not a string
       element.html($sce.getTrustedHtml(parsed(scope)) || '');
     });
   };

src/ng/interpolate.js

@@ -195,8 +195,7 @@ function $InterpolateProvider() {
           hasInterpolation = false,
           hasText = false,
           exp,
-          concat = [],
-          lastValuesCache = { values: {}, results: {}};
+          concat = [];
 
       while(index < textLength) {
         if ( ((startIndex = text.indexOf(startSymbol, index)) != -1) &&
@@ -205,7 +204,7 @@ function $InterpolateProvider() {
           separators.push(text.substring(index, startIndex));
           exp = text.substring(startIndex + startSymbolLength, endIndex);
           expressions.push(exp);
-          parseFns.push($parse(exp));
+          parseFns.push($parse(exp, parseStringifyInterceptor));
           index = endIndex + endSymbolLength;
           hasInterpolation = true;
         } else {
@@ -246,6 +245,7 @@ function $InterpolateProvider() {
 
         var compute = function(values) {
           for(var i = 0, ii = expressions.length; i < ii; i++) {
+            if (allOrNothing && isUndefined(values[i])) return;
             concat[2*i] = separators[i];
             concat[(2*i)+1] = values[i];
           }
@@ -255,12 +255,10 @@ function $InterpolateProvider() {
 
         var getValue = function (value) {
           if (trustedContext) {
-            value = $sce.getTrusted(trustedContext, value);
+            return $sce.getTrusted(trustedContext, value);
           } else {
-            value = $sce.valueOf(value);
+            return $sce.valueOf(value);
           }
-
-          return value;
         };
 
         var stringify = function (value) {
@@ -284,61 +282,47 @@ function $InterpolateProvider() {
         };
 
         return extend(function interpolationFn(context) {
-            var scopeId = (context && context.$id) || 'notAScope';
-            var lastValues = lastValuesCache.values[scopeId];
-            var lastResult = lastValuesCache.results[scopeId];
             var i = 0;
             var ii = expressions.length;
             var values = new Array(ii);
-            var val;
-            var inputsChanged = lastResult === undefined ? true: false;
-
-
-            // if we haven't seen this context before, initialize the cache and try to setup
-            // a cleanup routine that purges the cache when the scope goes away.
-            if (!lastValues) {
-              lastValues = [];
-              inputsChanged = true;
-              if (context && context.$on) {
-                context.$on('$destroy', function() {
-                  lastValuesCache.values[scopeId] = null;
-                  lastValuesCache.results[scopeId] = null;
-                });
-              }
-            }
-
 
             try {
               for (; i < ii; i++) {
-                val = getValue(parseFns[i](context));
-                if (allOrNothing && isUndefined(val)) {
-                  return;
-                }
-                val = stringify(val);
-                if (val !== lastValues[i]) {
-                  inputsChanged = true;
-                }
-                values[i] = val;
+                values[i] = parseFns[i](context);
               }
 
-              if (inputsChanged) {
-                lastValuesCache.values[scopeId] = values;
-                lastValuesCache.results[scopeId] = lastResult = compute(values);
-              }
+              return compute(values);
             } catch(err) {
               var newErr = $interpolateMinErr('interr', "Can't interpolate: {0}\n{1}", text,
                   err.toString());
               $exceptionHandler(newErr);
             }
 
-            return lastResult;
           }, {
           // all of these properties are undocumented for now
           exp: text, //just for compatibility with regular watchers created via $watch
           separators: separators,
-          expressions: expressions
+          expressions: expressions,
+          $$beWatched: function (scope, listener, objectEquality, deregisterNotifier) {
+            var lastValue;
+            return scope.$watchGroup(parseFns, function interpolateFnWatcher(values, oldValues) {
+              var currValue = compute(values);
+              listener.call(this, currValue, values !== oldValues ? lastValue : currValue, scope);
+              lastValue = currValue;
+            }, objectEquality, deregisterNotifier);
+          }
         });
       }
+
+      function parseStringifyInterceptor(value) {
+        try {
+          return stringify(getValue(value));
+        } catch(err) {
+          var newErr = $interpolateMinErr('interr', "Can't interpolate: {0}\n{1}", text,
+            err.toString());
+          $exceptionHandler(newErr);
+        }
+      }
     }
 
 

src/ng/parse.js

@@ -999,34 +999,87 @@ function $ParseProvider() {
   this.$get = ['$filter', '$sniffer', function($filter, $sniffer) {
     $parseOptions.csp = $sniffer.csp;
 
-    return function(exp) {
-      var parsedExpression;
+    return function(exp, interceptorFn) {
+      var parsedExpression, oneTime,
+          cacheKey = exp;
 
       switch (typeof exp) {
         case 'string':
+          if (cache.hasOwnProperty(cacheKey)) {
+            parsedExpression = cache[cacheKey];
+          } else {
+            if (exp.charAt(0) === ':' && exp.charAt(1) === ':') {
+              oneTime = true;
+              exp = exp.substring(2);
+            }
 
-          if (cache.hasOwnProperty(exp)) {
-            return cache[exp];
-          }
+            var lexer = new Lexer($parseOptions);
+            var parser = new Parser(lexer, $filter, $parseOptions);
+            parsedExpression = parser.parse(exp);
 
-          var lexer = new Lexer($parseOptions);
-          var parser = new Parser(lexer, $filter, $parseOptions);
-          parsedExpression = parser.parse(exp);
+            if (oneTime) parsedExpression.$$beWatched = oneTimeWatch;
+            if (parsedExpression.constant) parsedExpression.$$beWatched = constantWatch;
 
-          if (exp !== 'hasOwnProperty') {
+            if (cacheKey !== 'hasOwnProperty') {
             // Only cache the value if it's not going to mess up the cache object
             // This is more performant that using Object.prototype.hasOwnProperty.call
-            cache[exp] = parsedExpression;
+              cache[cacheKey] = parsedExpression;
+            }
           }
-
-          return parsedExpression;
+          return addInterceptor(parsedExpression, interceptorFn);
 
         case 'function':
-          return exp;
+          return addInterceptor(exp, interceptorFn);
 
         default:
-          return noop;
+          return addInterceptor(noop, interceptorFn);
       }
     };
+
+    function oneTimeWatch(scope, listener, objectEquality, deregisterNotifier, parsedExpression) {
+      var unwatch;
+      return unwatch = scope.$watch(function oneTimeWatch(scope) {
+        return parsedExpression(scope);
+      }, function oneTimeListener(value, old, scope) {
+        if (isFunction(listener)) {
+          listener.call(this, value, old, scope);
+        }
+        if (isDefined(value)) {
+          scope.$$postDigest(function () {
+            if (isDefined(parsedExpression(scope))) {
+              unwatch();
+            }
+          });
+        }
+      }, objectEquality, deregisterNotifier);
+    }
+
+    function constantWatch(scope, listener, objectEquality, deregisterNotifier, parsedExpression) {
+      var unwatch;
+      return unwatch = scope.$watch(function constantWatch(scope) {
+        return parsedExpression(scope);
+      }, function constantListener(value, old, scope) {
+        if (isFunction(listener)) {
+          listener.call(this, value, old, scope);
+        }
+        unwatch();
+      }, objectEquality, deregisterNotifier);
+    }
+
+    function addInterceptor(parsedExpression, interceptorFn) {
+      if (isFunction(interceptorFn)) {
+        var fn = function interceptedExpression(scope, locals) {
+          var value = parsedExpression(scope, locals);
+          var result = interceptorFn(value, scope, locals);
+          // we only return the interceptor's result if the
+          // initial value is defined (for bind-once)
+          return isDefined(value) ? result : value;
+        };
+        fn.$$beWatched = parsedExpression.$$beWatched;
+        return fn;
+      } else {
+        return parsedExpression;
+      }
+    }
   }];
 }