BC-BREAK: Removed ResolvePolicy enum in favor of the ResolvePolicy interface { when: "", async: "" }

BC-BREAK: renamed `ResolveContext.isolateRootTo` to `subContext`
BC-BREAK: rename `UIRouterGlobals` class to `Globals`; add `UIRouterGlobals` as interface
feat(ParamType): allow a parameter type to specify a default val for dynamic
feat(Resolvable): RXWAIT: resolve to an Observable, but also wait for the first value to emit
refactor(Resolvable): pre-compute the resolve policy in resolvableBuilder
chore(trace): Pass transition directly to resolve trace functions

Author: christopherthielen

packages/ng2/webpack.config.js

@@ -49,6 +49,7 @@ module.exports = {
   },
 
   externals: {
+    "rxjs/Rx": { root: 'rxjs/Rx', amd: 'rxjs/Rx', commonjs2: 'rxjs/Rx', commonjs: 'rxjs/Rx' },
     "@angular/core": { root: '@angular/core', amd: '@angular/core', commonjs2: '@angular/core', commonjs: '@angular/core' },
     "@angular/common": { root: '@angular/common', amd: '@angular/common', commonjs2: '@angular/common', commonjs: '@angular/common' }
   }

src/common/trace.ts

@@ -34,6 +34,9 @@ import {isNumber} from "../common/predicates";
 import {Transition}  from "../transition/transition";
 import {ActiveUIView, ViewConfig}  from "../view/interface";
 import {stringify, functionToString, maxLength, padString} from "./strings";
