@angular-wave/angular.ts 0.0.11 → 0.0.13

package/src/router/core/url/urlRouter.js

@@ -0,0 +1,115 @@
+import { stripLastPathElement } from "../common/strings";
+import { UrlRuleFactory } from "./urlRule";
+function appendBasePath(url, isHtml5, absolute, baseHref) {
+  if (baseHref === "/") return url;
+  if (isHtml5) return stripLastPathElement(baseHref) + url;
+  if (absolute) return baseHref.slice(1) + url;
+  return url;
+}
+/**
+ * Updates URL and responds to URL changes
+ *
+ * ### Deprecation warning:
+ * This class is now considered to be an internal API
+ * Use the [[UrlService]] instead.
+ * For configuring URL rules, use the [[UrlRules]] which can be found as [[UrlService.rules]].
+ */
+export class UrlRouter {
+  /** @internal */
+  constructor(/** @internal */ router) {
+    this.router = router;
+    // Delegate these calls to [[UrlService]]
+    /** @deprecated use [[UrlService.sync]]*/
+    this.sync = (evt) => this.router.urlService.sync(evt);
+    /** @deprecated use [[UrlService.listen]]*/
+    this.listen = (enabled) => this.router.urlService.listen(enabled);
+    /** @deprecated use [[UrlService.deferIntercept]]*/
+    this.deferIntercept = (defer) =>
+      this.router.urlService.deferIntercept(defer);
+    /** @deprecated use [[UrlService.match]]*/
+    this.match = (urlParts) => this.router.urlService.match(urlParts);
+    // Delegate these calls to [[UrlRules]]
+    /** @deprecated use [[UrlRules.initial]]*/
+    this.initial = (handler) => this.router.urlService.rules.initial(handler);
+    /** @deprecated use [[UrlRules.otherwise]]*/
+    this.otherwise = (handler) =>
+      this.router.urlService.rules.otherwise(handler);
+    /** @deprecated use [[UrlRules.removeRule]]*/
+    this.removeRule = (rule) => this.router.urlService.rules.removeRule(rule);
+    /** @deprecated use [[UrlRules.rule]]*/
+    this.rule = (rule) => this.router.urlService.rules.rule(rule);
+    /** @deprecated use [[UrlRules.rules]]*/
+    this.rules = () => this.router.urlService.rules.rules();
+    /** @deprecated use [[UrlRules.sort]]*/
+    this.sort = (compareFn) => this.router.urlService.rules.sort(compareFn);
+    /** @deprecated use [[UrlRules.when]]*/
+    this.when = (matcher, handler, options) =>
+      this.router.urlService.rules.when(matcher, handler, options);
+    this.urlRuleFactory = new UrlRuleFactory(router);
+  }
+  /** Internal API. */
+  update(read) {
+    const $url = this.router.locationService;
+    if (read) {
+      this.location = $url.url();
+      return;
+    }
+    if ($url.url() === this.location) return;
+    $url.url(this.location, true);
+  }
+  /**
+   * Internal API.
+   *
+   * Pushes a new location to the browser history.
+   *
+   * @internal
+   * @param urlMatcher
+   * @param params
+   * @param options
+   */
+  push(urlMatcher, params, options) {
+    const replace = options && !!options.replace;
+    this.router.urlService.url(urlMatcher.format(params || {}), replace);
+  }
+  /**
+   * Builds and returns a URL with interpolated parameters
+   *
+   * #### Example:
+   * ```js
+   * matcher = $umf.compile("/about/:person");
+   * params = { person: "bob" };
+   * $bob = $urlRouter.href(matcher, params);
+   * // $bob == "/about/bob";
+   * ```
+   *
+   * @param urlMatcher The [[UrlMatcher]] object which is used as the template of the URL to generate.
+   * @param params An object of parameter values to fill the matcher's required parameters.
+   * @param options Options object. The options are:
+   *
+   * - **`absolute`** - {boolean=false},  If true will generate an absolute url, e.g. "http://www.example.com/fullurl".
+   *
+   * @returns Returns the fully compiled URL, or `null` if `params` fail validation against `urlMatcher`
+   */
+  href(urlMatcher, params, options) {
+    let url = urlMatcher.format(params);
+    if (url == null) return null;
+    options = options || { absolute: false };
+    const cfg = this.router.urlService.config;
+    const isHtml5 = cfg.html5Mode();
+    if (!isHtml5 && url !== null) {
+      url = "#" + cfg.hashPrefix() + url;
+    }
+    url = appendBasePath(url, isHtml5, options.absolute, cfg.baseHref());
+    if (!options.absolute || !url) {
+      return url;
+    }
+    const slash = !isHtml5 && url ? "/" : "";
+    const cfgPort = cfg.port();
+    const port = cfgPort === 80 || cfgPort === 443 ? "" : ":" + cfgPort;
+    return [cfg.protocol(), "://", cfg.host(), port, slash, url].join("");
+  }
+  /** @deprecated use [[UrlService.interceptDeferred]]*/
+  get interceptDeferred() {
+    return this.router.urlService.interceptDeferred;
+  }
+}

package/src/router/core/url/urlRule.js

