feat(lazyLoad): Add state.lazyLoad hook to lazy load a tree of states

Closes #146
Closes #2739

src/hooks/lazyLoadStates.ts

@@ -0,0 +1,63 @@
+import {Transition} from "../transition/transition";
+import {TransitionService} from "../transition/transitionService";
+import {TransitionHookFn} from "../transition/interface";
+import {StateDeclaration} from "../state/interface";
+import {State} from "../state/stateObject";
+import {services} from "../common/coreservices";
+
+/**
+ * A [[TransitionHookFn]] that lazy loads a state tree.
+ *
+ * When transitioning to a state "abc" which has a `lazyLoad` function defined:
+ * - Invoke the `lazyLoad` function
+ * - The function should return a promise for an array of lazy loaded [[StateDeclaration]]s
+ * - Wait for the promise to resolve
+ * - Deregister the original state "abc"
+ * - The original state definition is a placeholder for the lazy loaded states
+ * - Register the new states
+ * - Retry the transition
+ *
+ * See [[StateDeclaration.lazyLoad]]
+ */
+const lazyLoadHook: TransitionHookFn = (transition: Transition) => {
+ var toState = transition.to();
+
+ function retryOriginalTransition(newStates: State[]) {
+ if (transition.options().source === 'url') {
+ let loc = services.location;
+ let path = loc.path(), search = loc.search(), hash = loc.hash();
+
+ let matchState = state => [state, state.url.exec(path, search, hash)];
+ let matches = newStates.map(matchState).filter(([state, params]) => !!params);
+ if (matches.length) {
+ let [state, params] = matches[0];
+ return transition.router.stateService.target(state, params, transition.options());
+ }
+ transition.router.urlRouter.sync();
+ }
+
+ let state = transition.targetState().identifier();
+ let params = transition.params();
+ let options = transition.options();
+ return transition.router.stateService.target(state, params, options);
+ }
+
+ /**
+ * Replace the placeholder state with the newly loaded states from the NgModule.
+ */
+ function updateStateRegistry(newStates: StateDeclaration[]) {
+ let registry = transition.router.stateRegistry;
+ let placeholderState = transition.to();
+
+ registry.deregister(placeholderState);
+ newStates.forEach(state => registry.register(state));
+ return newStates.map(state => registry.get(state).$$state());
+ }
+
+ return toState.lazyLoad(transition)
+ .then(updateStateRegistry)
+ .then(retryOriginalTransition)
+};
+
+export const registerLazyLoadHook = (transitionService: TransitionService) =>
+ transitionService.onBefore({ to: (state) => !!state.lazyLoad }, lazyLoadHook);

src/hooks/url.ts

@@ -3,6 +3,7 @@ import {UrlRouter} from "../url/urlRouter";
 import {StateService} from "../state/stateService";
 import {Transition} from "../transition/transition";
 import {TransitionHookFn} from "../transition/interface";
+import {TransitionService} from "../transition/transitionService";
 
 /** 
  * A [[TransitionHookFn]] which updates the URL after a successful transition

src/ng2.ts

@@ -8,10 +8,12 @@ export * from "./core";
 import "./justjs";
 
 export * from "./ng2/interface";
-export * from "./ng2/routerModule";
+export * from "./ng2/lazyLoadNgModule";
 export * from "./ng2/providers";
 export * from "./ng2/location";
 export * from "./ng2/directives/directives";
 export * from "./ng2/statebuilders/views";
+export * from "./ng2/statebuilders/lazyLoadNgModuleResolvable";
+export * from "./ng2/uiRouterNgModule";
 export * from "./ng2/uiRouterConfig";
 

src/ng2/directives/directives.ts

@@ -19,15 +19,6 @@ export * from "./uiSrefActive";
 
 /**
  * References to the UI-Router directive classes, for use within a @Component's `directives:` property
- *
- * @example
- * ```js
- *
- * Component({
- * selector: 'my-cmp',
- * directives: [UIROUTER_DIRECTIVES],
- * template: '<a uiSref="foo">Foo</a>'
- * })
- * ```
+ * @deprecated use [[UIRouterModule]]
  */
 export let UIROUTER_DIRECTIVES = [UISref, AnchorUISref, UIView, UISrefActive, UISrefStatus];

src/ng2/interface.ts

@@ -1,7 +1,7 @@
 /** @module ng2 */ /** */
 import {StateDeclaration, _ViewDeclaration} from "../state/interface";
 import {Transition} from "../transition/transition";
