refactor(Transition): Finish refactor APIs to use Path and TargetState

 - Transition factory and constructor now take a TargetState
 - Split invalid target logic between TargetState.exists() and Transition.valid()
   - Cannot create a Transition to a state which doesn't exist
   - Can create (but cannot run) a Transition object to an abstract state, or with invalid params
feat(ParamValues): now uses constructor function which takes a Path.
 - It exposes the path as ES5 $$path getter
 - It exposes $byState() function to retrieve params per
refactor(Transition): Moved tree changes functionality to PathFactory
refactor($state): Moved inheritParams functionality to PathFactory

Author: christopherthielen

src/params/interface.ts

@@ -1,6 +1,6 @@
- // Without importing something, TSC complains that this file isn't a module
-import {noop} from "../common/common"; 
+import ParamValues from "./paramValues";
 
 export interface IRawParams {
-	[key: string]: any
-}
+    [key: string]: any
+}
+export type IParamsOrArray = (IRawParams|IRawParams[]|ParamValues);

src/params/paramValues.ts

@@ -2,33 +2,32 @@ import {IParamsPath, IParamsNode} from "../path/interface"
 import {IState} from "../state/interface"
 import {IRawParams} from "../params/interface"
 
-import {extend, inherit} from "../common/common"
-/** 
- * This class calculates parameter values from a IParamsPath.  The param values for the path
- * are available directly on the resulting object.  Param values for a specific state in the
- * path may be retrieved using the $byState(stateName) function.  
+import {extend, inherit, find, pairs, prop, zipObject} from "../common/common"
+/**
+ * This class closes over a Path and encapsulates the parameter values from the Path's Nodes.
+ * The param values for the path are flattened and copied to the resulting ParamValues object.  
+ * Param values for a specific state are exposed with the $byState(stateName) function.
  */
