Skip to content

Commit 745d91f

Browse files
docs(Type): typedocify
1 parent b7754c6 commit 745d91f

File tree

4 files changed

+135
-222
lines changed

4 files changed

+135
-222
lines changed

src/params/interface.ts

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -219,3 +219,52 @@ interface Replace {
219219
from: string,
220220
to:string
221221
}
222+
223+
224+
/**
225+
* Defines the behavior of a custom [[Type]].
226+
* See: [[UrlMatcherFactory.type]]
227+
*/
228+
export interface TypeDefinition {
229+
/**
230+
* Detects whether a value is of a particular type. Accepts a native (decoded) value
231+
* and determines whether it matches the current `Type` object.
232+
*
233+
* @param val The value to check.
234+
* @param key If the type check is happening in the context of a specific [[UrlMatcher]] object,
235+
* this is the name of the parameter in which `val` is stored. Can be used for
236+
* meta-programming of `Type` objects.
237+
* @returns `true` if the value matches the type, otherwise `false`.
238+
*/
239+
is(val: any, key?: string): boolean;
240+
241+
/**
242+
* Encodes a custom/native type value to a string that can be embedded in a URL. Note that the
243+
* return value does *not* need to be URL-safe (i.e. passed through `encodeURIComponent()`), it
244+
* only needs to be a representation of `val` that has been coerced to a string.
245+
*
246+
* @param val The value to encode.
247+
* @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
248+
* @returns a string representation of `val` that can be encoded in a URL.
249+
*/
250+
encode(val: any, key?: string): (string|string[]);
251+
252+
/**
253+
* Converts a parameter value (from URL string or transition param) to a custom/native value.
254+
*
255+
* @param val The URL parameter value to decode.
256+
* @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
257+
* @returns a custom representation of the URL parameter value.
258+
*/
259+
decode(val: string, key?: string): any;
260+
261+
/**
262+
* Determines whether two decoded values are equivalent.
263+
*
264+
* @param a A value to compare against.
265+
* @param b A value to compare against.
266+
* @returns `true` if the values are equivalent/equal, otherwise `false`.
267+
*/
268+
equals(a: any, b: any): boolean;
269+
}
270+

src/params/type.ts

Lines changed: 23 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
/** @module params */ /** for typedoc */
22
import {extend, isArray, isDefined, filter, map} from "../common/common";
3+
import {TypeDefinition} from "./interface";
34