@@ -0,0 +1,202 @@
+import { UrlMatcher } from "./urlMatcher";
+import { isString, isDefined, isFunction } from "../common/predicates";
+import { identity, extend } from "../common/common";
+import { is, or, pattern } from "../common/hof";
+import { StateObject } from "../state/stateObject";
+/**
+ * Creates a [[UrlRule]]
+ *
+ * Creates a [[UrlRule]] from a:
+ *
+ * - `string`
+ * - [[UrlMatcher]]
+ * - `RegExp`
+ * - [[StateObject]]
+ */
+export class UrlRuleFactory {
+  constructor(router) {
+    this.router = router;
+  }
+  compile(str) {
+    return this.router.urlMatcherFactory.compile(str);
+  }
+  create(what, handler) {
+    const { isState, isStateDeclaration } = StateObject;
+    const makeRule = pattern([
+      [isString, (_what) => makeRule(this.compile(_what))],
+      [is(UrlMatcher), (_what) => this.fromUrlMatcher(_what, handler)],
+      [
+        or(isState, isStateDeclaration),
+        (_what) => this.fromState(_what, this.router),
+      ],
+      [is(RegExp), (_what) => this.fromRegExp(_what, handler)],
+      [isFunction, (_what) => new BaseUrlRule(_what, handler)],
+    ]);
+    const rule = makeRule(what);
+    if (!rule) throw new Error("invalid 'what' in when()");
+    return rule;
+  }
+  /**
+   * 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, handler) {
+    let _handler = handler;
+    if (isString(handler))
+      handler = this.router.urlMatcherFactory.compile(handler);
+    if (is(UrlMatcher)(handler)) _handler = (match) => handler.format(match);
+    function matchUrlParamters(url) {
+      const params = urlMatcher.exec(url.path, url.search, url.hash);
+      return urlMatcher.validates(params) && params;
+    }
+    // Prioritize URLs, lowest to highest:
+    // - Some optional URL parameters, but none matched
+    // - No optional parameters in URL
+    // - Some optional parameters, some matched
+    // - Some optional parameters, all matched
+    function matchPriority(params) {
+      const optional = urlMatcher
+        .parameters()
+        .filter((param) => param.isOptional);
+      if (!optional.length) return 0.000001;
+      const matched = optional.filter((param) => params[param.id]);
+      return matched.length / optional.length;
+    }
+    const details = { urlMatcher, matchPriority, type: "URLMATCHER" };
+    return extend(new BaseUrlRule(matchUrlParamters, _handler), details);
+  }
+  /**
+   * 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, router) {
+    const state = StateObject.isStateDeclaration(stateOrDecl)
+      ? stateOrDecl.$$state()
+      : stateOrDecl;
+    /**
+     * Handles match by transitioning to matched state
+     *
+     * First checks if the router should start a new transition.
+     * A new transition is not required if the current state's URL
+     * and the new URL are already identical
+     */
+    const handler = (match) => {
+      const $state = router.stateService;
+      const globals = router.globals;
+      if (
+        $state.href(state, match) !==
+        $state.href(globals.current, globals.params)
+      ) {
+        $state.transitionTo(state, match, { inherit: true, source: "url" });
+      }
+    };
+    const details = { state, type: "STATE" };
+    return extend(this.fromUrlMatcher(state.url, handler), details);
+  }
+  /**
+   * 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, handler) {
+    if (regexp.global || regexp.sticky)
+      throw new Error("Rule RegExp must not be global or sticky");
+    /**
+     * If handler is a string, the url will be replaced by the string.
+     * If the string has any String.replace() style variables in it (like `$2`),
+     * they will be replaced by the captures from [[match]]
+     */
+    const redirectUrlTo = (match) =>
+      // Interpolates matched values into $1 $2, etc using a String.replace()-style pattern
+      handler.replace(
+        /\$(\$|\d{1,2})/,
+        (m, what) => match[what === "$" ? 0 : Number(what)],
+      );
+    const _handler = isString(handler) ? redirectUrlTo : handler;
+    const matchParamsFromRegexp = (url) => regexp.exec(url.path);
+    const details = { regexp, type: "REGEXP" };
+    return extend(new BaseUrlRule(matchParamsFromRegexp, _handler), details);
+  }
+}
+UrlRuleFactory.isUrlRule = (obj) =>
+  obj && ["type", "match", "handler"].every((key) => isDefined(obj[key]));
+/**
+ * A base rule which calls `match`
+ *
+ * The value from the `match` function is passed through to the `handler`.
+ * @internal
+ */
+export class BaseUrlRule {
+  constructor(match, handler) {
+    this.match = match;
+    this.type = "RAW";
+    this.matchPriority = (match) => 0 - this.$id;
+    this.handler = handler || identity;
+  }
+}

package/src/router/core/url/urlRules.js