+const stateNameMatches = (stateName: string) => (node) => node.state.name === stateName;
+
 export default class ParamValues implements IRawParams {
     [key: string]: any
-    
-    constructor(private _byState) {}
-    
-    $byState(stateName: string) {
-        return this._byState[stateName]; 
+    private $$path: IParamsPath;
+
+
+    constructor($$path: IParamsPath) {
+        Object.defineProperty(this, "$$path", { value: $$path });
+        $$path.nodes().reduce((memo, node) => extend(memo, node.ownParams), this);
     }
-    
-    static paramsByState(path: IParamsPath): IRawParams {
-        const byState = (memo, node: IParamsNode) => { 
-            memo[node.state.name] = node.ownParams; 
-            return memo; 
-        };
-        return path.nodes().reduce(byState, {});
+
+    /** Gets the param values for a given state (by state name) */
+    $byState(stateName: string) {
+        let found = find(this.$$path.nodes(), stateNameMatches(stateName));
+        return found && found.ownParams;
     }
 
-    static fromPath(path: IParamsPath): ParamValues {
-        let $byState = ParamValues.paramsByState(path);
-        let params = inherit(new ParamValues($byState), {});
-        const extendParams = (memo, node: IParamsNode) => extend(memo, node.ownParams);
-        return path.nodes().reduce(extendParams, params);
+    /** Returns a new ParamValues object which closes over a subpath of this ParamValue's Path. */
+    $isolateRootTo(stateName: string): ParamValues {
+        return new ParamValues(this.$$path.pathFromRootTo(stateName));
     }
-}
+}

src/path/interface.ts

@@ -1,26 +1,46 @@
+
+import Path from "./../path/path";
+
 import {IState} from "../state/interface";
+
 import {IRawParams} from "../params/interface";
+import ParamValues from "../params/paramValues";
+
 import {IResolvables} from "../resolve/interface";
-import Path from "./../path/path";
+import ResolveContext from "../resolve/resolveContext";
+
 
 /** Base data (contains a state) for a node in a Path */
 export interface INode {
   state: IState
 }
+/** A basic Path. Each node contains an IState */
+export interface IPath extends Path<INode> {}
 
-/** Data, including raw params values, for a node in a Path */
+
+/** Contains INode base data plus raw params values for the node */
 export interface IParamsNode extends INode { 
   ownParams: IRawParams
 }
+/** A Path of IParamsNode(s) */
+export interface IParamsPath extends Path<IParamsNode> {}
 
-/** Transition Data for a node in a Path (either to path or from path) */
+
+/** Contains IParamsNode data, plus Resolvables for the node */
 export interface IResolveNode extends IParamsNode {
   ownResolvables: IResolvables
 }
+/** A Path of IResolveNode(s) */
+export interface IResolvePath extends Path<IResolveNode> {}
 
-/** A basic Path. Each node contains the data necessary for a Transition to work. */
-export interface IPath extends Path<INode> {}
-/** A Params Path. Each node contains raw params data for each state */
-export interface IParamsPath extends Path<IParamsNode> {}
-/** A Transition Path. Each node contains the data necessary for a Transition to work. */
-export interface IResolvePath extends Path<IResolveNode> { }
+
+/** Contains IResolveNode data, plus a ResolveContext and ParamsValues (bound to a full path) for the node,  */
+export interface ITransNode extends IResolveNode {
+  resolveContext: ResolveContext,
+  paramValues: ParamValues
+}
+/**
+ * A Path of ITransNode(s). Each node contains raw param values, Resolvables and also a ResolveContext
+ * and ParamValues which are bound to the overall path, but isolated to the node.
+ */
+export interface ITransPath extends Path<ITransNode> {}

src/path/path.ts

@@ -1,19 +1,23 @@
 /// <reference path='../../typings/angularjs/angular.d.ts' />
-import {extend, isArray, identity, noop,
+
+import {extend, isArray, isString, identity, noop, Predicate,
     defaults, map, omit, pluck, find, pipe, prop, eq}  from "../common/common";
 import trace  from "../common/trace";
 import {runtime} from "../common/angular1"
 import {IPromise} from "angular";
 
 import {INode, IParamsNode, IParamsPath} from "./interface";
 
-import {IState} from "../state/interface";
-
+import {IState, IStateDeclaration, IStateOrName} from "../state/interface";
 import TargetState from "../state/targetState"
 
 import {IResolvables} from "../resolve/interface";
 import Resolvable from "../resolve/resolvable";
 
+const stateMatches = (state: IState|IStateDeclaration) => (node) => node.state === state || node.state.self === state;
+const stateNameMatches = (stateName: string) => (node) => node.state.name === stateName;
+const shallowNodeCopy = node => extend({}, node);
+
 /**
  * A Path Object represents a Path of nested States within the State Hierarchy. 
  * Each node of the path holds the IState object, and additional data, according
@@ -27,40 +31,62 @@ import Resolvable from "../resolve/resolvable";
 export default class Path<NODE extends INode> {
   constructor(private _nodes: NODE[]) { }
 
-  // returns a subpath of this path from the root path element up to and including the toPathElement parameter
-  pathFromRootTo(toState: IState): Path<NODE> {
-    var first = this._nodes.filter((node) => node.state === toState);
-    var elementIdx = this._nodes.indexOf(first[0]);
+  /**
+   * returns a subpath of this path from the root path element up to and including the toState parameter.
+   * Each node of the subpath is a shallow copy of the original node.
+   *
+   * @param toState A state or name of a state
+   */
+  pathFromRootTo(toState: IStateOrName): Path<NODE> {
+    let predicate = isString(toState) ? stateNameMatches(<string> toState) : stateMatches(<IState> toState);
+    var node = find(this._nodes, predicate);
+    var elementIdx = this._nodes.indexOf(node);
     if (elementIdx == -1) throw new Error("This Path does not contain the toPathElement");
     return this.slice(0, elementIdx + 1);
   }
 
+  /**
+   * Returns a new Path which contains this Path's nodes, concatenated with another Path's nodes.
+   * Each node of the concatenated Path is a shallow copy of the original nodes.
+   */
   concat(path: Path<NODE>): Path<NODE> {
-    return new Path(this._nodes.concat(path._nodes));
+    return new Path(this._nodes.concat(path._nodes).map(shallowNodeCopy));
   }
 
+  /**
+   * Returns a new Path which is a subpath of this Path.  The new Path contains nodes starting from "start" and
+   * ending at "end".  Each node of the subpath is a shallow copy of the original Path's node.
+   */
   slice(start: number, end?: number): Path<NODE> {
-    return new Path(this._nodes.slice(start, end));
+    return new Path(this._nodes.slice(start, end).map(shallowNodeCopy));
   }
 
+  /**
+   * Returns a new Path which is a copy of this Path, but with nodes in reverse order.
+   * Each node in the reversed path is a shallow copy of the original Path's node.
+   */
   reverse(): Path<NODE> {
-    let copy = [].concat(this._nodes);
+    let copy = [].concat(this._nodes).map(shallowNodeCopy);
     copy.reverse();
-    return new Path(copy)
+    return new Path(copy);
   }
 
+  /** Returns the "state" property of each node in this Path */
   states(): IState[] {
     return this._nodes.map(prop("state"));
   }
 
-  elementForState(state: IState): NODE {
+  /** Gets the first node that exactly matches the given state */
+  nodeForState(state: IState): NODE {
     return find(this._nodes, pipe(prop('state'), eq(state)));
   }
-  
+
+  /** Returns the Path's nodes wrapped in a new array */
   nodes(): NODE[] {
     return [].concat(this._nodes);
   }
 
+  /** Returns the last node in the Path  */
   last(): NODE {
     return this._nodes.length ? this._nodes[this._nodes.length - 1] : null;
   }