+import {Resolvable} from "../resolve/resolvable";
+import {PathNode} from "../path/node";
+import {PolicyWhen} from "../resolve/interface";
 
 /** @hidden */
 function uiViewString (viewData) {
@@ -140,11 +143,11 @@ export class Trace {
   }
 
   /** called by ui-router code */
-  traceTransitionIgnored(transition: Transition) {
+  traceTransitionIgnored(trans: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
-    let tid = transition.$id,
+    let tid = trans && trans.$id,
         digest = this.approximateDigests,
-        transitionStr = stringify(transition);
+        transitionStr = stringify(trans);
     console.log(`Transition #${tid} Digest #${digest}: Ignored  <> ${transitionStr}`);
   }
 
@@ -170,72 +173,40 @@ export class Trace {
   }
 
   /** called by ui-router code */
-  traceResolvePath(path, options) {
+  traceResolvePath(path: PathNode[], when: PolicyWhen, trans?: Transition) {
     if (!this.enabled(Category.RESOLVE)) return;
-    let tid = parse("transition.$id")(options),
+    let tid = trans && trans.$id,
         digest = this.approximateDigests,
-        pathStr = path && path.toString(),
-        policyStr = options && options.resolvePolicy;
-    console.log(`Transition #${tid} Digest #${digest}:         Resolving ${pathStr} (${policyStr})`);
+        pathStr = path && path.toString();
+    console.log(`Transition #${tid} Digest #${digest}:         Resolving ${pathStr} (${when})`);
   }
 
   /** called by ui-router code */
-  traceResolvePathElement(pathElement, resolvablePromises, options) {
+  traceResolvableResolved(resolvable: Resolvable, trans?: Transition) {
     if (!this.enabled(Category.RESOLVE)) return;
-    if (!resolvablePromises.length) return;
-    let tid = parse("transition.$id")(options),
-        digest = this.approximateDigests,
-        resolvablePromisesStr = Object.keys(resolvablePromises).join(", "),
-        pathElementStr = pathElement && pathElement.toString(),
-        policyStr = options && options.resolvePolicy;
-    console.log(`Transition #${tid} Digest #${digest}:         Resolve ${pathElementStr} resolvables: [${resolvablePromisesStr}] (${policyStr})`);
-  }
-
-  /** called by ui-router code */
-  traceResolveResolvable(resolvable, options) {
-    if (!this.enabled(Category.RESOLVE)) return;
-    let tid = parse("transition.$id")(options),
-        digest = this.approximateDigests,
-        resolvableStr = resolvable && resolvable.toString();
-    console.log(`Transition #${tid} Digest #${digest}:               Resolving -> ${resolvableStr}`);
-  }
-
-  /** called by ui-router code */
-  traceResolvableResolved(resolvable, options) {
-    if (!this.enabled(Category.RESOLVE)) return;
-    let tid = parse("transition.$id")(options),
+    let tid = trans && trans.$id,
         digest = this.approximateDigests,
         resolvableStr = resolvable && resolvable.toString(),
         result = stringify(resolvable.data);
     console.log(`Transition #${tid} Digest #${digest}:               <- Resolved  ${resolvableStr} to: ${maxLength(200, result)}`);
   }
 
   /** called by ui-router code */
-  tracePathElementInvoke(node, fn, deps, options) {
-    if (!this.enabled(Category.INVOKE)) return;
-    let tid = parse("transition.$id")(options),
-        digest = this.approximateDigests,
-        stateName = node && node.state && node.state.toString(),
-        fnName = functionToString(fn);
-    console.log(`Transition #${tid} Digest #${digest}:         Invoke ${options.when}: context: ${stateName} ${maxLength(200, fnName)}`);
-  }
-
-  /** called by ui-router code */
-  traceError(error, transition: Transition) {
+  traceError(error, trans: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
-    let tid = transition.$id,
+    let tid = trans && trans.$id,
         digest = this.approximateDigests,
-        transitionStr = stringify(transition);
+        transitionStr = stringify(trans);
     console.log(`Transition #${tid} Digest #${digest}: <- Rejected ${transitionStr}, reason: ${error}`);
   }
 
   /** called by ui-router code */
-  traceSuccess(finalState, transition: Transition) {
+  traceSuccess(finalState, trans: Transition) {
     if (!this.enabled(Category.TRANSITION)) return;
-    let tid = transition.$id,
+    let tid = trans && trans.$id,
         digest = this.approximateDigests,
         state = finalState.name,
-        transitionStr = stringify(transition);
+        transitionStr = stringify(trans);
     console.log(`Transition #${tid} Digest #${digest}: <- Success  ${transitionStr}, final state: ${state}`);
   }
 

src/globals.ts

@@ -6,20 +6,21 @@ import {Transition} from "./transition/transition";
 import {Queue} from "./common/queue";
 import {TransitionService} from "./transition/transitionService";
 import {copy} from "./common/common";
+import {Observable} from "rxjs/Rx";
 
 /**
  * Global mutable state
  *
  * This is where we hold the global mutable state such as current state, current
- * params, current transition, last successful transition, last attempted transition, etc.
+ * params, current transition, etc.
  */
-export class UIRouterGlobals {
+export interface UIRouterGlobals {
   /**
    * Current parameter values
    *
    * The parameter values from the latest successful transition
    */
-  params: StateParams = new StateParams();
+  params: StateParams;
   /**
    * Current state
    *
@@ -36,17 +37,18 @@ export class UIRouterGlobals {
    * The current transition (in progress)
    */
   transition: Transition;
-  /**
-   * The transition history
-   *
-   * This queue's size is limited to a maximum number (default: 1)
-   */
+}
+
+
+/**
+ * Global mutable state
+ */
+export class Globals implements UIRouterGlobals {
+  params: StateParams = new StateParams();
+  current: StateDeclaration;
+  $current: State;
+  transition: Transition;
   transitionHistory = new Queue<Transition>([], 1);
-  /**
-   * The history of successful transitions
-   *
-   * This queue's size is limited to a maximum number (default: 1)
-   */
   successfulTransitions = new Queue<Transition>([], 1);
 
   constructor(transitionService: TransitionService) {

src/ng2/directives/uiSrefStatus.ts

@@ -9,7 +9,7 @@ import {TargetState} from "../../state/targetState";
 import {TreeChanges} from "../../transition/interface";
 import {State} from "../../state/stateObject";
 import {anyTrueR, tail, unnestR} from "../../common/common";
-import {UIRouterGlobals} from "../../globals";
+import {UIRouterGlobals, Globals} from "../../globals";
 import {Param} from "../../params/param";
 import {PathFactory} from "../../path/pathFactory";
 
@@ -53,7 +53,7 @@ export class UiSrefStatus {
   };
 
   constructor(transitionService: TransitionService,
-              private _globals: UIRouterGlobals,
+              private _globals: Globals,
               private _stateService: StateService,
               public sref: UiSref) {
     this._deregisterHook = transitionService.onStart({}, $transition$ => this.processTransition($transition$));

src/ng2/providers.ts

@@ -59,9 +59,10 @@ import {UiView} from "./directives/uiView";
 import {ng2ViewsBuilder, Ng2ViewConfig} from "./statebuilders/views";
 import {Ng2ViewDeclaration} from "./interface";
 import {UIRouterConfig} from "./uiRouterConfig";
-import {UIRouterGlobals} from "../globals";
+import {Globals} from "../globals";
 import {UIRouterLocation} from "./location";
 import {services} from "../common/coreservices";
+import {ProviderLike} from "../state/interface";
 
 let uiRouterFactory = (routerConfig: UIRouterConfig, location: UIRouterLocation, injector: Injector) => {
   services.$injector.get = injector.get.bind(injector);
@@ -117,15 +118,7 @@ export const UIROUTER_PROVIDERS: ProviderLike[] = [
 
   { provide: StateRegistry, useFactory: (r: UIRouter) => { return r.stateRegistry; }, deps: [UIRouter]},
 
-  { provide: UIRouterGlobals, useFactory: (r: UIRouter) => { return r.globals; }, deps: [UIRouter]},
+  { provide: Globals, useFactory: (r: UIRouter) => { return r.globals; }, deps: [UIRouter]},
 
   { provide: UiView.PARENT_INJECT, useFactory: (r: StateRegistry) => { return { fqn: null, context: r.root() } }, deps: [StateRegistry]}
-];
-
-export interface ProviderLike {
-  provide: any,
-  useClass?: any,
-  useFactory?: Function,
-  deps?: any[]
-}
-
+];

src/params/interface.ts

@@ -210,7 +210,13 @@ export interface ParamDeclaration {
    * This is not part of the declaration; it is a calculated value depending on if a default value was specified or not.
    */
   isOptional: boolean;
-  /** @todo document this one too */
+  /**
+   * Dynamic flag
+   *
+   * When `dynamic` is `true`, changes to the parameter value will not cause the state to be entered/exited.
+   *
+   * The resolves will not be re-fetched, nor will views be recreated.
+   */
   dynamic: boolean;
 }
 

src/params/type.ts

@@ -46,6 +46,7 @@ function ArrayType(type, mode) {
   });
 
   extend(this, {
+    dynamic: type.dynamic,
     name: type.name,
     pattern: type.pattern,
     is: arrayHandler(type.is.bind(type), true),

src/resolve/interface.ts

@@ -5,13 +5,107 @@ export interface Resolvables {
   [key: string]: Resolvable;
 }
 
-export interface IOptions1 {
-  omitOwnLocals ?: string[];
-  resolvePolicy ?: string;
+/**
+ * A plain object used to describe a [[Resolvable]]
+ *
+ * These objects may be defined in [[StateDefinition.resolve]] blocks to declare
+ * async data that the state or substates require.
+ */
+export interface ResolvableLiteral {
+  /** The Dependency Injection token that will be used to inject/access the resolvable */
+  token: any;
+
+  /**
+   * The function that returns one of:
+   *
+   * - The resolved value (synchronously)
+   * - A promise for the resolved value
+   * - An Observable of the resolved value(s)
+   *
+   * This function will be provided the dependencies listed in [[deps]] as its arguments.
+   * The resolve system will asynchronously fetch the dependencies before invoking this function.
+   */
+  resolveFn: Function;
+
+  /** A policy that defines when to invoke the resolve, and whether to wait for async and unwrap the data */
+  policy?: ResolvePolicy;
+
+  /**
+   * The Dependency Injection tokens for dependencies of the [[resolveFn]].
+   * The DI tokens are references to other `Resolvables`, or to global services.
+   */
+  deps?: any[];
+
+  /** Pre-resolved value. */
+  data?: any
 }
 
-// Defines the available policies and their ordinals.
-export enum ResolvePolicy {
-  LAZY, // Lazy resolves are resolved before their state is entered.
-  EAGER // Eager resolves are resolved before the transition starts.
-}
+/**
+ * Defines how a resolve is processed during a transition
+ *
+ * @example
+ * ```js
+ *
+ * // Fetched when the resolve's state is being entered.
+ * // Wait for the promise to resolve.
+ * var policy1 = { when: "LAZY", async: "WAIT" }
+ *
+ * // Fetched when the Transition is starting.
+ * // Do not wait for the returned promise to resolve.
+ * // Inject the raw promise/value
+ * var policy2 = { when: "EAGER", async: "NOWAIT" }
+ * ```
+ *
+ * The policy for a given Resolvable is merged from three sources (highest priority first):
+ *
+ * 1) Individual resolve definition
+ * 2) State definition
+ * 3) Global default
+ *
+ * @example
+ * ```js
+ *
+ * // Wait for an Observable to emit one item.
+ * // Since `wait` is not specified, it uses the `wait`
+ * // policy defined on the state, or the global default
+ * // if no `wait` policy is defined on the state
+ * var myResolvablePolicy = { async: "RXWAIT" }
+ * ```
+ */
+export interface ResolvePolicy {
+  /**
+   * Defines when a Resolvable is resolved (fetched) during a transition
+   *
+   * - `LAZY` (default) resolved as the resolve's state is being entered
+   * - `EAGER` resolved as the transition is starting
+   */
+  when?: PolicyWhen;
+
+  /**
+   * Determines the unwrapping behavior of asynchronous resolve values.
+   *
+   * - `WAIT` (default) if a promise is returned from the resolveFn, wait for the promise before proceeding
+   * - `NOWAIT` if a promise is returned from the resolve, do not wait for the promise.
+   *            The promise will not be unwrapped.
+   *            The promise itself will be provided when the resolve is injected or bound elsewhere.
+   * - `RXWAIT` When an Observable is returned from the resolveFn, wait until the Observable emits at least one item.
+   *            The Observable item will not be unwrapped.
+   *            The Observable stream itself will be provided when the resolve is injected or bound elsewhere.
+   */
+  async?: PolicyAsync;
+}
+
+export type PolicyWhen = "LAZY" | "EAGER" ;
+export type PolicyAsync = "WAIT" | "NOWAIT" | "RXWAIT" ;
+
+export let resolvePolicies = {
+  when: {
+    LAZY: "LAZY",
+    EAGER: "EAGER"
+  },
+  async: {
+    WAIT: "WAIT",
+    NOWAIT: "NOWAIT",
+    RXWAIT: "RXWAIT"
+  }
+};