@@ -0,0 +1,348 @@
+import { TargetState } from "../state/targetState";
+import { UrlMatcher } from "./urlMatcher";
+import { is, val } from "../common/hof";
+import { isDefined, isFunction, isString } from "../common/predicates";
+import { removeFrom } from "../common/common";
+import { UrlRuleFactory } from "./urlRule";
+const prioritySort = (a, b) => (b.priority || 0) - (a.priority || 0);
+const typeSort = (a, b) => {
+  const weights = { STATE: 4, URLMATCHER: 4, REGEXP: 3, RAW: 2, OTHER: 1 };
+  return (weights[a.type] || 0) - (weights[b.type] || 0);
+};
+const urlMatcherSort = (a, b) =>
+  !a.urlMatcher || !b.urlMatcher
+    ? 0
+    : UrlMatcher.compare(a.urlMatcher, b.urlMatcher);
+const idSort = (a, b) => {
+  // Identically sorted STATE and URLMATCHER best rule will be chosen by `matchPriority` after each rule matches the URL
+  const useMatchPriority = { STATE: true, URLMATCHER: true };
+  const equal = useMatchPriority[a.type] && useMatchPriority[b.type];
+  return equal ? 0 : (a.$id || 0) - (b.$id || 0);
+};
+/**
+ * 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.
+ */
+let defaultRuleSortFn;
+defaultRuleSortFn = (a, b) => {
+  let cmp = prioritySort(a, b);
+  if (cmp !== 0) return cmp;
+  cmp = typeSort(a, b);
+  if (cmp !== 0) return cmp;
+  cmp = urlMatcherSort(a, b);
+  if (cmp !== 0) return cmp;
+  return idSort(a, b);
+};
+function getHandlerFn(handler) {
+  if (
+    !isFunction(handler) &&
+    !isString(handler) &&
+    !is(TargetState)(handler) &&
+    !TargetState.isDef(handler)
+  ) {
+    throw new Error(
+      "'handler' must be a string, function, TargetState, or have a state: 'newtarget' property",
+    );
+  }
+  return isFunction(handler) ? handler : val(handler);
+}
+/**
+ * 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 `router.urlService.rules` (see: [[UIRouter.urlService]], [[URLService.rules]])
+ */
+export class UrlRules {
+  /** @internal */
+  constructor(/** @internal */ router) {
+    this.router = router;
+    /** @internal */ this._sortFn = defaultRuleSortFn;
+    /** @internal */ this._rules = [];
+    /** @internal */ this._id = 0;
+    this.urlRuleFactory = new UrlRuleFactory(router);
+  }
+  /** @internal */
+  dispose(router) {
+    this._rules = [];
+    delete this._otherwiseFn;
+  }
+  /**
+   * 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) {
+    const handlerFn = getHandlerFn(handler);
+    const matchFn = (urlParts, router) =>
+      router.globals.transitionHistory.size() === 0 &&
+      !!/^\/?$/.exec(urlParts.path);
+    this.rule(this.urlRuleFactory.create(matchFn, handlerFn));
+  }
+  /**
+   * 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) {
+    const handlerFn = getHandlerFn(handler);
+    this._otherwiseFn = this.urlRuleFactory.create(val(true), handlerFn);
+    this._sorted = false;
+  }
+  /**
+   * Remove a rule previously registered
+   *
+   * @param rule the matcher rule that was previously registered using [[rule]]
+   */
+  removeRule(rule) {
+    removeFrom(this._rules, rule);
+  }
+  /**
+   * 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) {
+    if (!UrlRuleFactory.isUrlRule(rule)) throw new Error("invalid rule");
+    rule.$id = this._id++;
+    rule.priority = rule.priority || 0;
+    this._rules.push(rule);
+    this._sorted = false;
+    return () => this.removeRule(rule);
+  }
+  /**
+   * Gets all registered rules
+   *
+   * @returns an array of all the registered rules
+   */
+  rules() {
+    this.ensureSorted();
+    return this._rules.concat(this._otherwiseFn ? [this._otherwiseFn] : []);
+  }
+  /**
+   * 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) {
+    const sorted = this.stableSort(
+      this._rules,
+      (this._sortFn = compareFn || this._sortFn),
+    );
+    // precompute _sortGroup values and apply to each rule
+    let group = 0;
+    for (let i = 0; i < sorted.length; i++) {
+      sorted[i]._group = group;
+      if (
+        i < sorted.length - 1 &&
+        this._sortFn(sorted[i], sorted[i + 1]) !== 0
+      ) {
+        group++;
+      }
+    }
+    this._rules = sorted;
+    this._sorted = true;
+  }
+  /** @internal */
+  ensureSorted() {
+    this._sorted || this.sort();
+  }
+  /** @internal */
+  stableSort(arr, compareFn) {
+    const arrOfWrapper = arr.map((elem, idx) => ({ elem, idx }));
+    arrOfWrapper.sort((wrapperA, wrapperB) => {
+      const cmpDiff = compareFn(wrapperA.elem, wrapperB.elem);
+      return cmpDiff === 0 ? wrapperA.idx - wrapperB.idx : cmpDiff;
+    });
+    return arrOfWrapper.map((wrapper) => wrapper.elem);
+  }
+  /**
+   * 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, handler, options) {
+    const rule = this.urlRuleFactory.create(matcher, handler);
+    if (isDefined(options && options.priority))
+      rule.priority = options.priority;
+    this.rule(rule);
+    return rule;
+  }
+}