Merge pull request #6 from nateabele/resolvable-rebase

feat($resolve): Super-duper-lazy Resolvable system

merge PR from resolvable-rebase

Author: christopherthielen

Gruntfile.js

@@ -97,6 +97,12 @@ module.exports = function (grunt) {
       background: {
           background: true,
           browsers: [ grunt.option('browser') || 'PhantomJS' ]
+      },
+      watch: {
+        configFile: 'config/karma.js',
+        singleRun: false,
+        autoWatch: true,
+        autoWatchInterval: 1
       }
     },
     changelog: {

src/common.js

@@ -146,6 +146,70 @@ function filterByKeys(keys, values) {
   });
   return filtered;
 }
+
+// like _.indexBy
+// when you know that your index values will be unique, or you want last-one-in to win
+function indexBy(array, propName) {
+  var result = {};
+  forEach(array, function(item) {
+    result[item[propName]] = item;
+  });
+  return result;
+}
+
+// extracted from underscore.js
+// Return a copy of the object only containing the whitelisted properties.
+function pick(obj) {
+  var copy = {};
+  var keys = Array.prototype.concat.apply(Array.prototype, Array.prototype.slice.call(arguments, 1));
+  forEach(keys, function(key) {
+    if (key in obj) copy[key] = obj[key];
+  });
+  return copy;
+}
+
+// extracted from underscore.js
+// Return a copy of the object omitting the blacklisted properties.
+function omit(obj) {
+  var copy = {};
+  var keys = Array.prototype.concat.apply(Array.prototype, Array.prototype.slice.call(arguments, 1));
+  for (var key in obj) {
+    if (keys.indexOf(key) == -1) copy[key] = obj[key];
+  }
+  return copy;
+}
+
+function pluck(collection, key) {
+  var result = isArray(collection) ? [] : {};
+
+  forEach(collection, function(val, i) {
+    result[i] = isFunction(key) ? key(val) : val[key];
+  });
+  return result;
+}
+
+function map(collection, callback) {
+  var result = isArray(collection) ? [] : {};
+
+  forEach(collection, function(val, i) {
+    result[i] = callback(val, i);
+  });
+  return result;
+}
+
+function flattenPrototypeChain(obj) {
+  var objs = [];
+  do {
+    objs.push(obj);
+  } while (obj = Object.getPrototypeOf(obj));
+  objs.reverse();
+
+  var result = {};
+  forEach(objs, function(obj) {
+    extend(result, obj);
+  });
+  return result;
+}
 /**
  * @ngdoc overview
  * @name ui.router.util

src/resolve.js

@@ -1,3 +1,5 @@
+var Resolvable, Path, PathElement, ResolveContext;
+
 /**
  * @ngdoc object
  * @name ui.router.util.$resolve
@@ -10,7 +12,289 @@
  */
 $Resolve.$inject = ['$q', '$injector'];
 function $Resolve(  $q,    $injector) {
-  
+
+  /*
+   ------- Resolvable, PathElement, Path, ResolveContext ------------------
+   I think these should be private API for now because we may need to iterate it for a while.
+   /*
+
+   /*  Resolvable
+
+   The basic building block for the new resolve system.
+   Resolvables encapsulate a state's resolve's resolveFn, the resolveFn's declared dependencies, and the wrapped (.promise)
+   and unwrapped-when-complete (.data) result of the resolveFn.
+
+   Resolvable.get() either retrieves the Resolvable's existing promise, or else invokes resolve() (which invokes the
+   resolveFn) and returns the resulting promise.
+
+   Resolvable.get() and Resolvable.resolve() both execute within a ResolveContext, which is passed as the first
+   parameter to those fns.
+   */
+
+
+  Resolvable = function Resolvable(name, resolveFn, state) {
+    var self = this;
+
+    // Resolvable: resolveResolvable() This function is aliased to Resolvable.resolve()
+
+    // synchronous part:
+    // - sets up the Resolvable's promise
+    // - retrieves dependencies' promises
+    // - returns promise for async part
+
+    // asynchronous part:
+    // - wait for dependencies promises to resolve
+    // - invoke the resolveFn
+    // - wait for resolveFn promise to resolve
+    // - store unwrapped data
+    // - resolve the Resolvable's promise
+    function resolveResolvable(resolveContext) {
+      // First, set up an overall deferred/promise for this Resolvable
+      var deferred = $q.defer();
+      self.promise = deferred.promise;
+
+      // Load an assoc-array of all resolvables for this state from the resolveContext
+      // omit the current Resolvable from the PathElement in the ResolveContext so we don't try to inject self into self
+      var options = {  omitPropsFromPrototype: [ self.name ], flatten: true };
+      var ancestorsByName = resolveContext.getResolvableLocals(self.state.name, options);
+
+      // Limit the ancestors Resolvables map to only those that the current Resolvable fn's annotations depends on
+      var depResolvables = pick(ancestorsByName, self.deps);
+
+      // Get promises (or synchronously invoke resolveFn) for deps
+      var depPromises = map(depResolvables, function(resolvable) {
+        return resolvable.get(resolveContext);
+      });
+
+      // Return a promise chain that waits for all the deps to resolve, then invokes the resolveFn passing in the
+      // dependencies as locals, then unwraps the resulting promise's data.
+      return $q.all(depPromises).then(function invokeResolve(locals) {
+        try {
+          var result = $injector.invoke(self.resolveFn, state, locals);
+          deferred.resolve(result);
+        } catch (error) {
+          deferred.reject(error);
+        }
+        return self.promise;
+      }).then(function(data) {
+        self.data = data;
+        return self.promise;
+      })
+    }
+
+    // Public API
+    extend(this, {
+      name: name,
+      resolveFn: resolveFn,
+      state: state,
+      deps: $injector.annotate(resolveFn),
+      resolve: resolveResolvable, // aliased function name for stacktraces
+      promise: undefined,
+      data: undefined,
+      get: function(resolveContext) {
+        return self.promise || resolveResolvable(resolveContext);
+      }
+    });
+  };
+
+  // An element in the path which represents a state and that state's Resolvables and their resolve statuses.
+  // When the resolved data is ready, it is stored in each Resolvable object within the PathElement
+
+  // Should be passed a state object.  I think maybe state could even be the public state, so users can add resolves
+  // on the fly.
+  PathElement = function PathElement(state) {
+    var self = this;
+    // Convert state's resolvable assoc-array into an assoc-array of empty Resolvable(s)
+    var resolvables = map(state.resolve || {}, function(resolveFn, resolveName) {
+      return new Resolvable(resolveName, resolveFn, state);
+    });
+
+    // private function
+    // returns a promise for all resolvables on this PathElement
+    function resolvePathElement(resolveContext) {
+      return $q.all(map(resolvables, function(resolvable) { return resolvable.get(resolveContext); }));
+    }
+
+    // Injects a function at this PathElement level with available Resolvables
+    // First it resolves all resolvables.  When they are done resolving, invokes the function.
+    // Returns a promise for the return value of the function.
+    // public function
+    // fn is the function to inject (onEnter, onExit, controller)
+    // locals are the regular-style locals to inject
+    // resolveContext is a ResolveContext which is for injecting state Resolvable(s)
+    function invokeLater(fn, locals, resolveContext) {
+      var deps = $injector.annotate(fn);
+      var resolvables = pick(resolveContext.getResolvableLocals(self.$$state.name), deps);
+      var promises = map(resolvables, function(resolvable) { return resolvable.get(resolveContext); });
+      return $q.all(promises).then(function() {
+        try {
+          return self.invokeNow(fn, locals, resolveContext);
+        } catch (error) {
+          return $q.reject(error);
+        }
+      });
+    }
+
+    // private function? Maybe needs to be public-to-$transition to allow onEnter/onExit to be invoked synchronously
+    // and in the correct order, but only after we've manually ensured all the deps are resolved.
+
+    // Injects a function at this PathElement level with available Resolvables
+    // Does not wait until all Resolvables have been resolved; you must call PathElement.resolve() (or manually resolve each dep) first
+    function invokeNow(fn, locals, resolveContext) {
+      var resolvables = resolveContext.getResolvableLocals(self.$$state.name);
+      var moreLocals = map(resolvables, function(resolvable) { return resolvable.data; });
+      var combinedLocals = extend({}, locals, moreLocals);
+      return $injector.invoke(fn, self.$$state, combinedLocals);
+    }
+
+    // public API so far
+    extend(this, {
+      state: function() { return state; },
+      $$state: state,
+      resolvables: function() { return resolvables; },
+      $$resolvables: resolvables,
+      resolve: resolvePathElement, // aliased function for stacktraces
+      invokeNow: invokeNow, // this might be private later
+      invokeLater: invokeLater
+    });
+  };
+
+  // A Path Object holds an ordered list of PathElements.
+  // This object is used by ResolveContext to store resolve status for an entire path of states.
+  // It has concat and slice helper methods to return new Paths, based on the current Path.
+
+  // statesOrPathElements must be an array of either state(s) or PathElement(s)
+  // states could be "public" state objects for this?
+  Path = function Path(statesOrPathElements) {
+    var self = this;
+    if (!isArray(statesOrPathElements)) throw new Error("states must be an array of state(s) or PathElement(s)", statesOrPathElements);
+    var isPathElementArray = (statesOrPathElements.length && (statesOrPathElements[0] instanceof PathElement));
+
+    var elements = statesOrPathElements;
+    if (!isPathElementArray) { // they passed in states; convert them to PathElements
+      elements = map(elements, function (state) { return new PathElement(state); });
+    }
+
+    // resolveContext holds stateful Resolvables (containing possibly resolved data), mapped per state-name.
+    function resolvePath(resolveContext) {
+      return $q.all(map(elements, function(element) { return element.resolve(resolveContext); }));
+    }
+
+    // Not used
+    function invoke(hook, self, locals) {
+      if (!hook) return;
+      return $injector.invoke(hook, self, locals);
+    }
+
+    // Public API
+    extend(this, {
+      resolve: resolvePath,
+      $$elements: elements, // for development at least
+      concat: function(path) {
+        return new Path(elements.concat(path.elements()));
+      },
+      slice: function(start, end) {
+        return new Path(elements.slice(start, end));
+      },
+      elements: function() {
+        return elements;
+      },
+      // I haven't looked at how $$enter and $$exit are going be used.
+      $$enter: function(/* locals */) {
+        // TODO: Replace with PathElement.invoke(Now|Later)
+        // TODO: If invokeNow (synchronous) then we have to .get() all Resolvables for all functions first.
+        for (var i = 0; i < states.length; i++) {
+          // entering.locals = toLocals[i];
+          if (invoke(states[i].self.onEnter, states[i].self, locals(states[i])) === false) return false;
+        }
+        return true;
+      },
+      $$exit: function(/* locals */) {
+        // TODO: Replace with PathElement.invoke(Now|Later)
+        for (var i = states.length - 1; i >= 0; i--) {
+          if (invoke(states[i].self.onExit, states[i].self, locals(states[i])) === false) return false;
+          // states[i].locals = null;
+        }
+        return true;
+      }
+    });
+  };
+
+  // ResolveContext is passed into each resolve() function, and is used to statefully manage Resolve status.
+  // ResolveContext is essentially the replacement data structure for $state.$current.locals and we'll have to
+  // figure out where to store/manage this data structure.
+  // It manages a set of Resolvables that are available at each level of the Path.
+  // It follows the list of PathElements and inherit()s the PathElement's Resolvables on top of the
+  // previous PathElement's Resolvables.  i.e., it builds a prototypal chain for the PathElements' Resolvables.
+  // Before moving on to the next PathElement, it makes a note of what Resolvables are available for the current
+  // PathElement, and maps it by state name.
+
+  // ResolveContext constructor takes a path which is assumed to be partially resolved, or
+  // not resolved at all, which we're in process of resolving
+  ResolveContext = function ResolveContext(path) {
+    if (path === undefined) path = new Path([]);
+    var resolvablesByState = {}, previousIteration = {};
+
+    forEach(path.elements(), function (pathElem) {
+      var resolvablesForPE = pathElem.resolvables();
+      var resolvesbyName = indexBy(resolvablesForPE, 'name');
+      var resolvables = inherit(previousIteration, resolvesbyName); // note prototypal inheritance
+      previousIteration = resolvablesByState[pathElem.state().name] = resolvables;
+    });
+
+    // Gets resolvables available for a particular state.
+    // TODO: This should probably be "for a particular PathElement" instead of state, but PathElements encapsulate a state.
+    // This returns the Resolvable map by state name.
+
+    // options.omitPropsFromPrototype
+    // Remove the props specified in options.omitPropsFromPrototype from the prototype of the object.
+
+    // This hides a top-level resolvable by name, potentially exposing a parent resolvable of the same name
+    // further down the prototype chain.
+
+    // This is used to provide a Resolvable access to all other Resolvables in its same PathElement, yet disallow
+    // that Resolvable access to its own injectable Resolvable reference.
+
+    // This is also used to allow a state to override a parent state's resolve while also injecting
+    // that parent state's resolve:
+
+    // state({ name: 'G', resolve: { _G: function() { return "G"; } } });
+    // state({ name: 'G.G2', resolve: { _G: function(_G) { return _G + "G2"; } } });
+    // where injecting _G into a controller will yield "GG2"
+
+    // options.flatten
+    // $$resolvablesByState has resolvables organized in a prototypal inheritance chain.  options.flatten will
+    // flatten the object from prototypal inheritance to a simple object with all its prototype chain properties
+    // exposed with child properties taking precedence over parent properties.
+    function getResolvableLocals(stateName, options) {
+      var resolvables = (resolvablesByState[stateName] || {});
+      options = extend({ flatten: true, omitPropsFromPrototype: [] }, options);
+
+      // Create a shallow clone referencing the original prototype chain.  This is so we can alter the clone's
+      // prototype without affecting the actual object (for options.omitPropsFromPrototype)
+      var shallowClone = Object.create(Object.getPrototypeOf(resolvables));
+      for (property in resolvables) {
+        if (resolvables.hasOwnProperty(property)) { shallowClone[property] = resolvables[property]; }
+      }
+
+      // Omit any specified top-level prototype properties
+      forEach(options.omitPropsFromPrototype, function(prop) {
+        delete(shallowClone[prop]); // possibly exposes the same prop from prototype chain
+      });
+
+      if (options.flatten) // Flatten from prototypal chain to simple object
+        shallowClone = flattenPrototypeChain(shallowClone);
+
+      return shallowClone;
+    }
+
+    extend(this, {
+      getResolvableLocals: getResolvableLocals,
+      $$resolvablesByState: resolvablesByState
+    });
+  };
+
+  // ----------------- 0.2.xx Legacy API here ------------------------
   var VISIT_IN_PROGRESS = 1,
       VISIT_DONE = 2,
       NOTHING = {},