feat(Transition): Make Transition.params() immutable to avoid confusion about mutability

refactor(params): rename type.ts to paramtype.ts

Author: christopherthielen

src/params/index.ts

@@ -11,4 +11,4 @@ export * from "./interface";
 export * from "./param";
 export * from "./paramTypes";
 export * from "./stateParams";
-export * from "./type";
+export * from "./paramType";

src/params/interface.ts

@@ -3,7 +3,7 @@
  * @module params
  */ /** for typedoc */
 
-import {ParamType} from "./type";
+import {ParamType} from "./paramType";
 
 /**
  * Parameter values
@@ -110,6 +110,10 @@ export interface ParamDeclaration {
    *
    * This defines a default value for the parameter.
    * If a parameter value is `undefined`, this default value will be used instead
+   *
+   * ---
+   *
+   * Default: `undefined`
    */
   value?: any;
 
@@ -123,6 +127,14 @@ export interface ParamDeclaration {
    * The type may be either one of the built in types, or a custom type that has been registered with the [[UrlMatcherFactory]].
    *
    * See [[ParamTypes]] for the list of built in types.
+   *
+   * ---
+   *
+   * Default:
+   * - Path parameters (`/:fooParam`): `path`
+   * - Query parameters (`?queryParam`): `query`
+   * - Non-url parameters (`param: { foo: null }`): `any`
+   *
    */
   type: (string|ParamType);
 
@@ -212,7 +224,7 @@ export interface ParamDeclaration {
    * $state.go('mystate', { myparam2: 'someOtherValue' });
    * ```
    *
-   * If squash is not set, it uses the configured default squash policy. (See [[defaultSquashPolicy]]())
+   * Default: If squash is not set, it uses the configured default squash policy. (See [[defaultSquashPolicy]]())
    */
   squash: (boolean|string);
 
@@ -258,6 +270,10 @@ export interface ParamDeclaration {
    * ---
    *
    * Note: this value overrides the `dynamic` value on a custom parameter type ([[ParamTypeDefinition.dynamic]]).
+   *
+   * ---
+   *
+   * Default: `false`
    */
   dynamic: boolean;
 
@@ -292,8 +308,45 @@ export interface ParamDeclaration {
    * It's generally safe to use a raw parameter at the end of a path, like '/product/:slug'.
    * However, beware of the characters you allow in your raw parameter values.
    * Avoid unencoded characters that could disrupt normal URL parsing, such as `?` and `#`.
+   *
+   * ---
+   *
+   * Default: `false`
    */
   raw: boolean;
+
+  /**
+   * Enables/disables inheriting of this parameter value
+   *
+   * When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited.
+   * Parameters values which have `inherit: false` will not be inherited.
+   *
+   * #### Example state :
+   * ```js
+   * var fooState = {
+   *   name: 'foo',
+   *   url: '/:fooId?mode&refresh',
+   *   params: {
+   *     refresh: { inherit: false }
+   *   }
+   * }
+   *
+   * // Set fooId to 123
+   * $state.go('fooState', { fooId: 1234, mode: 'list', refresh: true });
+   * ```
+   *
+   * In the component:
+   * `mode: 'list' is inherited, but refresh: true is not inherited.
+   * // The param values are thus: `{ fooId: 4567, mode: 'list' }`
+   * ```
+   * <ui-sref="foo({ fooId: 4567 })">4567</ui-sref>
+   * ```
+   *
+   * ---
+   *
+   * Default: `true`
+   */
+  inherit: boolean;
 }
 
 /** @internalapi */
@@ -520,5 +573,26 @@ export interface ParamTypeDefinition {
    * See: [[ParamDeclaration.raw]] for details
    */
   raw: boolean;
+
+  /**
+   * Enables/disables inheriting of parameter values (of this type)
+   *
+   * When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited.
+   * Param values whose type has `inherit: false` will not be inherited.
+   *
+   * The internal parameter type of `hash` has `inherit: false`.
+   * This is used to disable inheriting of the hash value (`#`) on subsequent transitions.
+   *
+   * #### Example:
+   * ```js
+   * $state.go('home', { '#': 'inboxAnchor' });
+   * ...
+   * // "#" is not inherited.
+   * // The value of the "#" parameter will be `null`
+   * // The url's hash will be cleared.
+   * $state.go('home.nest');
+   * ```
+   */
+  inherit: boolean;
 }
 

src/params/param.ts

@@ -7,7 +7,7 @@ import { prop, propEq } from "../common/hof";
 import { isInjectable, isDefined, isString, isArray } from "../common/predicates";
 import { RawParams, ParamDeclaration } from "../params/interface";
 import { services } from "../common/coreservices";
-import { ParamType } from "./type";
+import { ParamType } from "./paramType";
 import { ParamTypes } from "./paramTypes";
 import { UrlMatcherFactory } from "../url/urlMatcherFactory";
 

src/params/type.ts renamed to src/params/paramType.ts

@@ -6,7 +6,7 @@ import { fromJson, toJson, identity, equals, inherit, map, extend, pick } from "
 import { isDefined, isNullOrUndefined } from "../common/predicates";
 import { is } from "../common/hof";
 import { services } from "../common/coreservices";
-import { ParamType } from "./type";
+import { ParamType } from "./paramType";
 import { ParamTypeDefinition } from "./interface";
 
 /**

src/params/paramTypes.ts

@@ -250,6 +250,7 @@ export class Transition implements IHookRegistry {
    * Gets transition parameter values
    *
    * Returns the parameter values for a transition as key/value pairs.
+   * This object is immutable.
    *
    * By default, returns the new parameter values (for the "to state").
    * To return the previous parameter values,  supply `'from'` as the `pathname` argument.
@@ -262,7 +263,7 @@ export class Transition implements IHookRegistry {
   params(pathname?: string): any;
   params<T>(pathname?: string): T;
   params(pathname: string = "to") {
-    return this._treeChanges[pathname].map(prop("paramValues")).reduce(mergeR, {});
+    return Object.freeze(this._treeChanges[pathname].map(prop("paramValues")).reduce(mergeR, {}));
   }
 
 

src/transition/transition.ts

@@ -8,7 +8,7 @@
  * @module url
  */ /** */
 import { LocationConfig } from "../common/coreservices";
-import { ParamType } from "../params/type";
+import { ParamType } from "../params/paramType";
 import { Param } from "../params/param";
 import { UIRouter } from "../router";
 import { TargetState } from "../state/targetState";

src/url/interface.ts

@@ -9,7 +9,7 @@ import { Param, DefType } from "../params/param";
 import { ParamTypes } from "../params/paramTypes";
 import { ParamTypeDefinition } from "../params/interface";
 import { Disposable } from "../interface";
-import { ParamType } from "../params/type";
+import { ParamType } from "../params/paramType";
 import { ParamFactory, UrlMatcherConfig } from "./interface";
 
 /**