doc(ParamType): Add better docs for Custom Parameter Types

refactor(Type): rename Type to ParamType

Author: christopherthielen

src/params/interface.ts

@@ -1,5 +1,5 @@
 /** @module params */ /** for typedoc */
-import {Type} from "./type";
+import {ParamType} from "./type";
 
 export interface RawParams {
   [key: string]: any;
@@ -86,12 +86,12 @@ export interface ParamDeclaration {
   /**
    * A property of [[ParamDeclaration]]:
    *
-   * Specifies the [[Type]] of the parameter.
+   * Specifies the [[ParamType]] of the parameter.
    *
    * Set this property to the name of parameter's type.   The type may be either one of the
    * built in types, or a custom type that has been registered with the [[$urlMatcherFactory]]
    */
-  type: (string|Type);
+  type: (string|ParamType);
 
   /**
    * A property of [[ParamDeclaration]]:
@@ -106,7 +106,7 @@ export interface ParamDeclaration {
    * then the value is treated as single value (e.g.: { foo: '1' }).
    *
    * If you specified a [[type]] for the parameter, the value will be treated as an array
-   * of the specified Type.
+   * of the specified [[ParamType]].
    *
    * @example
    * ```
@@ -221,49 +221,195 @@ export interface Replace {
 
 
 /**
- * Defines the behavior of a custom [[Type]].
+ * Definition for a custom [[ParamType]]
+ *
+ * A developer can create a custom parameter type definition to customize the encoding and decoding of parameter values.
+ * The definition should implement all the methods of this interface.
+ *
+ * Parameter values are parsed from the URL as strings.
+ * However, it is often useful to parse the string into some other form, such as:
+ *
+ * - integer
+ * - date
+ * - array of <integer/date/string>
+ * - custom object
+ * - some custom string representation
+ *
+ * Typed parameter definitions control how parameter values are encoded (to the URL) and decoded (from the URL).
+ * UI-Router always provides the decoded parameter values to the user from methods such as [[Transition.params]].
+ *
+ *
+ * For example, if a state has a url of `/foo/{fooId:int}` (the `fooId` parameter is of the `int` ParamType)
+ * and if the browser is at `/foo/123`, then the 123 is parsed as an integer:
+ *
+ * ```js
+ * var fooId = transition.params().fooId;
+ * fooId === "123" // false
+ * fooId === 123 // true
+ * ```
+ *
+ *
+ * #### Examples
+ *
+ * This example encodes an array of integers as a dash-delimited string to be used in the URL.
+ *
+ * If we call `$state.go('foo', { fooIds: [20, 30, 40] });`, the URL changes to `/foo/20-30-40`.
+ * If we navigate to `/foo/1-2-3`, the `foo` state's onEnter logs `[1, 2, 3]`.
+ *
+ * @example
+ * ```
+ *
+ * $urlMatcherFactoryProvider.type('intarray', {
+ *   // Take an array of ints [1,2,3] and return a string "1-2-3"
+ *   encode: (array) => array.join("-"),
+ *
+ *   // Take an string "1-2-3" and return an array of ints [1,2,3]
+ *   decode: (str) => str.split("-").map(x => parseInt(x, 10)),
+ *
+ *   // Match the encoded string in the URL
+ *   pattern: new RegExp("[0-9]+(?:-[0-9]+)*")
+ *
+ *   // Ensure that the (decoded) object is an array, and that all its elements are numbers
+ *   is: (obj) => Array.isArray(obj) &&
+ *       obj.reduce((acc, item) => acc && typeof item === 'number', true),
+ *
+ *   // Compare two arrays of integers
+ *   equals: (array1, array2) => array1.length === array2.length &&
+ *       array1.reduce((acc, item, idx) => acc && item === array2[idx], true);
+ * });
+ *
+ * $stateProvider.state('foo', {
+ *   url: "/foo/{fooIds:intarray}",
+ *   onEnter: function($transition$) {
+ *     console.log($transition$.fooIds); // Logs "[1, 2, 3]"
+ *   }
+ * });
+ * ```
+ *
+ *
+ * This example decodes an integer from the URL.
+ * It uses the integer as an index to look up an item from a static list.
+ * That item from the list is the decoded parameter value.
+ *
+ * @example
+ * ```
+ *
+ * var list = ['John', 'Paul', 'George', 'Ringo'];
+ *
+ * $urlMatcherFactoryProvider.type('listItem', {
+ *   encode: function(item) {
+ *     // Represent the list item in the URL using its corresponding index
+ *     return list.indexOf(item);
+ *   },
+ *   decode: function(item) {
+ *     // Look up the list item by index
+ *     return list[parseInt(item, 10)];
+ *   },
+ *   is: function(item) {
+ *     // Ensure the item is valid by checking to see that it appears
+ *     // in the list
+ *     return list.indexOf(item) > -1;
+ *   }
+ * });
+ *
+ * $stateProvider.state('list', {
+ *   url: "/list/{item:listItem}",
+ *   controller: function($scope, $stateParams) {
+ *     console.log($stateParams.item);
+ *   }
+ * });
+ *
+ * // ...
+ *
+ * // Changes URL to '/list/3', logs "Ringo" to the console
+ * $state.go('list', { item: "Ringo" });
+ * ```
+ * 
  * See: [[UrlMatcherFactory.type]]
  */
-export interface TypeDefinition {
+export interface ParamTypeDefinition {
   /**
-   * Detects whether a value is of a particular type. Accepts a native (decoded) value
-   * and determines whether it matches the current `Type` object.
+   * Tests if some object type is compatible with this parameter type
+   * 
+   * Detects whether some value is of this particular type. 
+   * Accepts a decoded value and determines whether it matches this `ParamType` object.
+   *
+   * If your custom type encodes the parameter to a specific type, check for that type here.
+   * For example, if your custom type decodes the URL parameter value as an array of ints, return true if the
+   * input is an array of ints:
+   * `(val) => Array.isArray(val) && array.reduce((acc, x) => acc && parseInt(val, 10) === val, true)`.
+   * If your type decodes the URL parameter value to a custom string, check that the string matches
+   * the pattern (don't use an arrow fn if you need `this`): `function (val) { return !!this.pattern.exec(val) }`
+   *
+   * Note: This method is _not used to check if the URL matches_.
+   * It's used to check if a _decoded value is this type_.
+   * Use [[pattern]] to check the URL.
    *
    * @param val The value to check.
    * @param key If the type check is happening in the context of a specific [[UrlMatcher]]  object,
    *        this is the name of the parameter in which `val` is stored. Can be used for
-   *        meta-programming of `Type` objects.
+   *        meta-programming of `ParamType` objects.
    * @returns `true` if the value matches the type, otherwise `false`.
    */
   is(val: any, key?: string): boolean;
 
   /**
-   * Encodes a custom/native type value to a string that can be embedded in a URL. Note that the
-   * return value does *not* need to be URL-safe (i.e. passed through `encodeURIComponent()`), it
-   * only needs to be a representation of `val` that has been coerced to a string.
+   * Encodes a custom/native type value to a string that can be embedded in a URL.
+   *
+   * Note that the return value does *not* need to be URL-safe (i.e. passed through `encodeURIComponent()`), it
+   * only needs to be a representation of `val` that has been encoded as a string.
+   *
+   * For example, if your type decodes to an array of ints, then encode the array of ints as a string here:
+   * `(intarray) => intarray.join("-")`
+   *
+   * Note: in general, [[encode]] and [[decode]] should be symmetrical.  That is, `encode(decode(str)) === str`
    *
    * @param val The value to encode.
-   * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
+   * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.
    * @returns a string representation of `val` that can be encoded in a URL.
    */
   encode(val: any, key?: string): (string|string[]);
 
   /**
-   * Converts a parameter value (from URL string or transition param) to a custom/native value.
+   * Decodes a parameter value string (from URL string or transition param) to a custom/native value.
+   *
+   * For example, if your type decodes to an array of ints, then decode the string as an array of ints here:
+   * `(str) => str.split("-").map(str => parseInt(str, 10))`
+   *
+   * Note: in general, [[encode]] and [[decode]] should be symmetrical.  That is, `encode(decode(str)) === str`
    *
    * @param val The URL parameter value to decode.
-   * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
+   * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.
    * @returns a custom representation of the URL parameter value.
    */
   decode(val: string, key?: string): any;
 
   /**
    * Determines whether two decoded values are equivalent.
    *
+   * For example, if your type decodes to an array of ints, then check if the arrays are equal:
+   * `(a, b) => a.length === b.length && a.reduce((acc, x, idx) => acc && x === b[idx], true)`
+   *
    * @param a A value to compare against.
    * @param b A value to compare against.
    * @returns `true` if the values are equivalent/equal, otherwise `false`.
    */
   equals(a: any, b: any): boolean;
+
+  /**
+   * A regular expression that matches the encoded parameter type
+   *
+   * This regular expression is used to match the parameter type in the URL.
+   *
+   * For example, if your type encodes as a dash-separated numbers, match that here:
+   * `new RegExp("[0-9]+(?:-[0-9]+)*")`.
+   *
+   * There are some limitations to these regexps:
+   *
+   * - No capturing groups are allowed (use non-capturing groups: `(?: )`)
+   * - No pattern modifiers like case insensitive
+   * - No start-of-string or end-of-string: `/^foo$/`
+   */
+  pattern: RegExp;
 }
 

src/params/param.ts

@@ -5,7 +5,7 @@ import {isInjectable, isDefined, isString, isArray} from "../common/predicates";
 import {RawParams} from "../params/interface";
 import {services} from "../common/coreservices";
 import {matcherConfig} from "../url/urlMatcherConfig";
-import {Type} from "./type";
+import {ParamType} from "./type";
 import {paramTypes} from "./paramTypes";
 
 let hasOwn = Object.prototype.hasOwnProperty;
@@ -28,7 +28,7 @@ function getType(cfg, urlType, location, id) {
   if (cfg.type && urlType && urlType.name === 'string' && paramTypes.type(cfg.type)) return paramTypes.type(cfg.type);
   if (urlType) return urlType;
   if (!cfg.type) return (location === DefType.CONFIG ? paramTypes.type("any") : paramTypes.type("string"));
-  return cfg.type instanceof Type ? cfg.type : paramTypes.type(cfg.type);
+  return cfg.type instanceof ParamType ? cfg.type : paramTypes.type(cfg.type);
 }
 
 /**
@@ -56,7 +56,7 @@ function getReplace(config, arrayMode, isOptional, squash) {
 
 export class Param {
   id: string;
-  type: Type;
+  type: ParamType;
   location: DefType;
   array: boolean;
   squash: (boolean|string);
@@ -65,13 +65,13 @@ export class Param {
   dynamic: boolean;
   config: any;
 
-  constructor(id: string, type: Type, config: any, location: DefType) {
+  constructor(id: string, type: ParamType, config: any, location: DefType) {
     config = unwrapShorthand(config);
     type = getType(config, type, location, id);
     let arrayMode = getArrayMode();
     type = arrayMode ? type.$asArray(arrayMode, location === DefType.SEARCH) : type;
     let isOptional = config.value !== undefined;
-    let dynamic = config.dynamic === true;
+    let dynamic = isDefined(config.dynamic) ? !!config.dynamic : !!type.dynamic;
     let squash = getSquashPolicy(config, isOptional);
     let replace = getReplace(config, arrayMode, isOptional, squash);
 
@@ -101,7 +101,7 @@ export class Param {
       if (!services.$injector) throw new Error("Injectable functions cannot be called at configuration time");
       let defaultValue = services.$injector.invoke(this.config.$$fn);
       if (defaultValue !== null && defaultValue !== undefined && !this.type.is(defaultValue))
-        throw new Error(`Default value (${defaultValue}) for parameter '${this.id}' is not an instance of Type (${this.type.name})`);
+        throw new Error(`Default value (${defaultValue}) for parameter '${this.id}' is not an instance of ParamType (${this.type.name})`);
       return defaultValue;
     };
 
@@ -122,11 +122,11 @@ export class Param {
     // There was no parameter value, but the param is optional
     if ((!isDefined(value) || value === null) && this.isOptional) return true;
 
-    // The value was not of the correct Type, and could not be decoded to the correct Type
+    // The value was not of the correct ParamType, and could not be decoded to the correct ParamType
     const normalized = this.type.$normalize(value);
     if (!this.type.is(normalized)) return false;
 
-    // The value was of the correct type, but when encoded, did not match the Type's regexp
+    // The value was of the correct type, but when encoded, did not match the ParamType's regexp
     const encoded = this.type.encode(normalized);
     return !(isString(encoded) && !this.type.pattern.exec(<string> encoded));
   }
@@ -136,17 +136,17 @@ export class Param {
   }
 
   /** Creates a new [[Param]] from a CONFIG block */
-  static fromConfig(id: string, type: Type, config: any): Param {
+  static fromConfig(id: string, type: ParamType, config: any): Param {
     return new Param(id, type, config, DefType.CONFIG);
   }
 
   /** Creates a new [[Param]] from a url PATH */
-  static fromPath(id: string, type: Type, config: any): Param {
+  static fromPath(id: string, type: ParamType, config: any): Param {
     return new Param(id, type, config, DefType.PATH);
   }
 
   /** Creates a new [[Param]] from a url SEARCH */
-  static fromSearch(id: string, type: Type, config: any): Param {
+  static fromSearch(id: string, type: ParamType, config: any): Param {
     return new Param(id, type, config, DefType.SEARCH);
   }
 

src/params/paramTypes.ts

@@ -3,7 +3,7 @@ import {fromJson, toJson, identity, equals, inherit, map, extend} from "../commo
 import {isDefined} from "../common/predicates";
 import {is, val} from "../common/hof";
 import {services} from "../common/coreservices";
-import {Type} from "./type";
+import {ParamType} from "./type";
 
 // Use tildes to pre-encode slashes.
 // If the slashes are simply URLEncoded, the browser can choose to pre-decode them,
@@ -81,15 +81,15 @@ export class ParamTypes {
 
   constructor() {
     // Register default types. Store them in the prototype of this.types.
-    const makeType = (definition, name) => new Type(extend({ name }, definition));
+    const makeType = (definition, name) => new ParamType(extend({ name }, definition));
     this.types = inherit(map(this.defaultTypes, makeType), {});
   }
 
   type(name, definition?: any, definitionFn?: Function) {
     if (!isDefined(definition)) return this.types[name];
     if (this.types.hasOwnProperty(name)) throw new Error(`A type named '${name}' has already been defined.`);
 
-    this.types[name] = new Type(extend({ name }, definition));
+    this.types[name] = new ParamType(extend({ name }, definition));
 
     if (definitionFn) {
       this.typeQueue.push({ name, def: definitionFn });