-import {Type} from "@angular/core";
+import {Type, OpaqueToken} from "@angular/core";
 import {HookResult} from "../transition/interface";
 
 /**
@@ -342,4 +342,4 @@ export interface Ng2Component {
  uiCanExit(): HookResult;
 }
 
-export const NG2_INJECTOR_TOKEN = {};
+export const NG2_INJECTOR_TOKEN = new OpaqueToken("NgModule Injector");

src/ng2/lazyLoadNgModule.ts

@@ -0,0 +1,68 @@
+import {Transition} from "../transition/transition";
+import {NG2_INJECTOR_TOKEN, Ng2StateDeclaration} from "./interface";
+import {UIROUTER_STATES_TOKEN} from "./uiRouterNgModule";
+
+import {NgModuleFactoryLoader, NgModuleRef, Injector, NgModuleFactory} from "@angular/core";
+import {unnestR} from "../common/common";
+
+/**
+ * Returns a function which lazy loads a nested module
+ *
+ * Use this function as a [[StateDeclaration.lazyLoad]] property to lazy load a state tree (an NgModule).
+ *
+ * @param path the path to the module source code.
+ * @returns A function which takes a transition, then:
+ *
+ * - Gets the Injector (scoped properly for the destination state)
+ * - Loads and creates the NgModule
+ * - Finds the "replacement state" for the target state, and adds the new NgModule Injector to it (as a resolve)
+ *
+ * returns the new states array
+ */
+export function loadNgModule(path: string) {
+ /** Get the parent NgModule Injector (from resolves) */
+ const getNg2Injector = (transition: Transition) =>
+ transition.injector().getAsync(NG2_INJECTOR_TOKEN);
+
+ /**
+ * Lazy loads the NgModule using the NgModuleFactoryLoader
+ *
+ * Use the parent NgModule's Injector to:
+ * - Find the correct NgModuleFactoryLoader
+ * - Load the new NgModuleFactory from the path string (async)
+ * - Create the new NgModule
+ */
+ const createNg2Module = (path: string, ng2Injector: Injector) =>
+ ng2Injector.get(NgModuleFactoryLoader).load(path)
+ .then((factory: NgModuleFactory<any>) => factory.create(ng2Injector));
+
+ /**
+ * Apply the Lazy Loaded NgModule's Injector to the newly loaded state tree.
+ *
+ * Lazy loading uses a placeholder state which is removed (and replaced) after the module is loaded.
+ * The NgModule should include a state with the same name as the placeholder.
+ *
+ * Find the *newly loaded state* with the same name as the *placeholder state*.
+ * The NgModule's Injector (and ComponentFactoryResolver) will be added to that state.
+ * The Injector/Factory are used when creating Components for the `replacement` state and all its children.
+ */
+ function applyNgModuleToNewStates(transition: Transition, ng2Module: NgModuleRef<any>): Ng2StateDeclaration[] {
+ var targetName = transition.to().name;
+ let newStates: Ng2StateDeclaration[] = ng2Module.injector.get(UIROUTER_STATES_TOKEN).reduce(unnestR, []);
+ let replacementState = newStates.find(state => state.name === targetName);
+
+ if (!replacementState) {
+ throw new Error(`The module that was loaded from ${path} should have a state named '${targetName}'` +
+ `, but it only had: ${(newStates || []).map(s=>s.name).join(', ')}`);
+ }
+
+ // Add the injector as a resolve.
+ replacementState['_ngModuleInjector'] = ng2Module.injector;
+
+ return newStates;
+ }
+
+ return (transition: Transition) => getNg2Injector(transition)
+ .then((injector: Injector) => createNg2Module(path, injector))
+ .then((moduleRef: NgModuleRef<any>) => applyNgModuleToNewStates(transition, moduleRef))
+}

src/ng2/providers.ts

@@ -64,15 +64,27 @@ import {UIRouterLocation} from "./location";
 import {services} from "../common/coreservices";
 import {ProviderLike} from "../state/interface";
 import {Resolvable} from "../resolve/resolvable";
