feat(router-deprecated): add router-deprecated module which backports…

… @angular/router-deprecated API

router-deprecated.ts

@@ -0,0 +1 @@
+export * from './src/router-deprecated/index';

src/router-deprecated/index.ts

@@ -0,0 +1,4 @@
+export { RouteDefinition } from './route_definition';
+export { ComponentInstruction, RouteData, RouteParams } from './instructions';
+export { OnReuse, OnActivate, OnDeactivate, CanDeactivate, CanReuse } from './interfaces';
+export { ChildRouter, RootRouter, Router } from './router';

src/router-deprecated/instructions.ts

@@ -0,0 +1,187 @@
+/**
+ * `RouteParams` is an immutable map of parameters for the given route
+ * based on the url matcher and optional parameters for that route.
+ *
+ * You can inject `RouteParams` into the constructor of a component to use it.
+ *
+ * ### Example
+ *
+ * ```
+ * import {Component} from '@angular/core';
+ * import {bootstrap} from '@angular/platform-browser/browser';
+ * import {Router, ROUTER_DIRECTIVES, ROUTER_PROVIDERS, RouteConfig, RouteParams} from
+ * 'angular2/router';
+ *
+ * @Component({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  {path: '/user/:id', component: UserCmp, name: 'UserCmp'},
+ * ])
+ * class AppCmp {}
+ *
+ * @Component({ template: 'user: {{id}}' })
+ * class UserCmp {
+ *   id: string;
+ *   constructor(params: RouteParams) {
+ *     this.id = params.get('id');
+ *   }
+ * }
+ *
+ * bootstrap(AppCmp, ROUTER_PROVIDERS);
+ * ```
+ */
+export type RouteParams = {
+  params: {[key: string]: string};
+
+  // @TODO this doesn't work with downgraded router to ng1
+  // get(param: string): string { return normalizeBlank(StringMapWrapper.get(this.params, param)); }
+}
+
+/**
+ * `RouteData` is an immutable map of additional data you can configure in your {@link Route}.
+ *
+ * You can inject `RouteData` into the constructor of a component to use it.
+ *
+ * ### Example
+ *
+ * ```
+ * import {Component} from '@angular/core';
+ * import {bootstrap} from '@angular/platform-browser/browser';
+ * import {Router, ROUTER_DIRECTIVES, ROUTER_PROVIDERS, RouteConfig, RouteData} from
+ * 'angular2/router';
+ *
+ * @Component({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  {path: '/user/:id', component: UserCmp, name: 'UserCmp', data: {isAdmin: true}},
+ * ])
+ * class AppCmp {}
+ *
+ * @Component({
+ *   ...,
+ *   template: 'user: {{isAdmin}}'
+ * })
+ * class UserCmp {
+ *   string: isAdmin;
+ *   constructor(data: RouteData) {
+ *     this.isAdmin = data.get('isAdmin');
+ *   }
+ * }
+ *
+ * bootstrap(AppCmp, ROUTER_PROVIDERS);
+ * ```
+ */
+export type RouteData = {
+  data: {[key: string]: any},
+
+// @TODO this doesn't work with downgraded router to ng1
+//   get(key: string): any { return normalizeBlank(StringMapWrapper.get(this.data, key)); }
+}
+
+/**
+ * `Instruction` is a tree of {@link ComponentInstruction}s with all the information needed
+ * to transition each component in the app to a given route, including all auxiliary routes.
+ *
+ * `Instruction`s can be created using {@link Router#generate}, and can be used to
+ * perform route changes with {@link Router#navigateByInstruction}.
+ *
+ * ### Example
+ *
+ * ```
+ * import {Component} from '@angular/core';
+ * import {bootstrap} from '@angular/platform-browser/browser';
+ * import {Router, ROUTER_DIRECTIVES, ROUTER_PROVIDERS, RouteConfig} from
+ * '@angular/router-deprecated';
+ *
+ * @Component({directives: [ROUTER_DIRECTIVES]})
+ * @RouteConfig([
+ *  {...},
+ * ])
+ * class AppCmp {
+ *   constructor(router: Router) {
+ *     var instruction = router.generate(['/MyRoute']);
+ *     router.navigateByInstruction(instruction);
+ *   }
+ * }
+ *
+ * bootstrap(AppCmp, ROUTER_PROVIDERS);
+ * ```
+ */
+export type Instruction = {
+
+  component: ComponentInstruction;
+  child: Instruction;
+  auxInstruction: {[key: string]: Instruction};
+
+  // get()
+  urlPath: string;
+  // get()
+  urlParams: string[];
+  // get()
+  specificity: string
+
+  resolveComponent(): ng.IPromise<ComponentInstruction>;
+
+  /**
+   * converts the instruction into a URL string
+   */
+  toRootUrl(): string;
+
+  /** @internal */
+  _toNonRootUrl(): string;
+
+  toUrlQuery(): string;
+
+  /**
+   * Returns a new instruction that shares the state of the existing instruction, but with
+   * the given child {@link Instruction} replacing the existing child.
+   */
+  replaceChild(child: Instruction): Instruction;
+
+  /**
+   * If the final URL for the instruction is ``
+   */
+  toUrlPath(): string;
+
+  // default instructions override these
+  toLinkUrl(): string;
+
+  // this is the non-root version (called recursively)
+  /** @internal */
+  _toLinkUrl(): string;
+
+  /** @internal */
+  _stringifyPathMatrixAuxPrefixed(): string;
+
+  /** @internal */
+  _stringifyMatrixParams(): string;
+
+  /** @internal */
+  _stringifyPathMatrixAux(): string;
+
+  /** @internal */
+  _stringifyAux(): string;
+}
+
+
+/**
+ * A `ComponentInstruction` represents the route state for a single component.
+ *
+ * `ComponentInstructions` is a public API. Instances of `ComponentInstruction` are passed
+ * to route lifecycle hooks, like {@link CanActivate}.
+ *
+ * `ComponentInstruction`s are [hash consed](https://en.wikipedia.org/wiki/Hash_consing). You should
+ * never construct one yourself with "new." Instead, rely on router's internal recognizer to
+ * construct `ComponentInstruction`s.
+ *
+ * You should not modify this object. It should be treated as immutable.
+ */
+export type ComponentInstruction = {
+  reuse: boolean;
+  urlPath: string;
+  urlParams: string[];
+  routeData: RouteData;
+  componentType: string;
+  terminal: boolean;
+  specificity: string;
+  params: {[key: string]: string};
+  routeName: string;
+}