45
/**
56
* Wraps up a `Type` object to handle array values.
@@ -51,114 +52,49 @@ function ArrayType(type, mode) {
5152
}
5253

5354
/**
54-
* @ngdoc object
55-
* @name ui.router.util.type:Type
56-
*
57-
* @description
5855
* Implements an interface to define custom parameter types that can be decoded from and encoded to
59-
* string parameters matched in a URL. Used by {@link ui.router.util.type:UrlMatcher `UrlMatcher`}
56+
* string parameters matched in a URL. Used by [[UrlMatcher]]
6057
* objects when matching or formatting URLs, or comparing or validating parameter values.
6158
*
62-
* See {@link ui.router.util.$urlMatcherFactory#methods_type `$urlMatcherFactory#type()`} for more
63-
* information on registering custom types.
59+
* See [[UrlMatcherFactory.type]] for more information on registering custom types.
6460
*
65-
* @param {Object} config A configuration object which contains the custom type definition. The object's
66-
* properties will override the default methods and/or pattern in `Type`'s public interface.
6761
* @example
68-
* <pre>
62+
* ```
63+
*
6964
* {
7065
* decode: function(val) { return parseInt(val, 10); },
7166
* encode: function(val) { return val && val.toString(); },
7267
* equals: function(a, b) { return this.is(a) && a === b; },
73-
* is: function(val) { return angular.isNumber(val) isFinite(val) && val % 1 === 0; },
68+
* is: function(val) { return angular.isNumber(val) && isFinite(val) && val % 1 === 0; },
7469
* pattern: /\d+/
7570
* }
76-
* </pre>
77-
*
78-
* @property {RegExp} pattern The regular expression pattern used to match values of this type when
79-
* coming from a substring of a URL.
80-
*
81-
* @returns {Object} Returns a new `Type` object.
71+
* ```
8272
*/
83-
export class Type {
73+
export class Type implements TypeDefinition {
8474
pattern: RegExp = /.*/;
8575
name: string;
8676
raw: boolean;
8777

88-
constructor(config) {
89-
extend(this, config);
90-
}
91-
9278
/**
93-
* @ngdoc function
94-
* @name ui.router.util.type:Type#is
95-
* @methodOf ui.router.util.type:Type
96-
*
97-
* @description
98-
* Detects whether a value is of a particular type. Accepts a native (decoded) value
99-
* and determines whether it matches the current `Type` object.
100-
*
101-
* @param {*} val The value to check.
102-
* @param {string} key Optional. If the type check is happening in the context of a specific
103-
* {@link ui.router.util.type:UrlMatcher `UrlMatcher`} object, this is the name of the
104-
* parameter in which `val` is stored. Can be used for meta-programming of `Type` objects.
105-
* @returns {Boolean} Returns `true` if the value matches the type, otherwise `false`.
79+
* @param def A configuration object which contains the custom type definition. The object's
80+
* properties will override the default methods and/or pattern in `Type`'s public interface.
81+
* @returns a new Type object
10682
*/
107-
is(val, key?) {
108-
return true;
83+
constructor(def: TypeDefinition) {
84+
extend(this, def);
10985
}
11086

111-
/**
112-
* @ngdoc function
113-
* @name ui.router.util.type:Type#encode
114-
* @methodOf ui.router.util.type:Type
115-
*
116-
* @description
117-
* Encodes a custom/native type value to a string that can be embedded in a URL. Note that the
118-
* return value does *not* need to be URL-safe (i.e. passed through `encodeURIComponent()`), it
119-
* only needs to be a representation of `val` that has been coerced to a string.
120-
*
121-
* @param {*} val The value to encode.
122-
* @param {string} key The name of the parameter in which `val` is stored. Can be used for
123-
* meta-programming of `Type` objects.
124-
* @returns {string} Returns a string representation of `val` that can be encoded in a URL.
125-
*/
126-
encode(val, key?): (string|string[]) {
127-
return val;
128-
}
12987

130-
/**
131-
* @ngdoc function
132-
* @name ui.router.util.type:Type#decode
133-
* @methodOf ui.router.util.type:Type
134-
*
135-
* @description
136-
* Converts a parameter value (from URL string or transition param) to a custom/native value.
137-
*
138-
* @param {string} val The URL parameter value to decode.
139-
* @param {string} key The name of the parameter in which `val` is stored. Can be used for
140-
* meta-programming of `Type` objects.
141-
* @returns {*} Returns a custom representation of the URL parameter value.
142-
*/
143-
decode(val, key?) {
144-
return val;
145-
}
88+
// consider these four methods to be "abstract methods" that should be overridden
89+
/** @inheritdoc */
90+
is(val: any, key?: string): boolean { return true; }
91+
/** @inheritdoc */
92+
encode(val: any, key?: string): (string|string[]) { return val; }
93+
/** @inheritdoc */
94+
decode(val: string, key?: string): any { return val; }
95+
/** @inheritdoc */
96+
equals(a: any, b: any): boolean { return a == b; }
14697

147-
/**
148-
* @ngdoc function
149-
* @name ui.router.util.type:Type#equals
150-
* @methodOf ui.router.util.type:Type
151-
*
152-
* @description
153-
* Determines whether two decoded values are equivalent.
154-
*
155-
* @param {*} a A value to compare against.
156-
* @param {*} b A value to compare against.
157-
* @returns {Boolean} Returns `true` if the values are equivalent/equal, otherwise `false`.
158-
*/
159-
equals(a, b) {
160-
return a == b;
161-
}
16298

16399
$subPattern() {
164100
var sub = this.pattern.toString();
@@ -174,7 +110,7 @@ export class Type {
174110
return this.is(val) ? val : this.decode(val);
175111
}
176112

177-
/*
113+
/**
178114
* Wraps an existing custom Type as an array of Type, depending on 'mode'.
179115
* e.g.:
180116
* - urlmatcher pattern "/path?{queryParam[]:int}"

src/transition/transitionHook.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ import {IInjectable, defaults, extend, noop, filter, not, isFunction, isDefined,
55
eq, is, isPromise, isObject, parse, fnToString, maxLength, Predicate} from "../common/common";
66
import {runtime, trace} from "../common/module";
77

8-
import {Transition, RejectFactory, TransitionRejection} from "./module";
8+
import {Transition} from "./transition";
9+
import {TransitionRejection, RejectFactory} from "./rejectFactory";
910
import {State} from "../state/module";
1011
import {Resolvable, ResolveContext} from "../resolve/module";
1112

0 commit comments

Comments
 (0)