$resolve service (tested) and integration into $state (only partially tested)

Author: ksperling

src/common.js

@@ -15,15 +15,6 @@ function inherit(parent, extra) {
   return extend(new (extend(function() {}, { prototype: parent }))(), extra);
 }
 
-/**
- * Extends the destination object `dst` by copying all of the properties from the `src` object(s)
- * to `dst` if the `dst` object has no own property of the same name. You can specify multiple
- * `src` objects.
- *
- * @param {Object} dst Destination object.
- * @param {...Object} src Source object(s).
- * @see angular.extend
- */
 function merge(dst) {
   forEach(arguments, function(obj) {
     if (obj !== dst) {

src/resolve.js

@@ -0,0 +1,215 @@
+/**
+ * Service (`ui-util`). Manages resolution of (acyclic) graphs of promises.
+ * @module $resolve
+ * @requires $q
+ * @requires $injector
+ */
+$Resolve.$inject = ['$q', '$injector'];
+function $Resolve(  $q,    $injector) {
+  
+  var VISIT_IN_PROGRESS = 1,
+      VISIT_DONE = 2,
+      NOTHING = {},
+      NO_DEPENDENCIES = [],
+      NO_LOCALS = NOTHING,
+      NO_PARENT = extend($q.when(NOTHING), { $$promises: NOTHING, $$values: NOTHING });
+  
+
+  /**
+   * Studies a set of invocables that are likely to be used multiple times.
+   *      $resolve.study(invocables)(locals, parent, self)
+   * is equivalent to
+   *      $resolve.resolve(invocables, locals, parent, self)
+   * but the former is more efficient (in fact `resolve` just calls `study` internally).
+   * See {@link module:$resolve/resolve} for details.
+   * @function
+   * @param {Object} invocables
+   * @return {Function}
+   */
+  this.study = function (invocables) {
+    if (!isObject(invocables)) throw new Error("'invocables' must be an object");
+    
+    // Perform a topological sort of invocables to build an ordered plan
+    var plan = [], cycle = [], visited = {};
+    function visit(value, key) {
+      if (visited[key] === VISIT_DONE) return;
+      
+      cycle.push(key);
+      if (visited[key] === VISIT_IN_PROGRESS) {
+        cycle.splice(0, cycle.indexOf(key));
+        throw new Error("Cyclic dependency: " + cycle.join(" -> "));
+      }
+      visited[key] = VISIT_IN_PROGRESS;
+      
+      if (isString(value)) {
+        plan.push(key, [ function() { return $injector.get(key); }], NO_DEPENDENCIES);
+      } else {
+        var params = $injector.annotate(value);
+        forEach(params, function (param) {
+          if (param !== key && invocables.hasOwnProperty(param)) visit(invocables[param], param);
+        });
+        plan.push(key, value, params);
+      }
+      
+      cycle.pop();
+      visited[key] = VISIT_DONE;
+    }
+    forEach(invocables, visit);
+    invocables = cycle = visited = null; // plan is all that's required
+    
+    function isResolve(value) {
+      return isObject(value) && value.then && value.$$promises;
+    }
+    
+    return function (locals, parent, self) {
+      if (isResolve(locals) && self === undefined) {
+        self = parent; parent = locals; locals = null;
+      }
+      if (!locals) locals = NO_LOCALS;
+      else if (!isObject(locals)) {
+        throw new Error("'locals' must be an object");
+      }       
+      if (!parent) parent = NO_PARENT;
+      else if (!isResolve(parent)) {
+        throw new Error("'parent' must be a promise returned by $resolve.resolve()");
+      }
+      
+      // To complete the overall resolution, we have to wait for the parent
+      // promise and for the promise for each invokable in our plan.
+      var resolution = $q.defer(),
+          result = resolution.promise,
+          promises = result.$$promises = {},
+          values = extend({}, locals),
+          wait = 1 + plan.length/3,
+          merged = false;
+          
+      function done() {
+        // Merge parent values we haven't got yet and publish our own $$values
+        if (!--wait) {
+          if (!merged) merge(values, parent.$$values); 
+          result.$$values = values;
+          result.$$promises = true; // keep for isResolve()
+          resolution.resolve(values);
+        }
+      }
+      
+      function fail(reason) {
+        result.$$failure = reason;
+        resolution.reject(reason);
+      }
+      
+      // Short-circuit if parent has already failed
+      if (isDefined(parent.$$failure)) {
+        fail(parent.$$failure);
+        return result;
+      }
+      
+      // Merge parent values if the parent has already resolved, or merge
+      // parent promises and wait if the parent resolve is still in progress.
+      if (parent.$$values) {
+        merged = merge(values, parent.$$values);
+        done();
+      } else {
+        extend(promises, parent.$$promises);
+        parent.then(done, fail);
+      }
+      
+      // Process each invocable in the plan, but ignore any where a local of the same name exists.
+      for (var i=0, ii=plan.length; i<ii; i+=3) {
+        if (locals.hasOwnProperty(plan[i])) done();
+        else invoke(plan[i], plan[i+1], plan[i+2]);
+      }
+      
+      function invoke(key, invocable, params) {
+        // Create a deferred for this invocation. Failures will propagate to the resolution as well.
+        var invocation = $q.defer(), waitParams = 0;
+        function onfailure(reason) {
+          invocation.reject(reason);
+          fail(reason);
+        }
+        // Wait for any parameter that we have a promise for (either from parent or from this
+        // resolve; in that case study() will have made sure it's ordered before us in the plan).
+        params.forEach(function (dep) {
+          if (promises.hasOwnProperty(dep) && !locals.hasOwnProperty(dep)) {
+            waitParams++;
+            promises[dep].then(function (result) {
+              values[dep] = result;
+              if (!(--waitParams)) proceed();
+            }, onfailure);
+          }
+        });
+        if (!waitParams) proceed();
+        function proceed() {
+          if (isDefined(result.$$failure)) return;
+          try {
+            invocation.resolve($injector.invoke(invocable, self, values));
+            invocation.promise.then(function (result) {
+              values[key] = result;
+              done();
+            }, onfailure);
+          } catch (e) {
+            onfailure(e);
+          }
+        }
+        // Publish promise synchronously; invocations further down in the plan may depend on it.
+        promises[key] = invocation.promise;
+      }
+      
+      return result;
+    };
+  };
+  
+  /**
+   * Resolves a set of invocables. An invocable is a function to be invoked via `$injector.invoke()`,
+   * and can have an arbitrary number of dependencies. An invocable can either return a value directly,
+   * or a `$q` promise. If a promise is returned it will be resolved and the resulting value will be
+   * used instead. Dependencies of invocables are resolved (in this order of precedence)
+   *
+   * - from the specified `locals`
+   * - from another invocable that is part of this `$resolve` call
+   * - from an invocable that is inherited from a `parent` call to `$resolve` (or recursively
+   *   from any ancestor `$resolve` of that parent).
+   *
+   * The return value of `$resolve` is a promise for an object that contains (in this order of precedence)
+   *
+   * - any `locals` (if specified)
+   * - the resolved return values of all injectables
+   * - any values inherited from a `parent` call to `$resolve` (if specified)
+   *
+   * The promise will resolve after the `parent` promise (if any) and all promises returned by injectables
+   * have been resolved. If any invocable (or `$injector.invoke`) throws an exception, or if a promise
+   * returned by an invocable is rejected, the `$resolve` promise is immediately rejected with the same error.
+   * A rejection of a `parent` promise (if specified) will likewise be propagated immediately. Once the
+   * `$resolve` promise has been rejected, no further invocables will be called.
+   * 
+   * Cyclic dependencies between invocables are not permitted and will caues `$resolve` to throw an
+   * error. As a special case, an injectable can depend on a parameter with the same name as the injectable,
+   * which will be fulfilled from the `parent` injectable of the same name. This allows inherited values
+   * to be decorated. Note that in this case any other injectable in the same `$resolve` with the same
+   * dependency would see the decorated value, not the inherited value.
+   *
+   * Note that missing dependencies -- unlike cyclic dependencies -- will cause an (asynchronous) rejection
+   * of the `$resolve` promise rather than a (synchronous) exception.
+   *
+   * Invocables are invoked eagerly as soon as all dependencies are available. This is true even for
+   * dependencies inherited from a `parent` call to `$resolve`.
+   *
+   * As a special case, an invocable can be a string, in which case it is taken to be a service name
+   * to be passed to `$injector.get()`. This is supported primarily for backwards-compatibility with the
+   * `resolve` property of `$routeProvider` routes.
+   *
+   * @function
+   * @param {Object.<string, Function|string>} invocables  functions to invoke or `$injector` services to fetch.
+   * @param {Object.<string, *>} [locals]  values to make available to the injectables
+   * @param {Promise.<Object>} [parent]  a promise returned by another call to `$resolve`.
+   * @param {Object} [self]  the `this` for the invoked methods
+   * @return {Promise.<Object>}  Promise for an object that contains the resolved return value
+   *    of all invocables, as well as any inherited and local values.
+   */
+  this.resolve = function (invocables, locals, parent, self) {
+    return this.study(invocables)(locals, parent, self);
+  };
+}
+
+angular.module('ui.router.util').service('$resolve', $Resolve);
+

src/state.js

@@ -175,7 +175,6 @@ function $StateProvider(   $urlRouterProvider,   $urlMatcherFactory,           $
     views: null,
     'abstract': true
   });
-  root.locals = { globals: { $stateParams: {} } };
   root.navigable = null;
 
 
@@ -192,12 +191,13 @@ function $StateProvider(   $urlRouterProvider,   $urlMatcherFactory,           $
 
   // $urlRouter is injected just to ensure it gets instantiated
   this.$get = $get;
-  $get.$inject = ['$rootScope', '$q', '$view', '$injector', '$stateParams', '$location', '$urlRouter'];
-  function $get(   $rootScope,   $q,   $view,   $injector,   $stateParams,   $location,   $urlRouter) {
+  $get.$inject = ['$rootScope', '$q', '$view', '$injector', '$resolve', '$stateParams', '$location', '$urlRouter'];
+  function $get(   $rootScope,   $q,   $view,   $injector,   $resolve,   $stateParams,   $location,   $urlRouter) {
 
     var TransitionSuperseded = $q.reject(new Error('transition superseded'));
     var TransitionPrevented = $q.reject(new Error('transition prevented'));
 
+    root.locals = { resolve: null, globals: { $stateParams: {} } };
     $state = {
       params: {},
       current: root.self,
@@ -259,7 +259,7 @@ function $StateProvider(   $urlRouterProvider,   $urlMatcherFactory,           $
         resolved = resolveState(state, toParams, state===to, resolved, locals);
       }
 
-      // Once everything is resolved, we are ready to perform the actual transition
+      // Once everything is resolved, wer are ready to perform the actual transition
       // and return a promise for the new state. We also keep track of what the
       // current promise is, so that we can detect overlapping transitions and
       // keep only the outcome of the last transition.
@@ -341,67 +341,41 @@ function $StateProvider(   $urlRouterProvider,   $urlMatcherFactory,           $
     };
 
     function resolveState(state, params, paramsAreFiltered, inherited, dst) {
-      // We need to track all the promises generated during the resolution process.
-      // The first of these is for the fully resolved parent locals.
-      var promises = [inherited];
-
       // Make a restricted $stateParams with only the parameters that apply to this state if
       // necessary. In addition to being available to the controller and onEnter/onExit callbacks,
       // we also need $stateParams to be available for any $injector calls we make during the
       // dependency resolution process.
       var $stateParams = (paramsAreFiltered) ? params : filterByKeys(state.params, params);
       var locals = { $stateParams: $stateParams };
 
-      // Resolves the values from an individual 'resolve' dependency spec
-      function resolve(deps, dst) {
-        forEach(deps, function (value, key) {
-          promises.push($q
-            .when(isString(value) ?
-                $injector.get(value) :
-                $injector.invoke(value, state.self, locals))
-            .then(function (result) {
-              dst[key] = result;
-            }));
-        });
-      }
-
       // Resolve 'global' dependencies for the state, i.e. those not specific to a view.
       // We're also including $stateParams in this; that way the parameters are restricted
       // to the set that should be visible to the state, and are independent of when we update
       // the global $state and $stateParams values.
-      var globals = dst.globals = { $stateParams: $stateParams };
-      resolve(state.resolve, globals);
-      globals.$$state = state; // Provide access to the state itself for internal use
+      dst.resolve = $resolve.resolve(state.resolve, locals, dst.resolve, state);
+      var promises = [ dst.resolve.then(function (globals) {
+        dst.globals = globals;
+      }) ];
+      if (inherited) promises.push(inherited);
 
       // Resolve template and dependencies for all views.
       forEach(state.views, function (view, name) {
-        // References to the controller (only instantiated at link time)
-        var _$view = dst[name] = {
-          $$controller: view.controller
-        };
-
-        // Template
-        promises.push($q
-          .when($view.load(name, { view: view, locals: locals, params: $stateParams, notify: false }) || '')
-          .then(function (result) {
-            _$view.$template = result;
-          }));
-
-        // View-local dependencies. If we've reused the state definition as the default
-        // view definition in .state(), we can end up with state.resolve === view.resolve.
-        // Avoid resolving everything twice in that case.
-        if (view.resolve !== state.resolve) resolve(view.resolve, _$view);
+        var injectables = (view.resolve && view.resolve !== state.resolve ? view.resolve : {});
+        injectables.$template = [ function () {
+          return $view.load(name, { view: view, locals: locals, params: $stateParams, notify: false }) || '';
+        }];
+
+        promises.push($resolve.resolve(injectables, locals, dst.resolve, state).then(function (result) {
+          // References to the controller (only instantiated at link time)
+          result.$$controller = view.controller;
+          // Provide access to the state itself for internal use
+          result.$$state = state;
+          dst[name] = result;
+        }));
       });
 
-      // Once we've resolved all the dependencies for this state, merge
-      // in any inherited dependencies, and merge common state dependencies
-      // into the dependency set for each view. Finally return a promise
-      // for the fully popuplated state dependencies.
+      // Wait for all the promises and then return the activation object
       return $q.all(promises).then(function (values) {
-        merge(dst.globals, values[0].globals); // promises[0] === inherited
-        forEach(state.views, function (view, name) {
-          merge(dst[name], dst.globals);
-        });
         return dst;
       });
     }