@angular-wave/angular.ts 0.9.1 → 0.9.3

package/@types/router/url/url-matcher.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Matches URLs against patterns.
+ *
+ * Matches URLs against patterns and extracts named parameters from the path or the search
+ * part of the URL.
+ *
+ * A URL pattern consists of a path pattern, optionally followed by '?' and a list of search (query)
+ * parameters. Multiple search parameter names are separated by '&'. Search parameters
+ * do not influence whether or not a URL is matched, but their values are passed through into
+ * the matched parameters returned by [[UrlMatcher.exec]].
+ *
+ * - *Path parameters* are defined using curly brace placeholders (`/somepath/{param}`)
+ * or colon placeholders (`/somePath/:param`).
+ *
+ * - *A parameter RegExp* may be defined for a param after a colon
+ * (`/somePath/{param:[a-zA-Z0-9]+}`) in a curly brace placeholder.
+ * The regexp must match for the url to be matched.
+ * Should the regexp itself contain curly braces, they must be in matched pairs or escaped with a backslash.
+ *
+ * Note: a RegExp parameter will encode its value using either [[ParamTypes.path]] or [[ParamTypes.query]].
+ *
+ * - *Custom parameter types* may also be specified after a colon (`/somePath/{param:int}`) in curly brace parameters.
+ *   See [[UrlMatcherFactory.type]] for more information.
+ *
+ * - *Catch-all parameters* are defined using an asterisk placeholder (`/somepath/*catchallparam`).
+ *   A catch-all * parameter value will contain the remainder of the URL.
+ *
+ * ---
+ *
+ * Parameter names may contain only word characters (latin letters, digits, and underscore) and
+ * must be unique within the pattern (across both path and search parameters).
+ * A path parameter matches any number of characters other than '/'. For catch-all
+ * placeholders the path parameter matches any number of characters.
+ *
+ * Examples:
+ *
+ * * `'/hello/'` - Matches only if the path is exactly '/hello/'. There is no special treatment for
+ *   trailing slashes, and patterns have to match the entire path, not just a prefix.
+ * * `'/user/:id'` - Matches '/user/bob' or '/user/1234!!!' or even '/user/' but not '/user' or
+ *   '/user/bob/details'. The second path segment will be captured as the parameter 'id'.
+ * * `'/user/{id}'` - Same as the previous example, but using curly brace syntax.
+ * * `'/user/{id:[^/]*}'` - Same as the previous example.
+ * * `'/user/{id:[0-9a-fA-F]{1,8}}'` - Similar to the previous example, but only matches if the id
+ *   parameter consists of 1 to 8 hex digits.
+ * * `'/files/{path:.*}'` - Matches any URL starting with '/files/' and captures the rest of the
+ *   path into the parameter 'path'.
+ * * `'/files/*path'` - ditto.
+ * * `'/calendar/{start:date}'` - Matches "/calendar/2014-11-12" (because the pattern defined
+ *   in the built-in  `date` ParamType matches `2014-11-12`) and provides a Date object in $stateParams.start
+ *
+ */
+export class UrlMatcher {
+  /** @internal Given a matcher, return an array with the matcher's path segments and path params, in order */
+  static pathSegmentsAndParams(matcher: any): any;
+  /** @internal Given a matcher, return an array with the matcher's query params */
+  static queryParams(matcher: any): any;
+  /**
+   * Compare two UrlMatchers
+   *
+   * This comparison function converts a UrlMatcher into static and dynamic path segments.
+   * Each static path segment is a static string between a path separator (slash character).
+   * Each dynamic segment is a path parameter.
+   *
+   * The comparison function sorts static segments before dynamic ones.
+   */
+  static compare(a: any, b: any): number;
+  /**
+   * @param pattern The pattern to compile into a matcher.
+   * @param paramTypes The [[ParamTypes]] registry
+   * @param paramFactory A [[ParamFactory]] object
+   * @param config  A [[UrlMatcherCompileConfig]] configuration object
+   */
+  constructor(pattern: any, paramTypes: any, paramFactory: any, config: any);
+  _cache: {
+    path: UrlMatcher[];
+  };
+  _children: any[];
+  _params: any[];
+  _segments: any[];
+  _compiled: any[];
+  config: any;
+  pattern: any;
+  /**
+   * Creates a new concatenated UrlMatcher
+   *
+   * Builds a new UrlMatcher by appending another UrlMatcher to this one.
+   *
+   * @param url A `UrlMatcher` instance to append as a child of the current `UrlMatcher`.
+   */
+  append(url: any): any;
+  isRoot(): boolean;
+  /** Returns the input pattern string */
+  toString(): any;
+  _getDecodedParamValue(value: any, param: any): any;
+  /**
+   * Tests the specified url/path against this matcher.
+   *
+   * Tests if the given url matches this matcher's pattern, and returns an object containing the captured
+   * parameter values.  Returns null if the path does not match.
+   *
+   * The returned object contains the values
+   * of any search parameters that are mentioned in the pattern, but their value may be null if
+   * they are not present in `search`. This means that search parameters are always treated
+   * as optional.
+   *
+   * #### Example:
+   * ```js
+   * new UrlMatcher('/user/{id}?q&r').exec('/user/bob', {
+   *   x: '1', q: 'hello'
+   * });
+   * // returns { id: 'bob', q: 'hello', r: null }
+   * ```
+   *
+   * @param path    The URL path to match, e.g. `$location.getPath()`.
+   * @param search  URL search parameters, e.g. `$location.getSearch()`.
+   * @param hash    URL hash e.g. `$location.getHash()`.
+   *
+   * @returns The captured parameter values.
+   */
+  exec(
+    path: any,
+    search: {},
+    hash: any,
+  ): {
+    "#": any;
+  };
+  /**
+   * @internal
+   * Returns all the [[Param]] objects of all path and search parameters of this pattern in order of appearance.
+   *
+   * @returns {Array.<Param>}  An array of [[Param]] objects. Must be treated as read-only. If the
+   *    pattern has no parameters, an empty array is returned.
+   */
+  parameters(opts?: {}): Array<Param>;
+  /**
+   * @internal
+   * Returns a single parameter from this UrlMatcher by id
+   *
+   * @param id
+   * @param opts
+   * @returns {Param|any|boolean|UrlMatcher|null}
+   */
+  parameter(id: any, opts?: {}): Param | any | boolean | UrlMatcher | null;
+  /**
+   * Validates the input parameter values against this UrlMatcher
+   *
+   * Checks an object hash of parameters to validate their correctness according to the parameter
+   * types of this `UrlMatcher`.
+   *
+   * @param params The object hash of parameters to validate.
+   * @returns Returns `true` if `params` validates, otherwise `false`.
+   */
+  validates(params: any): any;
+  /**
+   * Given a set of parameter values, creates a URL from this UrlMatcher.
+   *
+   * Creates a URL that matches this pattern by substituting the specified values
+   * for the path and search parameters.
+   *
+   * #### Example:
+   * ```js
+   * new UrlMatcher('/user/{id}?q').format({ id:'bob', q:'yes' });
+   * // returns '/user/bob?q=yes'
+   * ```
+   *
+   * @param values  the values to substitute for the parameters in this pattern.
+   * @returns the formatted URL (path and optionally search part).
+   */
+  format(values?: {}): string;
+}
+export namespace UrlMatcher {
+  let nameValidator: RegExp;
+}
+import { Param } from "../params/param.js";

