refactor(HookBuilder): support entering/exiting/retained matchcriteria

Author: christopherthielen

src/state/hooks/enterExitHooks.ts

@@ -15,17 +15,17 @@ export class EnterExitHooks {
   }
 
   registerOnEnterHooks() {
-    let onEnterRegistration = (state) => this.transition.onEnter({to: state.name}, state.onEnter);
-    this.transition.entering().filter(state => !!state.onEnter).forEach(onEnterRegistration);
+    this.transition.entering().filter(state => !!state.onEnter)
+        .forEach(state => this.transition.onEnter({entering: state.name}, state.onEnter));
   }
 
   registerOnRetainHooks() {
-    let onRetainRegistration = (state) => this.transition.onRetain({}, state.onRetain);
-    this.transition.retained().filter(state => !!state.onRetain).forEach(onRetainRegistration);
+    this.transition.retained().filter(state => !!state.onRetain)
+        .forEach(state => this.transition.onRetain({retained: state.name}, state.onRetain));
   }
 
   registerOnExitHooks() {
-    let onExitRegistration = (state) => this.transition.onExit({from: state.name}, state.onExit);
-    this.transition.exiting().filter(state => !!state.onExit).forEach(onExitRegistration);
+    this.transition.exiting().filter(state => !!state.onExit)
+        .forEach(state => this.transition.onExit({exiting: state.name}, state.onExit));
   }
 }

src/state/hooks/resolveHooks.ts

@@ -5,6 +5,7 @@ import {propEq} from "../../common/hof";
 import {ResolvePolicy} from "../../resolve/interface";
 
 import {Transition} from "../../transition/transition";
+import {val} from "../../common/hof";
 
 
 let LAZY = ResolvePolicy[ResolvePolicy.LAZY];
@@ -38,6 +39,6 @@ export class ResolveHooks {
     // Resolve eager resolvables before when the transition starts
     this.transition.onStart({}, $eagerResolvePath, { priority: 1000 });
     // Resolve lazy resolvables before each state is entered
-    this.transition.onEnter({}, $lazyResolveEnteringState, { priority: 1000 });
+    this.transition.onEnter({ entering: val(true) }, $lazyResolveEnteringState, { priority: 1000 });
   }
 }

src/transition/hookBuilder.ts

@@ -3,17 +3,12 @@
 import {IInjectable, extend, tail, assertPredicate, unnestR, flatten, identity} from "../common/common";
 import {isArray} from "../common/predicates";
 
-import {TransitionOptions, TransitionHookOptions, IHookRegistry, TreeChanges, IEventHook, ITransitionService} from "./interface";
+import {TransitionOptions, TransitionHookOptions, IHookRegistry, TreeChanges, IEventHook, ITransitionService, IMatchingNodes} from "./interface";
 
 import {Transition, TransitionHook} from "./module";
 import {State} from "../state/module";
 import {Node} from "../path/module";
 