src/router-deprecated/interfaces.ts

@@ -0,0 +1,122 @@
+import { ComponentInstruction } from './instructions';
+/**
+ * Defines route lifecycle method `routerOnActivate`, which is called by the router at the end of a
+ * successful route navigation.
+ *
+ * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse}
+ * will be called depending on the result of {@link CanReuse}.
+ *
+ * The `routerOnActivate` hook is called with two {@link ComponentInstruction}s as parameters, the
+ * first
+ * representing the current route being navigated to, and the second parameter representing the
+ * previous route or `null`.
+ *
+ * If `routerOnActivate` returns a promise, the route change will wait until the promise settles to
+ * instantiate and activate child components.
+ *
+ * ### Example
+ * {@example router/ts/on_activate/on_activate_example.ts region='routerOnActivate'}
+ */
+export interface OnActivate {
+  $routerOnActivate(
+    nextInstruction: ComponentInstruction,
+    prevInstruction: ComponentInstruction
+  ): any |ng.IPromise<any>;
+}
+
+/**
+ * Defines route lifecycle method `routerOnReuse`, which is called by the router at the end of a
+ * successful route navigation when {@link CanReuse} is implemented and returns or resolves to true.
+ *
+ * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse}
+ * will be called, depending on the result of {@link CanReuse}.
+ *
+ * The `routerOnReuse` hook is called with two {@link ComponentInstruction}s as parameters, the
+ * first
+ * representing the current route being navigated to, and the second parameter representing the
+ * previous route or `null`.
+ *
+ * ### Example
+ * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
+ */
+export interface OnReuse {
+  $routerOnReuse(
+    nextInstruction: ComponentInstruction,
+    prevInstruction: ComponentInstruction
+  ): any | ng.IPromise<any>;
+}
+
+/**
+ * Defines route lifecycle method `routerOnDeactivate`, which is called by the router before
+ * destroying
+ * a component as part of a route change.
+ *
+ * The `routerOnDeactivate` hook is called with two {@link ComponentInstruction}s as parameters, the
+ * first
+ * representing the current route being navigated to, and the second parameter representing the
+ * previous route.
+ *
+ * If `routerOnDeactivate` returns a promise, the route change will wait until the promise settles.
+ *
+ * ### Example
+ * {@example router/ts/on_deactivate/on_deactivate_example.ts region='routerOnDeactivate'}
+ */
+export interface OnDeactivate {
+  $routerOnDeactivate(
+    nextInstruction: ComponentInstruction,
+    prevInstruction: ComponentInstruction
+  ): any | ng.IPromise<any>;
+}
+
+/**
+ * Defines route lifecycle method `routerCanReuse`, which is called by the router to determine
+ * whether a
+ * component should be reused across routes, or whether to destroy and instantiate a new component.
+ *
+ * The `routerCanReuse` hook is called with two {@link ComponentInstruction}s as parameters, the
+ * first
+ * representing the current route being navigated to, and the second parameter representing the
+ * previous route.
+ *
+ * If `routerCanReuse` returns or resolves to `true`, the component instance will be reused and the
+ * {@link OnDeactivate} hook will be run. If `routerCanReuse` returns or resolves to `false`, a new
+ * component will be instantiated, and the existing component will be deactivated and removed as
+ * part of the navigation.
+ *
+ * If `routerCanReuse` throws or rejects, the navigation will be cancelled.
+ *
+ * ### Example
+ * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
+ */
+export interface CanReuse {
+  $routerCanReuse(
+    nextInstruction: ComponentInstruction,
+    prevInstruction: ComponentInstruction
+  ): boolean | ng.IPromise<boolean>;
+}
+
+/**
+ * Defines route lifecycle method `routerCanDeactivate`, which is called by the router to determine
+ * if a component can be removed as part of a navigation.
+ *
+ * The `routerCanDeactivate` hook is called with two {@link ComponentInstruction}s as parameters,
+ * the
+ * first representing the current route being navigated to, and the second parameter
+ * representing the previous route.
+ *
+ * If `routerCanDeactivate` returns or resolves to `false`, the navigation is cancelled. If it
+ * returns or
+ * resolves to `true`, then the navigation continues, and the component will be deactivated
+ * (the {@link OnDeactivate} hook will be run) and removed.
+ *
+ * If `routerCanDeactivate` throws or rejects, the navigation is also cancelled.
+ *
+ * ### Example
+ * {@example router/ts/can_deactivate/can_deactivate_example.ts region='routerCanDeactivate'}
+ */
+export interface CanDeactivate {
+  $routerCanDeactivate(
+    nextInstruction: ComponentInstruction,
+    prevInstruction: ComponentInstruction
+  ): boolean | ng.IPromise<boolean>;
+}

src/router-deprecated/route_definition.ts

@@ -0,0 +1,36 @@
+/**
+ * `RouteDefinition` defines a route within a {@link RouteConfig} decorator.
+ *
+ * Supported keys:
+ * - `path` or `aux` (requires exactly one of these)
+ * - `component`, `loader`,  `redirectTo` (requires exactly one of these)
+ * - `name` (optional)
+ * - `data` (optional)
+ *
+ * See also {@link Route}, {@link AsyncRoute}, {@link AuxRoute}, and {@link Redirect}.
+ */
+export interface RouteDefinition {
+  path?: string;
+  aux?: string;
+  regex?: string;
+  regex_group_names?: string[];
+  serializer?: any/*RegexSerializer*/;
+  component?: string | Type | ComponentDefinition;
+  loader?: () => ng.IPromise<Type>;
+  redirectTo?: any[];
+  name?: string;
+  data?: any;
+  useAsDefault?: boolean;
+}
+
+/**
+ * Represents either a component type (`type` is `component`) or a loader function
+ * (`type` is `loader`).
+ *
+ * See also {@link RouteDefinition}.
+ */
+export interface ComponentDefinition {
+  type: string;
+  loader?: () => ng.IPromise<Type>;
+  component?: Type;
+}