package/@types/router/url/url-rule.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Creates a [[UrlRule]]
+ *
+ * Creates a [[UrlRule]] from a:
+ *
+ * - `string`
+ * - [[UrlMatcher]]
+ * - `RegExp`
+ * - [[StateObject]]
+ */
+export class UrlRuleFactory {
+  /**
+   * @param {import('../url/url-service.js').UrlService} urlService
+   * @param {import('../state/state-service.js').StateProvider} stateService
+   * @param {import('../router.js').Router} routerGlobals
+   */
+  constructor(
+    urlService: import("../url/url-service.js").UrlService,
+    stateService: import("../state/state-service.js").StateProvider,
+    routerGlobals: import("../router.js").Router,
+  );
+  urlService: import("../url/url-service.js").UrlService;
+  stateService: import("../state/state-service.js").StateProvider;
+  routerGlobals: import("../router.js").Router;
+  /**
+   *
+   * @param {*} what
+   * @param {*} handler
+   * @returns {BaseUrlRule}
+   */
+  create(what: any, handler: any): BaseUrlRule;
+  /**
+   * A UrlRule which matches based on a UrlMatcher
+   *
+   * The `handler` may be either a `string`, a [[UrlRuleHandlerFn]] or another [[UrlMatcher]]
+   *
+   * ## Handler as a function
+   *
+   * If `handler` is a function, the function is invoked with:
+   *
+   * - matched parameter values ([[RawParams]] from [[UrlMatcher.exec]])
+   * - url: the current Url ([[UrlParts]])
+   * - router: the router object ([[UIRouter]])
+   *
+   * #### Example:
+   * ```js
+   * var urlMatcher = $umf.compile("/foo/:fooId/:barId");
+   * var rule = factory.fromUrlMatcher(urlMatcher, match => "/home/" + match.fooId + "/" + match.barId);
+   * var match = rule.match('/foo/123/456'); // results in { fooId: '123', barId: '456' }
+   * var result = rule.handler(match); // '/home/123/456'
+   * ```
+   *
+   * ## Handler as UrlMatcher
+   *
+   * If `handler` is a UrlMatcher, the handler matcher is used to create the new url.
+   * The `handler` UrlMatcher is formatted using the matched param from the first matcher.
+   * The url is replaced with the result.
+   *
+   * #### Example:
+   * ```js
+   * var urlMatcher = $umf.compile("/foo/:fooId/:barId");
+   * var handler = $umf.compile("/home/:fooId/:barId");
+   * var rule = factory.fromUrlMatcher(urlMatcher, handler);
+   * var match = rule.match('/foo/123/456'); // results in { fooId: '123', barId: '456' }
+   * var result = rule.handler(match); // '/home/123/456'
+   * ```
+   */
+  fromUrlMatcher(
+    urlMatcher: any,
+    handler: any,
+  ): BaseUrlRule & {
+    urlMatcher: any;
+    matchPriority: (params: any) => number;
+    type: string;
+  };
+  /**
+   * A UrlRule which matches a state by its url
+   *
+   * #### Example:
+   * ```js
+   * var rule = factory.fromState($state.get('foo'), router);
+   * var match = rule.match('/foo/123/456'); // results in { fooId: '123', barId: '456' }
+   * var result = rule.handler(match);
+   * // Starts a transition to 'foo' with params: { fooId: '123', barId: '456' }
+   * ```
+   */
+  fromState(
+    stateOrDecl: any,
+    stateService: any,
+    globals: any,
+  ): BaseUrlRule & {
+    urlMatcher: any;
+    matchPriority: (params: any) => number;
+    type: string;
+  } & {
+    state: any;
+    type: string;
+  };
+  /**
+   * A UrlRule which matches based on a regular expression
+   *
+   * The `handler` may be either a [[UrlRuleHandlerFn]] or a string.
+   *
+   * ## Handler as a function
+   *
+   * If `handler` is a function, the function is invoked with:
+   *
+   * - regexp match array (from `regexp`)
+   * - url: the current Url ([[UrlParts]])
+   * - router: the router object ([[UIRouter]])
+   *
+   * #### Example:
+   * ```js
+   * var rule = factory.fromRegExp(/^\/foo\/(bar|baz)$/, match => "/home/" + match[1])
+   * var match = rule.match('/foo/bar'); // results in [ '/foo/bar', 'bar' ]
+   * var result = rule.handler(match); // '/home/bar'
+   * ```
+   *
+   * ## Handler as string
+   *
+   * If `handler` is a string, the url is *replaced by the string* when the Rule is invoked.
+   * The string is first interpolated using `string.replace()` style pattern.
+   *
+   * #### Example:
+   * ```js
+   * var rule = factory.fromRegExp(/^\/foo\/(bar|baz)$/, "/home/$1")
+   * var match = rule.match('/foo/bar'); // results in [ '/foo/bar', 'bar' ]
+   * var result = rule.handler(match); // '/home/bar'
+   * ```
+   */
+  fromRegExp(
+    regexp: any,
+    handler: any,
+  ): BaseUrlRule & {
+    regexp: any;
+    type: string;
+  };
+}
+export namespace UrlRuleFactory {
+  function isUrlRule(obj: any): boolean;
+}
+/**
+ * A base rule which calls `match`
+ *
+ * The value from the `match` function is passed through to the `handler`.
+ */
+export class BaseUrlRule {
+  constructor(match: any, handler: any);
+  match: any;
+  type: string;
+  $id: number;
+  _group: any;
+  handler: any;
+  priority: any;
+  /**
+   * This function should be overridden
+   * @param {*} [params]
+   * @returns {number}
+   */
+  matchPriority(params?: any): number;
+}

