| 11 | "import { ParamType } from './paramType';\n\n/**\n * Parameter values\n *\n * An object containing state parameter key/value pairs\n *\n * #### Example:\n * ```js\n * {\n * userId: 353474,\n * folderId: 'inbox'\n * }\n * ```\n */\nexport interface RawParams {\n [key: string]: any;\n}\n\n/**\n * Configuration for a single Parameter\n *\n * In a [[StateDeclaration.params]], each `ParamDeclaration`\n * defines how a single State Parameter should work.\n *\n * #### Example:\n * ```js\n * var mystate = {\n * template: '<div ui-view/>',\n * controller: function() {}\n * url: '/mystate/:start?{count:int}',\n * params: {\n * start: { // <-- ParamDeclaration for `start`\n * type: 'date',\n * value: new Date(), // <-- Default value\n * squash: true,\n * },\n *\n * nonUrlParam: { // <-- ParamDeclaration for 'nonUrlParam'\n * type: \"int\",\n * array: true,\n * value: []\n * },\n *\n * count: 0, // <-- Default value for 'param1'\n * // (shorthand ParamDeclaration.value)\n * }\n * }\n * ```\n */\nexport interface ParamDeclaration {\n /**\n * The default value for this parameter.\n *\n * Specifies the default value for this parameter.\n * This implicitly sets this parameter as optional.\n *\n * When UI-Router routes to a state and no value is specified for this parameter in the URL or transition,\n * the default value will be used instead.\n * If value is a function, it will be injected and invoked, and the return value used.\n *\n * Note: `value: undefined` is treated as though **no default value was specified**, while `value: null` is treated\n * as **\"the default value is null\"**.\n *\n * ```\n * // define default values for param1 and param2\n * params: {\n * param1: {\n * value: \"defaultValue\"\n * },\n * param2: {\n * value: \"param2Default;\n * }\n * }\n * ```\n *\n * ### Shorthand Declaration\n *\n * If you only want to set the default value of the parameter, you may use a shorthand syntax.\n * In the params map, instead mapping the param name to a full parameter configuration object, simply set map it\n * to the default parameter value, e.g.:\n * ```\n * // Normal (non-shorthand) default value syntax\n * params: {\n * param1: {\n * value: \"defaultValue\"\n * },\n * param2: {\n * value: \"param2Default\"\n * }\n * }\n *\n * // Shorthand default value syntax\n * params: {\n * param1: \"defaultValue\",\n * param2: \"param2Default\"\n * }\n * ```\n *\n * This defines a default value for the parameter.\n * If a parameter value is `undefined`, this default value will be used instead\n *\n * ---\n *\n * Default: `undefined`\n */\n value?: any;\n\n /**\n * The parameter's type\n *\n * Specifies the [[ParamType]] of the parameter.\n * Parameter types can be used to customize the encoding/decoding of parameter values.\n *\n * Set this property to the name of parameter's type.\n * The type may be either one of the built in types, or a custom type that has been registered with the [[UrlMatcherFactory]].\n *\n * See [[ParamTypes]] for the list of built in types.\n *\n * ---\n *\n * Default:\n * - Path parameters (`/:fooParam`): `path`\n * - Query parameters (`?queryParam`): `query`\n * - Non-url parameters (`param: { foo: null }`): `any`\n *\n */\n type?: string | ParamType;\n\n /**\n * The parameter's `array` mode\n *\n * Explicitly specifies the array mode of a URL parameter\n *\n * - If `false`, the parameter value will be treated (encoded/decoded) as a single value\n * - If `true`, the parameter value will be treated (encoded/decoded) as an array of values.\n * - If `auto` (for query parameters only), if multiple values for a single parameter are present\n * in the URL (e.g.: /foo?bar=1&bar=2&bar=3) then the values are mapped to an array (e.g.:\n * `{ foo: [ '1', '2', '3' ] }`). However, if only one value is present (e.g.: /foo?bar=1)\n * then the value is treated as single value (e.g.: { foo: '1' }).\n *\n * If you specified a [[type]] for the parameter, the value will be treated as an array\n * of the specified [[ParamType]].\n *\n * #### Example:\n * ```js\n * {\n * name: 'foo',\n * url: '/foo/{arrayParam:int}`,\n * params: {\n * arrayParam: { array: true }\n * }\n * }\n *\n * // After the transition, URL should be '/foo/1-2-3'\n * $state.go(\"foo\", { arrayParam: [ 1, 2, 3 ] });\n * ```\n *\n * @default `false` for path parameters, such as `url: '/foo/:pathParam'`\n * @default `auto` for query parameters, such as `url: '/foo?queryParam'`\n * @default `true` if the parameter name ends in `[]`, such as `url: '/foo/{implicitArrayParam:int[]}'`\n */\n array?: boolean;\n\n /**\n * Squash mode: omit default parameter values in URL\n *\n * Configures how a default parameter value is represented in the URL when the current parameter value\n * is the same as the default value.\n *\n * There are three squash settings:\n *\n * - `false`: The parameter's default value is not squashed. It is encoded and included in the URL\n * - `true`: The parameter's default value is omitted from the URL.\n * If the parameter is preceeded and followed by slashes in the state's url declaration, then one of those slashes are omitted.\n * This can allow for cleaner looking URLs.\n * - `\"<arbitrary string>\"`: The parameter's default value is replaced with an arbitrary\n * placeholder of your choice.\n *\n * #### Example:\n * ```js\n * {\n * name: 'mystate',\n * url: '/mystate/:myparam',\n * params: {\n * myparam: 'defaultParamValue'\n * squash: true\n * }\n * }\n *\n * // URL will be `/mystate/`\n * $state.go('mystate', { myparam: 'defaultParamValue' });\n *\n * // URL will be `/mystate/someOtherValue`\n * $state.go('mystate', { myparam: 'someOtherValue' });\n * ```\n *\n * #### Example:\n * ```js\n * {\n * name: 'mystate2',\n * url: '/mystate2/:myparam2',\n * params: {\n * myparam2: 'defaultParamValue'\n * squash: \"~\"\n * }\n * }\n *\n * // URL will be `/mystate/~`\n * $state.go('mystate', { myparam2: 'defaultParamValue' });\n *\n * // URL will be `/mystate/someOtherValue`\n * $state.go('mystate', { myparam2: 'someOtherValue' });\n * ```\n *\n * Default: If squash is not set, it uses the configured default squash policy. (See [[defaultSquashPolicy]]())\n */\n squash?: boolean | string;\n\n /**\n * @internal\n *\n * An array of [[Replace]] objects.\n *\n * When creating a Transition, defines how to handle certain special values, such as `undefined`, `null`,\n * or empty string `\"\"`. If the transition is started, and the parameter value is equal to one of the \"to\"\n * values, then the parameter value is replaced with the \"from\" value.\n *\n * #### Example:\n * ```js\n * replace: [\n * { from: undefined, to: null },\n * { from: \"\", to: null }\n * ]\n * ```\n */\n replace?: Replace[];\n\n /**\n * @internal\n * @internal\n *\n * This is not part of the declaration; it is a calculated value depending on if a default value was specified or not.\n */\n isOptional?: boolean;\n\n /**\n * Dynamic flag\n *\n * When `dynamic` is `true`, changes to the parameter value will not cause the state to be entered/exited.\n * The resolves will not be re-fetched, nor will views be reloaded.\n *\n * Normally, if a parameter value changes, the state which declared that the parameter will be reloaded (entered/exited).\n * When a parameter is `dynamic`, a transition still occurs, but it does not cause the state to exit/enter.\n *\n * This can be useful to build UI where the component updates itself when the param values change.\n * A common scenario where this is useful is searching/paging/sorting.\n *\n * ---\n *\n * Note: this value overrides the `dynamic` value on a custom parameter type ([[ParamTypeDefinition.dynamic]]).\n *\n * ---\n *\n * Default: `false`\n */\n dynamic?: boolean;\n\n /**\n * Disables url-encoding of parameter values\n *\n * When `true`, parameter values are not url-encoded.\n * This is commonly used to allow \"slug\" urls, with a parameter value including non-semantic slashes.\n *\n * #### Example:\n * ```js\n * url: '/product/:slug',\n * params: {\n * slug: { type: 'string', raw: true }\n * }\n * ```\n *\n * This allows a URL parameter of `{ slug: 'camping/tents/awesome_tent' }`\n * to serialize to `/product/camping/tents/awesome_tent`\n * instead of `/product/camping%2Ftents%2Fawesome_tent`.\n *\n * ---\n *\n * Note: this value overrides the `raw` value on a custom parameter type ([[ParamTypeDefinition.raw]]).\n *\n * ### Decoding warning\n *\n * The decoding behavior of raw parameters is not defined.\n * For example, given a url template such as `/:raw1/:raw2`\n * the url `/foo/bar/baz/qux/`, there is no way to determine which slashes belong to which params.\n *\n * It's generally safe to use a raw parameter at the end of a path, like '/product/:slug'.\n * However, beware of the characters you allow in your raw parameter values.\n * Avoid unencoded characters that could disrupt normal URL parsing, such as `?` and `#`.\n *\n * ---\n *\n * Default: `false`\n */\n raw?: boolean;\n\n /**\n * Enables/disables inheriting of this parameter's value\n *\n * When a transition is run with [[TransitionOptions.inherit]] set to\n * `true`, the current param values are inherited in the new transition.\n * However, parameters values which have `inherit: false` set will *not be inherited*.\n *\n * #### Example state :\n * ```js\n * var fooState = {\n * name: 'foo',\n * url: '/:fooId?mode&refresh',\n * params: {\n * refresh: { inherit: false }\n * }\n * }\n *\n * // Set fooId to 123\n * $state.go('fooState', { fooId: 1234, mode: 'list', refresh: true });\n * ```\n *\n * In the component:\n * `mode: 'list' is inherited, but refresh: true is not inherited.\n * // The param values are thus: `{ fooId: 4567, mode: 'list' }`\n * ```\n * <ui-sref=\"foo({ fooId: 4567 })\">4567</ui-sref>\n * ```\n *\n * ---\n *\n * See also [[TransitionOptions.inherit]] and [[ParamTypeDefinition.inherit]]\n *\n * ---\n *\n * Default: `true`\n */\n inherit?: boolean;\n}\n\n/**\n * String replacement\n *\n * Represents an exact match string replacement.\n *\n * Note: `to` or `from` may be null or undefined, and will be tested using `===`.\n */\nexport interface Replace {\n /**\n * The value to replace.\n *\n * May be `null` or `undefined`.\n * The entire value must match using `===`.\n * When found, the [[to]] value is used instead.\n */\n from: string;\n\n /**\n * The new value\n *\n * Used instead of the [[from]] value.\n */\n to: string;\n}\n\n/**\n * Describes a custom [[ParamType]]\n *\n * See: [[UrlMatcherFactory.type]]\n *\n * A developer can create a custom parameter type definition to customize the encoding and decoding of parameter values.\n * The definition should implement all the methods of this interface.\n *\n * Parameter values are parsed from the URL as strings.\n * However, it is often useful to parse the string into some other form, such as:\n *\n * - integer\n * - date\n * - array of <integer/date/string>\n * - custom object\n * - some internal string representation\n *\n * Typed parameter definitions control how parameter values are encoded (to the URL) and decoded (from the URL).\n * UI-Router always provides the decoded parameter values to the user (from methods such as [[Transition.params]])).\n *\n * For example, if a state has a url of `/foo/{fooId:int}` (the `fooId` parameter is of the `int` ParamType)\n * and if the browser is at `/foo/123`, then the 123 is parsed as an integer:\n *\n * ```js\n * var fooId = transition.params().fooId;\n * fooId === \"123\" // false\n * fooId === 123 // true\n * ```\n *\n *\n * #### Examples\n *\n * This example encodes an array of integers as a dash-delimited string to be used in the URL.\n *\n * If we call `$state.go('foo', { fooIds: [20, 30, 40] });`, the URL changes to `/foo/20-30-40`.\n * If we navigate to `/foo/1-2-3`, the `foo` state's onEnter logs `[1, 2, 3]`.\n *\n * @example\n * ```\n *\n * $urlMatcherFactoryProvider.type('intarray', {\n * // Take an array of ints [1,2,3] and return a string \"1-2-3\"\n * encode: (array) => array.join(\"-\"),\n *\n * // Take an string \"1-2-3\" and return an array of ints [1,2,3]\n * decode: (str) => str.split(\"-\").map(x => parseInt(x, 10)),\n *\n * // Match the encoded string in the URL\n * pattern: new RegExp(\"[0-9]+(?:-[0-9]+)*\")\n *\n * // Ensure that the (decoded) object is an array, and that all its elements are numbers\n * is: (obj) => Array.isArray(obj) &&\n * obj.reduce((acc, item) => acc && typeof item === 'number', true),\n *\n * // Compare two arrays of integers\n * equals: (array1, array2) => array1.length === array2.length &&\n * array1.reduce((acc, item, idx) => acc && item === array2[idx], true);\n * });\n *\n * $stateProvider.state('foo', {\n * url: \"/foo/{fooIds:intarray}\",\n * onEnter: function($transition$) {\n * console.log($transition$.fooIds); // Logs \"[1, 2, 3]\"\n * }\n * });\n * ```\n *\n *\n * This example decodes an integer from the URL.\n * It uses the integer as an index to look up an item from a static list.\n * That item from the list is the decoded parameter value.\n *\n * @example\n * ```\n *\n * var list = ['John', 'Paul', 'George', 'Ringo'];\n *\n * $urlMatcherFactoryProvider.type('listItem', {\n * encode: function(item) {\n * // Represent the list item in the URL using its corresponding index\n * return list.indexOf(item);\n * },\n * decode: function(item) {\n * // Look up the list item by index\n * return list[parseInt(item, 10)];\n * },\n * is: function(item) {\n * // Ensure the item is valid by checking to see that it appears\n * // in the list\n * return list.indexOf(item) > -1;\n * }\n * });\n *\n * $stateProvider.state('list', {\n * url: \"/list/{item:listItem}\",\n * controller: function($scope, $stateParams) {\n * console.log($stateParams.item);\n * }\n * });\n *\n * // ...\n *\n * // Changes URL to '/list/3', logs \"Ringo\" to the console\n * $state.go('list', { item: \"Ringo\" });\n * ```\n *\n * See: [[UrlConfig.type]]\n */\nexport interface ParamTypeDefinition {\n /**\n * A regular expression that matches the encoded parameter type\n *\n * This regular expression is used to match an encoded parameter value **in the URL**.\n *\n * For example, if your type encodes as a dash-separated numbers, match that here:\n * `new RegExp(\"[0-9]+(?:-[0-9]+)*\")`.\n *\n * There are some limitations to these regexps:\n *\n * - No capturing groups are allowed (use non-capturing groups: `(?: )`)\n * - No pattern modifiers like case insensitive\n * - No start-of-string or end-of-string: `/^foo$/`\n */\n pattern?: RegExp;\n\n /**\n * Disables url-encoding of parameter values\n *\n * If a parameter type is declared `raw`, it will not be url-encoded.\n * Custom encoding can still be applied in the [[encode]] function.\n *\n * ### Decoding warning\n *\n * The decoding behavior of raw parameters is not defined.\n * See: [[ParamDeclaration.raw]] for details\n */\n raw?: boolean;\n\n /**\n * Enables/disables inheriting of parameter values (of this type)\n *\n * When a transition is run with [[TransitionOptions.inherit]] set to\n * `true`, the current param values are inherited in the new transition.\n * However, parameters whose type has `inherit: false` set will *not be inherited*.\n *\n * The internal parameter type of `hash` has `inherit: false`.\n * This is used to disable inheriting of the hash value (`#`) on subsequent transitions.\n *\n * #### Example:\n * ```js\n * $state.go('home', { '#': 'inboxAnchor' });\n * ...\n * // \"#\" is not inherited.\n * // The value of the \"#\" parameter will be `null`\n * // The url's hash will be cleared.\n * $state.go('home.nest');\n * ```\n *\n * ---\n *\n * See also [[TransitionOptions.inherit]] and [[ParamDeclaration.inherit]]\n *\n */\n inherit?: boolean;\n\n /**\n * Dynamic flag\n *\n * When `dynamic` is `true`, changes to the parameter value will not cause the state to be entered/exited.\n *\n * Normally, if a parameter value changes, the state which declared that the parameter will be reloaded (entered/exited).\n * When a parameter is `dynamic`, a transition still occurs, but it does not cause the state to exit/enter.\n *\n * Default: `false`\n */\n dynamic?: boolean;\n\n /**\n * Tests if some object type is compatible with this parameter type\n *\n * Detects whether some value is of this particular type.\n * Accepts a decoded value and determines whether it matches this `ParamType` object.\n *\n * If your custom type encodes the parameter to a specific type, check for that type here.\n * For example, if your custom type decodes the URL parameter value as an array of ints, return true if the\n * input is an array of ints:\n *\n * ```\n * is: (val) => Array.isArray(val) && array.reduce((acc, x) => acc && parseInt(val, 10) === val, true)\n * ```\n *\n * If your type decodes the URL parameter value to a custom string, check that the string matches\n * the pattern (don't use an arrow fn if you need `this`): `function (val) { return !!this.pattern.exec(val) }`\n *\n * Note: This method is _not used to check if the URL matches_.\n * It's used to check if a _decoded value *is* this type_.\n * Use [[pattern]] to check the encoded value in the URL.\n *\n * @param val The value to check.\n * @param key If the type check is happening in the context of a specific [[UrlMatcher]] object,\n * this is the name of the parameter in which `val` is stored. Can be used for\n * meta-programming of `ParamType` objects.\n * @returns `true` if the value matches the type, otherwise `false`.\n */\n is(val: any, key?: string): boolean;\n\n /**\n * Encodes a custom/native type value to a string that can be embedded in a URL.\n *\n * Note that the return value does *not* need to be URL-safe (i.e. passed through `encodeURIComponent()`).\n * It only needs to be a representation of `val` that has been encoded as a string.\n *\n * For example, if your custom type decodes to an array of ints, then encode the array of ints to a string here:\n *\n * ```js\n * encode: (intarray) => intarray.join(\"-\")\n * ```\n *\n * Note: in general, [[encode]] and [[decode]] should be symmetrical. That is, `encode(decode(str)) === str`\n *\n * @param val The value to encode.\n * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.\n * @returns a string representation of `val` that can be encoded in a URL.\n */\n encode(val: any, key?: string): string | string[];\n\n /**\n * Decodes a parameter value string (from URL string or transition param) to a custom/native value.\n *\n * For example, if your type decodes to an array of ints, then decode the string as an array of ints here:\n * ```js\n * decode: (str) => str.split(\"-\").map(str => parseInt(str, 10))\n * ```\n *\n * Note: in general, [[encode]] and [[decode]] should be symmetrical. That is, `encode(decode(str)) === str`\n *\n * @param val The URL parameter value to decode.\n * @param key The name of the parameter in which `val` is stored. Can be used for meta-programming of `ParamType` objects.\n * @returns a custom representation of the URL parameter value.\n */\n decode(val: string, key?: string): any;\n\n /**\n * Determines whether two decoded values are equivalent.\n *\n * For example, if your type decodes to an array of ints, then check if the arrays are equal:\n * ```js\n * equals: (a, b) => a.length === b.length && a.reduce((acc, x, idx) => acc && x === b[idx], true)\n * ```\n *\n * @param a A value to compare against.\n * @param b A value to compare against.\n * @returns `true` if the values are equivalent/equal, otherwise `false`.\n */\n equals(a: any, b: any): boolean;\n}\n"
|