-interface IToFrom {
-  to:   State;
-  from: State;
-}
-
 /**
  * This class returns applicable TransitionHooks for a specific Transition instance.
  *
@@ -36,7 +31,6 @@ export class HookBuilder {
   toState: State;
   fromState: State;
 
-
   constructor(private $transitions: ITransitionService, private transition: Transition, private baseHookOptions: TransitionHookOptions) {
     this.treeChanges        = transition.treeChanges();
     this.toState            = tail(this.treeChanges.to).state;
@@ -48,15 +42,14 @@ export class HookBuilder {
   // onBefore/onStart/onFinish/onSuccess/onError returns an array of hooks
   // onExit/onRetain/onEnter returns an array of arrays of hooks
 
-  getOnBeforeHooks  = () => this._buildTransitionHooks("onBefore", {}, { async: false });
-  getOnStartHooks   = () => this._buildTransitionHooks("onStart");
-  getOnExitHooks    = () => this._buildNodeHooks("onExit",          this.treeChanges.exiting.reverse(), (node) => this._toFrom({ from: node.state }));
-  getOnRetainHooks  = () => this._buildNodeHooks("onRetain",        this.treeChanges.retained,          (node) => this._toFrom());
-  getOnEnterHooks   = () => this._buildNodeHooks("onEnter",         this.treeChanges.entering,          (node) => this._toFrom({ to: node.state }));
-  getOnFinishHooks  = () => this._buildTransitionHooks("onFinish", { $treeChanges$: this.treeChanges });
-  getOnSuccessHooks = () => this._buildTransitionHooks("onSuccess", {}, {async: false, rejectIfSuperseded: false});
-  getOnErrorHooks   = () => this._buildTransitionHooks("onError", {}, {async: false, rejectIfSuperseded: false});
-
+  getOnBeforeHooks  = () => this._buildNodeHooks("onBefore",  "to",       tupleSort(), undefined, { async: false });
+  getOnStartHooks   = () => this._buildNodeHooks("onStart",   "to",       tupleSort());
+  getOnExitHooks    = () => this._buildNodeHooks("onExit",    "exiting",  tupleSort(true), (node) => ({ $state$: node.state }));
+  getOnRetainHooks  = () => this._buildNodeHooks("onRetain",  "retained", tupleSort(), (node) => ({ $state$: node.state }));
+  getOnEnterHooks   = () => this._buildNodeHooks("onEnter",   "entering", tupleSort(), (node) => ({ $state$: node.state }));
+  getOnFinishHooks  = () => this._buildNodeHooks("onFinish",  "to",       tupleSort(), (node) => ({ $treeChanges$: this.treeChanges }));
+  getOnSuccessHooks = () => this._buildNodeHooks("onSuccess", "to",       tupleSort(), undefined, {async: false, rejectIfSuperseded: false});
+  getOnErrorHooks   = () => this._buildNodeHooks("onError",   "to",     tupleSort(), undefined, {async: false, rejectIfSuperseded: false});
 
   asyncHooks() {
     let onStartHooks    = this.getOnStartHooks();
@@ -65,75 +58,88 @@ export class HookBuilder {
     let onEnterHooks    = this.getOnEnterHooks();
     let onFinishHooks   = this.getOnFinishHooks();
 
-    return flatten([onStartHooks, onExitHooks, onRetainHooks, onEnterHooks, onFinishHooks]).filter(identity);
-  }
-
-  private _toFrom(toFromOverride?): IToFrom {
-    return extend({ to: this.toState, from: this.fromState }, toFromOverride);
+    let asyncHooks = [onStartHooks, onExitHooks, onRetainHooks, onEnterHooks, onFinishHooks];
+    return asyncHooks.reduce(unnestR, []).filter(identity);
   }
 
   /**
    * Returns an array of newly built TransitionHook objects.
    *
-   * Builds a TransitionHook which cares about the entire Transition, for instance, onActivate
-   * Finds all registered IEventHooks which matched the hookType and toFrom criteria.
-   * A TransitionHook is then built from each IEventHook with the context, locals, and options provided.
-   */
-  private _buildTransitionHooks(hookType: string, locals = {}, options: TransitionHookOptions = {}) {
-    let context = this.treeChanges.to, node = tail(context);
-    options.traceData = { hookType, context };
-
-    const transitionHook = eventHook => this.buildHook(node, eventHook.callback, locals, options);
-    return this._matchingHooks(hookType, this._toFrom()).map(transitionHook);
-  }
-
-  /**
-   * Returns an 2 dimensional array of newly built TransitionHook objects.
-   * Each inner array contains the hooks for a node in the Path.
+   * - Finds all IEventHooks registered for the given `hookType` which matched the transition's [[TreeChanges]].
+   * - Finds [[Node]] (or `Node[]`) to use as the TransitionHook context(s)
+   * - For each of the [[Node]]s, creates a TransitionHook
    *
-   * For each Node in the Path:
-   * Builds the toFrom criteria
-   * Finds all registered IEventHooks which matched the hookType and toFrom criteria.
-   * A TransitionHook is then built from each IEventHook with the context, locals, and options provided.
+   * @param hookType the name of the hook registration function, e.g., 'onEnter', 'onFinish'.
+   * @param matchingNodesProp selects which [[Node]]s from the [[IMatchingNodes]] object to create hooks for.
+   * @param getLocals a function which accepts a [[Node]] and returns additional locals to provide to the hook as injectables
+   * @param sortHooksFn a function which compares two HookTuple and returns <1, 0, or >1
+   * @param options any specific Transition Hook Options
    */