package/@types/router/url/url-rules.d.ts

@@ -0,0 +1,249 @@
+/**
+ * API for managing URL rules
+ *
+ * This API is used to create and manage URL rules.
+ * URL rules are a mechanism to respond to specific URL patterns.
+ *
+ * The most commonly used methods are [[otherwise]] and [[when]].
+ *
+ * This API is found at `$url.rules` (see: [[UIRouter.urlService]], [[URLService.rules]])
+ */
+export class UrlRules {
+  /** @param {UrlRuleFactory} urlRuleFactory */
+  constructor(urlRuleFactory: UrlRuleFactory);
+  _sortFn: typeof defaultRuleSortFn;
+  _rules: any[];
+  _id: number;
+  urlRuleFactory: UrlRuleFactory;
+  /**
+   * Defines the initial state, path, or behavior to use when the app starts.
+   *
+   * This rule defines the initial/starting state for the application.
+   *
+   * This rule is triggered the first time the URL is checked (when the app initially loads).
+   * The rule is triggered only when the url matches either `""` or `"/"`.
+   *
+   * Note: The rule is intended to be used when the root of the application is directly linked to.
+   * When the URL is *not* `""` or `"/"` and doesn't match other rules, the [[otherwise]] rule is triggered.
+   * This allows 404-like behavior when an unknown URL is deep-linked.
+   *
+   * #### Example:
+   * Start app at `home` state.
+   * ```js
+   * .initial({ state: 'home' });
+   * ```
+   *
+   * #### Example:
+   * Start app at `/home` (by url)
+   * ```js
+   * .initial('/home');
+   * ```
+   *
+   * #### Example:
+   * When no other url rule matches, go to `home` state
+   * ```js
+   * .initial((matchValue, url, router) => {
+   *   console.log('initial state');
+   *   return { state: 'home' };
+   * })
+   * ```
+   *
+   * @param handler The initial state or url path, or a function which returns the state or url path (or performs custom logic).
+   */
+  initial(handler: any): void;
+  /**
+   * Defines the state, url, or behavior to use when no other rule matches the URL.
+   *
+   * This rule is matched when *no other rule* matches.
+   * It is generally used to handle unknown URLs (similar to "404" behavior, but on the client side).
+   *
+   * - If `handler` a string, it is treated as a url redirect
+   *
+   * #### Example:
+   * When no other url rule matches, redirect to `/index`
+   * ```js
+   * .otherwise('/index');
+   * ```
+   *
+   * - If `handler` is an object with a `state` property, the state is activated.
+   *
+   * #### Example:
+   * When no other url rule matches, redirect to `home` and provide a `dashboard` parameter value.
+   * ```js
+   * .otherwise({ state: 'home', params: { dashboard: 'default' } });
+   * ```
+   *
+   * - If `handler` is a function, the function receives the current url ([[UrlParts]]) and the [[UIRouter]] object.
+   *   The function can perform actions, and/or return a value.
+   *
+   * #### Example:
+   * When no other url rule matches, manually trigger a transition to the `home` state
+   * ```js
+   * .otherwise((matchValue, urlParts, router) => {
+   *   router.stateService.go('home');
+   * });
+   * ```
+   *
+   * #### Example:
+   * When no other url rule matches, go to `home` state
+   * ```js
+   * .otherwise((matchValue, urlParts, router) => {
+   *   return { state: 'home' };
+   * });
+   * ```
+   *
+   * @param handler The url path to redirect to, or a function which returns the url path (or performs custom logic).
+   */
+  otherwise(handler: any): void;
+  _otherwiseFn: import("./url-rule.js").BaseUrlRule;
+  _sorted: boolean;
+  /**
+   * Remove a rule previously registered
+   *
+   * @param rule the matcher rule that was previously registered using [[rule]]
+   */
+  removeRule(rule: any): void;
+  /**
+   * Manually adds a URL Rule.
+   *
+   * Usually, a url rule is added using [[StateDeclaration.url]] or [[when]].
+   * This api can be used directly for more control (to register a [[BaseUrlRule]], for example).
+   * Rules can be created using [[urlRuleFactory]], or created manually as simple objects.
+   *
+   * A rule should have a `match` function which returns truthy if the rule matched.
+   * It should also have a `handler` function which is invoked if the rule is the best match.
+   *
+   * @return a function that deregisters the rule
+   */
+  rule(rule: any): () => void;
+  /**
+   * Gets all registered rules
+   *
+   * @returns an array of all the registered rules
+   */
+  rules(): any[];
+  /**
+   * Defines URL Rule priorities
+   *
+   * More than one rule ([[UrlRule]]) might match a given URL.
+   * This `compareFn` is used to sort the rules by priority.
+   * Higher priority rules should sort earlier.
+   *
+   * The [[defaultRuleSortFn]] is used by default.
+   *
+   * You only need to call this function once.
+   * The `compareFn` will be used to sort the rules as each is registered.
+   *
+   * If called without any parameter, it will re-sort the rules.
+   *
+   * ---
+   *
+   * Url rules may come from multiple sources: states's urls ([[StateDeclaration.url]]), [[when]], and [[rule]].
+   * Each rule has a (user-provided) [[UrlRule.priority]], a [[UrlRule.type]], and a [[UrlRule.$id]]
+   * The `$id` is is the order in which the rule was registered.
+   *
+   * The sort function should use these data, or data found on a specific type
+   * of [[UrlRule]] (such as [[StateRule.state]]), to order the rules as desired.
+   *
+   * #### Example:
+   * This compare function prioritizes rules by the order in which the rules were registered.
+   * A rule registered earlier has higher priority.
+   *
+   * ```js
+   * function compareFn(a, b) {
+   *   return a.$id - b.$id;
+   * }
+   * ```
+   *
+   * @param compareFn a function that compares to [[UrlRule]] objects.
+   *    The `compareFn` should abide by the `Array.sort` compare function rules.
+   *    Given two rules, `a` and `b`, return a negative number if `a` should be higher priority.
+   *    Return a positive number if `b` should be higher priority.
+   *    Return `0` if the rules are identical.
+   *
+   *    See the [mozilla reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Description)
+   *    for details.
+   */
+  sort(compareFn: any): void;
+  ensureSorted(): void;
+  stableSort(arr: any, compareFn: any): any;
+  /**
+   * Registers a `matcher` and `handler` for custom URLs handling.
+   *
+   * The `matcher` can be:
+   *
+   * - a [[UrlMatcher]]: See: [[UrlMatcherFactory.compile]]
+   * - a `string`: The string is compiled to a [[UrlMatcher]]
+   * - a `RegExp`: The regexp is used to match the url.
+   *
+   * The `handler` can be:
+   *
+   * - a string: The url is redirected to the value of the string.
+   * - a function: The url is redirected to the return value of the function.
+   *
+   * ---
+   *
+   * When the `handler` is a `string` and the `matcher` is a `UrlMatcher` (or string), the redirect
+   * string is interpolated with parameter values.
+   *
+   * #### Example:
+   * When the URL is `/foo/123` the rule will redirect to `/bar/123`.
+   * ```js
+   * .when("/foo/:param1", "/bar/:param1")
+   * ```
+   *
+   * ---
+   *
+   * When the `handler` is a string and the `matcher` is a `RegExp`, the redirect string is
+   * interpolated with capture groups from the RegExp.
+   *
+   * #### Example:
+   * When the URL is `/foo/123` the rule will redirect to `/bar/123`.
+   * ```js
+   * .when(new RegExp("^/foo/(.*)$"), "/bar/$1");
+   * ```
+   *
+   * ---
+   *
+   * When the handler is a function, it receives the matched value, the current URL, and the `UIRouter` object (See [[UrlRuleHandlerFn]]).
+   * The "matched value" differs based on the `matcher`.
+   * For [[UrlMatcher]]s, it will be the matched state params.
+   * For `RegExp`, it will be the match array from `regexp.exec()`.
+   *
+   * If the handler returns a string, the URL is redirected to the string.
+   *
+   * #### Example:
+   * When the URL is `/foo/123` the rule will redirect to `/bar/123`.
+   * ```js
+   * .when(new RegExp("^/foo/(.*)$"), match => "/bar/" + match[1]);
+   * ```
+   *
+   * Note: the `handler` may also invoke arbitrary code, such as `$state.go()`
+   *
+   * @param matcher A pattern `string` to match, compiled as a [[UrlMatcher]], or a `RegExp`.
+   * @param handler The path to redirect to, or a function that returns the path.
+   * @param options `{ priority: number }`
+   *
+   * @return the registered [[UrlRule]]
+   */
+  when(
+    matcher: any,
+    handler: any,
+    options: any,
+  ): import("./url-rule.js").BaseUrlRule;
+}
+/**
+ * Default rule priority sorting function.
+ *
+ * Sorts rules by:
+ *
+ * - Explicit priority (set rule priority using [[UrlRules.when]])
+ * - Rule type (STATE: 4, URLMATCHER: 4, REGEXP: 3, RAW: 2, OTHER: 1)
+ * - `UrlMatcher` specificity ([[UrlMatcher.compare]]): works for STATE and URLMATCHER types to pick the most specific rule.
+ * - Rule registration order (for rule types other than STATE and URLMATCHER)
+ *   - Equally sorted State and UrlMatcher rules will each match the URL.
+ *     Then, the *best* match is chosen based on how many parameter values were matched.
+ */
+declare function defaultRuleSortFn(a: any, b: any): number;
+import { UrlRuleFactory } from "./url-rule.js";
+export {};