feat(LocationServices): Add a parts() method which returns the URL parts as an object

refactor(UrlSync): Consolidate UrlSync UrlListen UrlDeferIntercept
feat(UrlServices): Add `match()`: given a URL, return the best matching Url Rule

Author: christopherthielen

src/common/coreservices.ts

@@ -7,6 +7,7 @@
 /** for typedoc */
 import {IInjectable, Obj} from "./common";
 import { Disposable } from "../interface";
+import { UrlParts } from "../url/interface";
 
 export let notImplemented = (fnname: string) => () => {
   throw new Error(`${fnname}(): No coreservices implementation for UI-Router is loaded.`);
@@ -77,29 +78,32 @@ export interface LocationServices extends Disposable {
   url(newurl: string, replace?: boolean, state?: any): string;
 
   /**
-   * Gets the path portion of the current url
+   * Gets the path part of the current url
    *
    * If the current URL is `/some/path?query=value#anchor`, this returns `/some/path`
    *
    * @return the path portion of the url
    */
   path(): string;
+
   /**
-   * Gets the search portion of the current url as an object
+   * Gets the search part of the current url as an object
    *
    * If the current URL is `/some/path?query=value#anchor`, this returns `{ query: 'value' }`
    *
    * @return the search (querystring) portion of the url, as an object
    */
   search(): { [key: string]: any };
+
   /**
-   * Gets the hash portion of the current url
+   * Gets the hash part of the current url
    *
    * If the current URL is `/some/path?query=value#anchor`, this returns `anchor`
    *
    * @return the hash (anchor) portion of the url
    */
   hash(): string;
+
   /**
    * Registers a url change handler
    *

src/url/interface.ts

@@ -91,7 +91,6 @@ export interface UrlMatcherConfig {
    */
   defaultSquashPolicy(value?: (boolean|string)): (boolean|string);
 
-
   /**
    * Creates and registers a custom [[ParamTypeDefinition]] object
    *
@@ -120,7 +119,7 @@ export interface UrlMatcherConfig {
 }
 
 /** @internalapi */
-export interface UrlSync {
+export interface UrlSyncApi {
   /**
    * Checks the URL for a matching [[UrlRule]]
    *
@@ -142,10 +141,7 @@ export interface UrlSync {
    * ```
    */
   sync(evt?): void;
-}
 
-/** @internalapi */
-export interface UrlListen {
   /**
    * Starts or stops listening for URL changes
    *
@@ -166,11 +162,8 @@ export interface UrlListen {
    * });
    * ```
    */
-  listen(enabled?: boolean): Function;
-}
+  listen(enabled?: boolean): Function
 
-/** @internalapi */
-export interface UrlDeferIntercept {
   /**
    * Disables monitoring of the URL.
    *
@@ -195,7 +188,7 @@ export interface UrlDeferIntercept {
    * @param defer Indicates whether to defer location change interception.
    *        Passing no parameter is equivalent to `true`.
    */
-  deferIntercept(defer?: boolean);
+  deferIntercept(defer?: boolean)
 }
 
 /**
@@ -376,10 +369,23 @@ export interface UrlRules {
  */
 export interface UrlParts {
   path: string;
-  search: { [key: string]: any };
-  hash: string;
+  search?: { [key: string]: any };
+  hash?: string;
 }
 
+/**
+ * A UrlRule match result
+ *
+ * The result of UrlRouter.match()
+ */
+export interface MatchResult {
+  /** The matched value from a [[UrlRule]] */
+  match: any;
+  /** The rule that matched */
+  rule: UrlRule;
+  /** The match result weight */
+  weight: number;
+}
 /**
  * A function that matches the URL for a [[UrlRule]]
  *

src/url/urlRouter.ts

@@ -1,8 +1,9 @@
 /**
  * @internalapi
  * @module url
- */ /** for typedoc */
-import { removeFrom, createProxyFunctions, inArray, composeSort, sortBy } from "../common/common";
+ */
+/** for typedoc */
+import { removeFrom, createProxyFunctions, inArray, composeSort, sortBy, extend } from "../common/common";
 import { isFunction, isString, isDefined } from "../common/predicates";
 import { UrlMatcher } from "./urlMatcher";
 import { RawParams } from "../params/interface";
@@ -11,7 +12,7 @@ import { UIRouter } from "../router";
 import { val, is, pattern, prop, pipe } from "../common/hof";
 import { UrlRuleFactory } from "./urlRule";
 import { TargetState } from "../state/targetState";
-import { UrlRule, UrlRuleHandlerFn, UrlParts, UrlRules, UrlSync, UrlListen, UrlDeferIntercept } from "./interface";
+import { UrlRule, UrlRuleHandlerFn, UrlParts, UrlRules, UrlSyncApi, MatchResult } from "./interface";
 import { TargetStateDef } from "../state/interface";
 
 /** @hidden */
@@ -53,7 +54,7 @@ defaultRuleSortFn = composeSort(
  * This class updates the URL when the state changes.
  * It also responds to changes in the URL.
  */
-export class UrlRouter implements UrlRules, UrlSync, UrlListen, UrlDeferIntercept, Disposable {
+export class UrlRouter implements UrlRules, UrlSyncApi, Disposable {
   /** used to create [[UrlRule]] objects for common cases */
   public urlRuleFactory: UrlRuleFactory;
 
@@ -85,25 +86,20 @@ export class UrlRouter implements UrlRules, UrlSync, UrlListen, UrlDeferIntercep
     this._rules.sort(this._sortFn = compareFn || this._sortFn);
   }
 
-  /** @inheritdoc */
-  sync(evt?) {
-    if (evt && evt.defaultPrevented) return;
-
-    let router = this._router,
-        $url = router.urlService,
-        $state = router.stateService;
-
+  /**
+   * Given a URL, check all rules and return the best [[MatchResult]]
+   * @param url
+   * @returns {MatchResult}
+   */
+  match(url: UrlParts): MatchResult {
+    url = extend({path: '', search: {}, hash: '' }, url);
     let rules = this.rules();
     if (this._otherwiseFn) rules.push(this._otherwiseFn);
 
-    let url: UrlParts = {
-      path: $url.path(), search: $url.search(), hash: $url.hash()
-    };
-
     // Checks a single rule. Returns { rule: rule, match: match, weight: weight } if it matched, or undefined
-    interface MatchResult { match: any, rule: UrlRule, weight: number }
+
     let checkRule = (rule: UrlRule): MatchResult => {
-      let match = rule.match(url, router);
+      let match = rule.match(url, this._router);
       return match && { match, rule, weight: rule.matchPriority(match) };
     };
 
@@ -121,6 +117,23 @@ export class UrlRouter implements UrlRules, UrlSync, UrlListen, UrlDeferIntercep
       best = (!best || current && current.weight > best.weight) ? current : best;
     }
 
+    return best;
+  }
+
+  /** @inheritdoc */
+  sync(evt?) {
+    if (evt && evt.defaultPrevented) return;
+
+    let router = this._router,
+        $url = router.urlService,
+        $state = router.stateService;
+
+    let url: UrlParts = {
+      path: $url.path(), search: $url.search(), hash: $url.hash()
+    };
+
+    let best = this.match(url);
+
     let applyResult = pattern([
       [isString, (newurl: string) => $url.url(newurl)],
       [TargetState.isDef, (def: TargetStateDef) => $state.go(def.state, def.params, def.options)],

src/url/urlService.ts

@@ -6,7 +6,7 @@
 import { UIRouter } from "../router";
 import { LocationServices, notImplemented, LocationConfig } from "../common/coreservices";
 import { noop, createProxyFunctions } from "../common/common";
-import { UrlConfig, UrlSync, UrlListen, UrlRules, UrlDeferIntercept } from "./interface";
+import { UrlConfig, UrlSyncApi, UrlRules, UrlParts, MatchResult } from "./interface";
 
 /** @hidden */
 const makeStub = (keys: string[]): any =>
@@ -16,12 +16,12 @@ const makeStub = (keys: string[]): any =>
 /** @hidden */ const locationConfigFns = ["port", "protocol", "host", "baseHref", "html5Mode", "hashPrefix"];
 /** @hidden */ const umfFns = ["type", "caseInsensitive", "strictMode", "defaultSquashPolicy"];
 /** @hidden */ const rulesFns = ["sort", "when", "otherwise", "rules", "rule", "removeRule"];
-/** @hidden */ const syncFns = ["deferIntercept", "listen", "sync"];
+/** @hidden */ const syncFns = ["deferIntercept", "listen", "sync", "match"];
 
 /**
  * API for URL management
  */
-export class UrlService implements LocationServices, UrlSync, UrlListen, UrlDeferIntercept {
+export class UrlService implements LocationServices, UrlSyncApi {
   /** @hidden */
   static locationServiceStub: LocationServices = makeStub(locationServicesFns);
   /** @hidden */
@@ -41,6 +41,18 @@ export class UrlService implements LocationServices, UrlSync, UrlListen, UrlDefe
   /** @inheritdoc */
   onChange(callback: Function): Function { return };
 
+
+  /**
+   * Returns the current URL parts
+   *
+   * This method returns the current URL components as a [[UrlParts]] object.
+   *
+   * @returns the current url parts
+   */
+  parts(): UrlParts {
+    return { path: this.path(), search: this.search(), hash: this.hash() }
+  }
+
   dispose() { }
 
   /** @inheritdoc */
@@ -49,6 +61,8 @@ export class UrlService implements LocationServices, UrlSync, UrlListen, UrlDefe
   listen(enabled?: boolean): Function { return };
   /** @inheritdoc */
   deferIntercept(defer?: boolean) { return }
+  /** @inheritdoc */
+  match(urlParts: UrlParts): MatchResult { return }
 
   /**
    * A nested API for managing URL rules and rewrites

src/vanilla/hashLocation.ts

@@ -22,7 +22,7 @@ export class HashLocationService implements LocationServices, Disposable {
   url(url?: string, replace: boolean = true): string {
     if (isDefined(url)) location.hash = url;
     return buildUrl(this);
-  };
+  }
 
   onChange(cb: EventListener) {
     window.addEventListener('hashchange', cb, false);

test/urlRouterSpec.ts

@@ -4,7 +4,7 @@ import { LocationServices } from "../src/common/coreservices";
 import { UrlService } from "../src/url/urlService";
 import { StateRegistry } from "../src/state/stateRegistry";
 import { noop } from "../src/common/common";
-import { UrlRule } from "../src/url/interface";
+import { UrlRule, MatchResult } from "../src/url/interface";
 
 declare var jasmine;
 var _anything = jasmine.anything();
@@ -272,6 +272,34 @@ describe("UrlRouter", function () {
       })
     });
   });
+
+  describe('match', () => {
+    let A, B, CCC;
+    beforeEach(() => {
+      A = stateRegistry.register({ name: 'A', url: '/:pA' });
+      B = stateRegistry.register({ name: 'B', url: '/BBB' });
+      CCC = urlService.rules.when('/CCC', '/DDD');
+    });
+
+    it("should return the best match for a URL 1", () => {
+      let match: MatchResult = urlRouter.match({ path: '/BBB' });
+      expect(match.rule.type).toBe("STATE");
+      expect(match.rule['state']).toBe(B)
+    });
+
+    it("should return the best match for a URL 2", () => {
+      let match: MatchResult = urlRouter.match({ path: '/EEE' });
+      expect(match.rule.type).toBe("STATE");
+      expect(match.rule['state']).toBe(A);
+      expect(match.match).toEqual({ pA: 'EEE' });
+    });
+
+    it("should return the best match for a URL 3", () => {
+      let match: MatchResult = urlRouter.match({ path: '/CCC' });
+      expect(match.rule.type).toBe("URLMATCHER");
+      expect(match.rule).toBe(CCC);
+    });
+  });
 });
 
 describe('UrlRouter.deferIntercept', () => {