-  private _buildNodeHooks(hookType: string, path: Node[], toFromFn: (node: Node) => IToFrom, locals: any = {}, options: TransitionHookOptions = {}) {
-    const hooksForNode = (node: Node) => {
-      let toFrom = toFromFn(node);
-      options.traceData = { hookType, context: node };
-      locals.$state$ = node.state;
-
-      const transitionHook = eventHook => this.buildHook(node, eventHook.callback, locals, options);
-      return this._matchingHooks(hookType, toFrom).map(transitionHook);
+  private _buildNodeHooks(hookType: string,
+                          matchingNodesProp: string,
+                          sortHooksFn: (l: HookTuple, r: HookTuple) => number,
+                          getLocals: (node: Node) => any = (node) => ({}),
+                          options: TransitionHookOptions = {}): TransitionHook[] {
+
+    // Find all the matching registered hooks for a given hook type
+    let matchingHooks = this._matchingHooks(hookType, this.treeChanges);
+    if (!matchingHooks) return [];
+
+     const makeTransitionHooks = (hook: IEventHook) => {
+      // Fetch the Nodes that caused this hook to match.
+      let matches: IMatchingNodes = hook.matches(this.treeChanges);
+      // Select the Node[] that will be used as TransitionHook context objects
+      let nodes: Node[] = matches[matchingNodesProp];
+
+      // Return an array of HookTuples
+      return nodes.map(node => {
+        let _options = extend({ traceData: { hookType, context: node} }, this.baseHookOptions, options);
+        let transitionHook = new TransitionHook(hook.callback, getLocals(node), node.resolveContext, _options);
+        return <HookTuple> { hook, node, transitionHook };
+      });
     };
 
-    return path.map(hooksForNode);
-  }
-
-  /** Given a node and a callback function, builds a TransitionHook */
-  buildHook(node: Node, fn: IInjectable, locals?, options: TransitionHookOptions = {}): TransitionHook {
-    let _options = extend({}, this.baseHookOptions, options);
-    return new TransitionHook(fn, extend({}, locals), node.resolveContext, _options);
+    return matchingHooks.map(makeTransitionHooks)
+        .reduce(unnestR, [])
+        .sort(sortHooksFn)
+        .map(tuple => tuple.transitionHook);
   }
 
-
   /**
-   * returns an array of the IEventHooks from:
+   * Finds all IEventHooks from:
    * - The Transition object instance hook registry
    * - The TransitionService ($transitions) global hook registry
+   *
    * which matched:
    * - the eventType
-   * - the matchCriteria to state
-   * - the matchCriteria from state
+   * - the matchCriteria (to, from, exiting, retained, entering)
+   *
+   * @returns an array of matched [[IEventHook]]s
    */
-  private _matchingHooks(hookName: string, matchCriteria: IToFrom): IEventHook[] {
-    const matchFilter   = hook => hook.matches(matchCriteria.to, matchCriteria.from);
-    const prioritySort  = (l, r) => r.priority - l.priority;
-
+  private _matchingHooks(hookName: string, treeChanges: TreeChanges): IEventHook[] {
     return [ this.transition, this.$transitions ]                             // Instance and Global hook registries
         .map((reg: IHookRegistry) => reg.getHooks(hookName))                  // Get named hooks from registries
         .filter(assertPredicate(isArray, `broken event named: ${hookName}`))  // Sanity check
-        .reduce(unnestR)                                                      // Un-nest IEventHook[][] to IEventHook[] array
-        .filter(matchFilter)                                                  // Only those satisfying matchCriteria
-        .sort(prioritySort);                                                  // Order them by .priority field
+        .reduce(unnestR, [])                                                  // Un-nest IEventHook[][] to IEventHook[] array
+        .filter(hook => hook.matches(treeChanges));                           // Only those satisfying matchCriteria
   }
 }
+
+interface HookTuple { hook: IEventHook, node: Node, transitionHook: TransitionHook }
+
+/**
+ * A factory for a sort function for HookTuples.
+ *
+ * The sort function first compares the Node depth (how deep in the state tree a node is), then compares
+ * the EventHook priority.
+ *
+ * @param reverseDepthSort a boolean, when true, reverses the sort order for the node depth
+ * @returns a tuple sort function
+ */
+function tupleSort(reverseDepthSort = false) {
+  return function nodeDepthThenPriority(l: HookTuple, r: HookTuple): number {
+    let factor = reverseDepthSort ? -1 : 1;
+    let depthDelta = (l.node.state.path.length - r.node.state.path.length) * factor;
+    return depthDelta !== 0 ? depthDelta : r.hook.priority - l.hook.priority;
+  }
+}

src/transition/hookRegistry.ts

@@ -1,30 +1,31 @@
 /** @module transition */ /** for typedoc */
-import {IInjectable, extend, removeFrom} from "../common/common";
+import {IInjectable, extend, removeFrom, anyTrueR, allTrueR, tail} from "../common/common";
 import {isString, isFunction} from "../common/predicates";
 import {val} from "../common/hof";
+import {Node} from "../path/node";
 
-import {IMatchCriteria, IStateMatch, IEventHook, IHookRegistry, IHookRegistration} from "./interface";
-
+import {IMatchCriteria, IStateMatch, IEventHook, IHookRegistry, IHookRegistration, TreeChanges, MatchCriterion, IMatchingNodes} from "./interface";
 import {Glob, State} from "../state/module";
 
 /**
  * Determines if the given state matches the matchCriteria
  * @param state a State Object to test against
- * @param matchCriteria {string|array|function}
+ * @param criterion
  * - If a string, matchState uses the string as a glob-matcher against the state name
  * - If an array (of strings), matchState uses each string in the array as a glob-matchers against the state name
  *   and returns a positive match if any of the globs match.
  * - If a function, matchState calls the function with the state and returns true if the function's result is truthy.
  * @returns {boolean}
  */
-export function matchState(state: State, matchCriteria: (string|IStateMatch)) {
-  let toMatch = isString(matchCriteria) ? [matchCriteria] : matchCriteria;
+export function matchState(state: State, criterion: MatchCriterion) {
+  let toMatch = isString(criterion) ? [criterion] : criterion;
 
   function matchGlobs(_state) {
-    for (let i = 0; i < toMatch.length; i++) {
-      let glob = Glob.fromString(toMatch[i]);
+    let globStrings = <string[]> toMatch;
+    for (let i = 0; i < globStrings.length; i++) {
+      let glob = Glob.fromString(globStrings[i]);
 
-      if ((glob && glob.matches(_state.name)) || (!glob && toMatch[i] === _state.name)) {
+      if ((glob && glob.matches(_state.name)) || (!glob && globStrings[i] === _state.name)) {
         return true;
       }
     }
@@ -41,14 +42,41 @@ export class EventHook implements IEventHook {
   matchCriteria: IMatchCriteria;
   priority: number;
 
-  constructor(matchCriteria: IMatchCriteria, callback: IInjectable, options: { priority: number } = <any>{}) {
+  constructor(matchCriteria: IMatchCriteria, callback: IInjectable, options: { priority?: number } = <any>{}) {
     this.callback = callback;
-    this.matchCriteria = extend({to: val(true), from: val(true)}, matchCriteria);
+    this.matchCriteria = extend({ to: true, from: true, exiting: true, retained: true, entering: true }, matchCriteria);
     this.priority = options.priority || 0;
   }
 
-  matches(to: State, from: State) {
-    return <boolean> matchState(to, this.matchCriteria.to) && matchState(from, this.matchCriteria.from);
+  private static _matchingNodes(nodes: Node[], criterion: MatchCriterion): Node[] {
+    if (criterion === true) return nodes;
+    let matching = nodes.filter(node => matchState(node.state, criterion));
+    return matching.length ? matching : null;
+  }
+
+  /**
+   * Determines if this hook's [[matchCriteria]] match the given [[TreeChanges]]
+   *
+   * @returns an IMatchingNodes object, or null. If an IMatchingNodes object is returned, its values
+   * are the matching [[Node]]s for each [[MatchCriterion]] (to, from, exiting, retained, entering)
+   */
+  matches(treeChanges: TreeChanges): IMatchingNodes {
+    let mc = this.matchCriteria, _matchingNodes = EventHook._matchingNodes;
+
+    let matches = {
+      to: _matchingNodes([tail(treeChanges.to)], mc.to),
+      from: _matchingNodes([tail(treeChanges.from)], mc.from),
+      exiting: _matchingNodes(treeChanges.exiting, mc.exiting),
+      retained: _matchingNodes(treeChanges.retained, mc.retained),
+      entering: _matchingNodes(treeChanges.entering, mc.entering),
+    };
+
+    // Check if all the criteria matched the TreeChanges object
+    let allMatched: boolean = ["to", "from", "exiting", "retained", "entering"]
+        .map(prop => matches[prop])
+        .reduce(allTrueR, true);
+
+    return allMatched ? matches : null;
   }
 }
 

src/transition/interface.ts

@@ -576,9 +576,10 @@ export type IStateMatch = Predicate<State>
  * This object is used to configure whether or not a Transition Hook is invoked for a particular transition,
  * based on the Transition's "to state" and "from state".
  *
- * The `to` and `from` can be state globs, or a function that takes a state.
- * Both `to` and `from` are optional.  If one of these is omitted, it is replaced with the
- * function: `function() { return true; }`, which effectively matches any state.
+ * Each property (`to`, `from`, `exiting`, `retained`, and `entering`) can be state globs, a function that takes a
+ * state, or a boolean (see [[MatchCriterion]])
+ *
+ * All properties are optional.  If any property is omitted, it is replaced with the value `true`, and always matches.
  *
  * @example
  * ```js
@@ -620,24 +621,47 @@ export type IStateMatch = Predicate<State>
  *   }
  * }
  * ```
+ *
+ * @example
+ * ```js
+ *
+ * // This matches a transition that is exiting `parent.child`
+ * var match = {
+ *   exiting: 'parent.child'
+ * }
+ * ```
  */
 export interface IMatchCriteria {
-  /**
-   * A glob string that matches the 'to' state's name.
-   * Or, a function with the signature `function(state) {}` which should return a boolean to indicate if the state matches.
-   */
-  to?: (string|IStateMatch);
+  /** A [[MatchCriterion]] to match the destination state */
+  to?: MatchCriterion;
+  /** A [[MatchCriterion]] to match the original (from) state */
+  from?: MatchCriterion;
+  /** A [[MatchCriterion]] to match any state that would be exiting */
+  exiting?: MatchCriterion;
+  /** A [[MatchCriterion]] to match any state that would be retained */
+  retained?: MatchCriterion;
+  /** A [[MatchCriterion]] to match any state that would be entering */
+  entering?: MatchCriterion;
+}
 
-  /**
-   *  A glob string that matches the 'from' state's name.
-   *  Or, a function with the signature `function(State) { return boolean; }` which should return a boolean to
-   *  indicate if the state matches.
-   */
-  from?: (string|IStateMatch);
+export interface IMatchingNodes {
+  to: Node[];
+  from: Node[];
+  exiting: Node[];
+  retained: Node[];
+  entering: Node[];
 }
 
+/**
+ * A glob string that matches the name of a state
+ * Or, a function with the signature `function(state) { return matches; }`
+ * which should return a boolean to indicate if a state matches.
+ * Or, `true` to match anything
+ */
+export type MatchCriterion = (string|IStateMatch|boolean)
+
 export interface IEventHook {
   callback: IInjectable;
   priority: number;
-  matches:  (a: State, b: State) => boolean;
+  matches:  (treeChanges: TreeChanges) => IMatchingNodes;
 }