+import {ngModuleResolvablesBuilder} from "./statebuilders/lazyLoadNgModuleResolvable";
 
 let uiRouterFactory = (routerConfig: UIRouterConfig, location: UIRouterLocation, injector: Injector) => {
  services.$injector.get = injector.get.bind(injector);
- let router = new UIRouter();
 
  location.init();
 
+
+ // ----------------- Create router -----------------
+ // Create a new ng2 UIRouter and configure it for ng2
+ let router = new UIRouter();
+ let registry = router.stateRegistry;
+
+ // ----------------- Configure for ng2 -------------
+ // Apply ng2 ui-view handling code
  router.viewService.viewConfigFactory("ng2", (path: PathNode[], config: Ng2ViewDeclaration) => new Ng2ViewConfig(path, config));
- router.stateRegistry.decorator('views', ng2ViewsBuilder);
+ registry.decorator('views', ng2ViewsBuilder);
+
+ // Apply statebuilder decorator for ng2 NgModule registration
+ registry.stateQueue.flush(router.stateService);
+ registry.decorator('resolvables', ngModuleResolvablesBuilder);
 
  router.stateRegistry.stateQueue.autoFlush(router.stateService);
 

src/ng2/statebuilders/lazyLoadNgModuleResolvable.ts

@@ -0,0 +1,21 @@
+/** @module ng2 */ /** */
+import {State} from "../../state/stateObject";
+import {NG2_INJECTOR_TOKEN} from "../interface";
+import {Resolvable} from "../../resolve/resolvable";
+
+/**
+ * This is a [[StateBuilder.builder]] function which enables lazy Ng2Module support.
+ * 
+ * See [[loadNgModule]]
+ *
+ * After lazy loading an NgModule, any Components from that module should be created using the NgModule's Injecjtor.
+ * The NgModule's ComponentFactory only exists inside that Injector.
+ * 
+ * After lazy loading an NgModule, it is stored on the root state of the lazy loaded state tree.
+ * When instantiating Component, the parent Component's Injector is merged with the NgModule injector.
+ */
+export function ngModuleResolvablesBuilder(state: State, parentFn: Function): Resolvable[] {
+ let resolvables: Resolvable[] = parentFn(state);
+ let injector = state.self['_ngModuleInjector'];
+ return !injector ? resolvables : resolvables.concat(Resolvable.fromData(NG2_INJECTOR_TOKEN, injector));
+}

src/ng2/routerModule.ts → src/ng2/uiRouterNgModule.ts

@@ -3,15 +3,15 @@ import {NgModule, NgModuleMetadataType, OpaqueToken} from "@angular/core";
 import {UIROUTER_DIRECTIVES} from "./directives/directives";
 import {UIROUTER_PROVIDERS} from "./providers";
 import {UIView} from "./directives/uiView";
-import {uniqR} from "../common/common";
+import {uniqR, flattenR} from "../common/common";
 
 @NgModule({
  declarations: [UIROUTER_DIRECTIVES],
  exports: [UIROUTER_DIRECTIVES],
  entryComponents: [UIView],
  providers: [UIROUTER_PROVIDERS]
 })
-export class _UIRouterModule {}
+export class UIRouterRootModule {}
 
 /**
  * A module declaration lteral, including UI-Router states.
@@ -23,7 +23,7 @@ export interface UIRouterModuleMetadata extends NgModuleMetadataType {
  states?: Ng2StateDeclaration[]
 }
 
-export const UIROUTER_STATES_TOKEN = new OpaqueToken("UIRouterStates");
+export const UIROUTER_STATES_TOKEN = new OpaqueToken("UIRouter States");
 
 /**
  * Declares a NgModule with UI-Router states
@@ -51,17 +51,19 @@ export const UIROUTER_STATES_TOKEN = new OpaqueToken("UIRouterStates");
  */
 export function UIRouterModule(moduleMetaData: UIRouterModuleMetadata) {
  let states = moduleMetaData.states || [];
+ var statesProvider = { provide: UIROUTER_STATES_TOKEN, useValue: states, multi: true };
 
  // Get the component classes for all views for all states in the module
- let components = states.map(state => state.views || { $default: state })
+ let routedComponents = states.reduce(flattenR, [])
+ .map(state => state.views || { $default: state })
  .map(viewObj => Object.keys(viewObj).map(key => viewObj[key].component))
  .reduce((acc, arr) => acc.concat(arr), [])
  .filter(x => typeof x === 'function' && x !== UIView);
 
- moduleMetaData.imports = <any[]> (moduleMetaData.imports || []).concat(_UIRouterModule).reduce(uniqR, []);
- moduleMetaData.declarations = <any[]> (moduleMetaData.declarations || []).concat(components).reduce(uniqR, []);
- moduleMetaData.entryComponents = <any[]> (moduleMetaData.entryComponents || []).concat(components).reduce(uniqR, []);
- moduleMetaData.providers = (moduleMetaData.providers || []).concat({ provide: UIROUTER_STATES_TOKEN, useValue: states });
+ moduleMetaData.imports  = <any[]> (moduleMetaData.imports || []).concat(UIRouterRootModule).reduce(uniqR, []);
+ moduleMetaData.declarations  = <any[]> (moduleMetaData.declarations || []).concat(routedComponents).reduce(uniqR, []);
+ moduleMetaData.entryComponents  = <any[]> (moduleMetaData.entryComponents || []).concat(routedComponents).reduce(uniqR, []);
+ moduleMetaData.providers  = (moduleMetaData.providers || []).concat(statesProvider);
 
  return function(moduleClass) {
  return NgModule(moduleMetaData)(moduleClass);

src/resolve/resolvable.ts

@@ -167,4 +167,7 @@ export class Resolvable implements ResolvableLiteral {
  clone(): Resolvable {
  return new Resolvable(this);
  }
+
+ static fromData = (token: any, data: any) => 
+ new Resolvable(token, () => data, null, null, data);
 }

src/state/interface.ts

@@ -520,6 +520,15 @@ export interface StateDeclaration {
  */
  onExit?: TransitionStateHookFn;
 
+ /**
+ * A function that lazy loads a state tree.
+ 
+ 
+ *
+ * @param transition
+ */
+ lazyLoad?: (transition: Transition) => Promise<StateDeclaration[]>;
+
  /**
  * @deprecated define individual parameters as [[ParamDeclaration.dynamic]]
  */

src/state/stateMatcher.ts

@@ -2,6 +2,8 @@
 import {isString} from "../common/predicates";
 import {StateOrName} from "./interface";
 import {State} from "./stateObject";
+import {Glob} from "../common/glob";
+import {values} from "../common/common";
 
 export class StateMatcher {
  constructor (private _states: { [key: string]: State }) { }
@@ -22,6 +24,17 @@ export class StateMatcher {
 
  if (state && (isStr || (!isStr && (state === stateOrName || state.self === stateOrName)))) {
  return state;
+ } else if (isStr) {
+ let matches = values(this._states)
+ .filter(state => !!state.lazyLoad)
+ .map(state => ({ state, glob: new Glob(state.name + ".**")}))
+ .filter(({state, glob}) => glob.matches(name))
+ .map(({state, glob}) => state);
+
+ if (matches.length > 1) {
+ console.log(`stateMatcher.find: Found multiple matches for ${name} using glob: `, matches.map(match => match.name));
+ }
+ return matches[0];
  }
  return undefined;
  }

src/state/stateObject.ts

@@ -44,6 +44,7 @@ export class State {
  public onExit: TransitionStateHookFn;
  public onRetain: TransitionStateHookFn;
  public onEnter: TransitionStateHookFn;
+ public lazyLoad: (transition: Transition) => Promise<StateDeclaration[]>;
 
  redirectTo: (
  string |

src/transition/transitionService.ts

@@ -17,6 +17,7 @@ import {registerLoadEnteringViews, registerActivateViews} from "../hooks/views";
 import {registerUpdateUrl} from "../hooks/url";
 import {registerRedirectToHook} from "../hooks/redirectTo";
 import {registerOnExitHook, registerOnRetainHook, registerOnEnterHook} from "../hooks/onEnterExitRetain";
+import {registerLazyLoadHook} from "../hooks/lazyLoadStates";
 
 /**
  * The default [[Transition]] options.
@@ -50,12 +51,13 @@ export class TransitionService implements IHookRegistry {
  public $view: ViewService;
 
  /**
- * This object has hook de-registration functions.
+ * This object has hook de-registration functions for the built-in hooks.
  * This can be used by third parties libraries that wish to customize the behaviors
  *
  * @hidden
  */
  _deregisterHookFns: {
+ redirectTo: Function;
  onExit: Function;
  onRetain: Function;
  onEnter: Function;
@@ -64,7 +66,7 @@ export class TransitionService implements IHookRegistry {
  loadViews: Function;
  activateViews: Function;
  updateUrl: Function;
- redirectTo: Function;
+ lazyLoad: Function;
  };
 
  constructor(private _router: UIRouter) {
@@ -96,6 +98,9 @@ export class TransitionService implements IHookRegistry {
 
  // After globals.current is updated at priority: 10000
  fns.updateUrl = registerUpdateUrl(this);
+
+ // Lazy load state trees
+ fns.lazyLoad = registerLazyLoadHook(this);
  }
 
  /** @inheritdoc */