docs(Type): typedocify

Author: christopherthielen

src/params/interface.ts

@@ -219,3 +219,52 @@ interface Replace {
   from: string,
   to:string
 }
+
+
+/**
+ * Defines the behavior of a custom [[Type]].
+ * See: [[UrlMatcherFactory.type]]
+ */
+export interface TypeDefinition {
+  /**
+   * Detects whether a value is of a particular type. Accepts a native (decoded) value
+   * and determines whether it matches the current `Type` object.
+   *
+   * @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.
+   * @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.
+   *
+   * @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.
+   * @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.
+   *
+   * @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.
+   * @returns a custom representation of the URL parameter value.
+   */
+  decode(val: string, key?: string): any;
+
+  /**
+   * Determines whether two decoded values are equivalent.
+   *
+   * @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;
+}
+

src/params/type.ts

@@ -1,5 +1,6 @@
 /** @module params */ /** for typedoc */
 import {extend, isArray, isDefined, filter, map} from "../common/common";
+import {TypeDefinition} from "./interface";
 
 /**
  * Wraps up a `Type` object to handle array values.
@@ -51,114 +52,49 @@ function ArrayType(type, mode) {
 }
 
 /**
- * @ngdoc object
- * @name ui.router.util.type:Type
- *
- * @description
  * Implements an interface to define custom parameter types that can be decoded from and encoded to
- * string parameters matched in a URL. Used by {@link ui.router.util.type:UrlMatcher `UrlMatcher`}
+ * string parameters matched in a URL. Used by [[UrlMatcher]]
  * objects when matching or formatting URLs, or comparing or validating parameter values.
  *
- * See {@link ui.router.util.$urlMatcherFactory#methods_type `$urlMatcherFactory#type()`} for more
- * information on registering custom types.
+ * See [[UrlMatcherFactory.type]] for more information on registering custom types.
  *
- * @param {Object} config  A configuration object which contains the custom type definition.  The object's
- *        properties will override the default methods and/or pattern in `Type`'s public interface.
  * @example
- * <pre>
+ * ```
+ *
  * {
  *   decode: function(val) { return parseInt(val, 10); },
  *   encode: function(val) { return val && val.toString(); },
  *   equals: function(a, b) { return this.is(a) && a === b; },
- *   is: function(val) { return angular.isNumber(val) isFinite(val) && val % 1 === 0; },
+ *   is: function(val) { return angular.isNumber(val) && isFinite(val) && val % 1 === 0; },
  *   pattern: /\d+/
  * }
- * </pre>
- *
- * @property {RegExp} pattern The regular expression pattern used to match values of this type when
- *           coming from a substring of a URL.
- *
- * @returns {Object}  Returns a new `Type` object.
+ * ```
  */
-export class Type {
+export class Type implements TypeDefinition {
   pattern: RegExp = /.*/;
   name: string;
   raw: boolean;
 
-  constructor(config) {
-    extend(this, config);
-  }
-
   /**
-   * @ngdoc function
-   * @name ui.router.util.type:Type#is
-   * @methodOf ui.router.util.type:Type
-   *
-   * @description
-   * Detects whether a value is of a particular type. Accepts a native (decoded) value
-   * and determines whether it matches the current `Type` object.
-   *
-   * @param {*} val  The value to check.
-   * @param {string} key  Optional. If the type check is happening in the context of a specific
-   *        {@link ui.router.util.type:UrlMatcher `UrlMatcher`} object, this is the name of the
-   *        parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
-   * @returns {Boolean}  Returns `true` if the value matches the type, otherwise `false`.
+   * @param def  A configuration object which contains the custom type definition.  The object's
+   *        properties will override the default methods and/or pattern in `Type`'s public interface.
+   * @returns a new Type object
    */
-  is(val, key?) {
-    return true;
+  constructor(def: TypeDefinition) {
+    extend(this, def);
   }
 
-  /**
-   * @ngdoc function
-   * @name ui.router.util.type:Type#encode
-   * @methodOf ui.router.util.type:Type
-   *
-   * @description
-   * 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.
-   *
-   * @param {*} val  The value to encode.
-   * @param {string} key  The name of the parameter in which `val` is stored. Can be used for
-   *        meta-programming of `Type` objects.
-   * @returns {string}  Returns a string representation of `val` that can be encoded in a URL.
-   */
-  encode(val, key?): (string|string[]) {
-    return val;
-  }
 
-  /**
-   * @ngdoc function
-   * @name ui.router.util.type:Type#decode
-   * @methodOf ui.router.util.type:Type
-   *
-   * @description
-   * Converts a parameter value (from URL string or transition param) to a custom/native value.
-   *
-   * @param {string} val  The URL parameter value to decode.
-   * @param {string} key  The name of the parameter in which `val` is stored. Can be used for
-   *        meta-programming of `Type` objects.
-   * @returns {*}  Returns a custom representation of the URL parameter value.
-   */
-  decode(val, key?) {
-    return val;
-  }
+  // consider these four methods to be "abstract methods" that should be overridden
+  /** @inheritdoc */
+  is(val: any, key?: string): boolean { return true; }
+  /** @inheritdoc */
+  encode(val: any, key?: string): (string|string[]) { return val; }
+  /** @inheritdoc */
+  decode(val: string, key?: string): any { return val; }
+  /** @inheritdoc */
+  equals(a: any, b: any): boolean { return a == b; }
 
-  /**
-   * @ngdoc function
-   * @name ui.router.util.type:Type#equals
-   * @methodOf ui.router.util.type:Type
-   *
-   * @description
-   * Determines whether two decoded values are equivalent.
-   *
-   * @param {*} a  A value to compare against.
-   * @param {*} b  A value to compare against.
-   * @returns {Boolean}  Returns `true` if the values are equivalent/equal, otherwise `false`.
-   */
-  equals(a, b) {
-    return a == b;
-  }
 
   $subPattern() {
     var sub = this.pattern.toString();
@@ -174,7 +110,7 @@ export class Type {
     return this.is(val) ? val : this.decode(val);
   }
 
-  /*
+  /**
    * Wraps an existing custom Type as an array of Type, depending on 'mode'.
    * e.g.:
    * - urlmatcher pattern "/path?{queryParam[]:int}"

src/transition/transitionHook.ts

@@ -5,7 +5,8 @@ import {IInjectable, defaults, extend, noop, filter, not, isFunction, isDefined,
     eq, is, isPromise, isObject, parse, fnToString, maxLength, Predicate} from "../common/common";
 import {runtime, trace} from "../common/module";
 
-import {Transition, RejectFactory, TransitionRejection} from "./module";
+import {Transition} from "./transition";
+import {TransitionRejection, RejectFactory} from "./rejectFactory";
 import {State} from "../state/module";
 import {Resolvable, ResolveContext} from "../resolve/module";