@angular/router 7.2.8 → 7.2.12

package/src/config.d.ts

@@ -10,53 +10,132 @@ import { Observable } from 'rxjs';
 import { ActivatedRouteSnapshot } from './router_state';
 import { UrlSegment, UrlSegmentGroup } from './url_tree';
 /**
- * @description
- *
- * Represents router configuration.
- *
- * `Routes` is an array of route configurations. Each one has the following properties:
- *
- * - `path` is a string that uses the route matcher DSL.
- * - `pathMatch` is a string that specifies the matching strategy. Options are `prefix` (default)
- *   and `full`. See [Matching Strategy](#matching-strategy) below for more information.
- * - `matcher` defines a custom strategy for path matching and supersedes `path` and `pathMatch`.
- * - `component` is a component type.
- * - `redirectTo` is the url fragment which will replace the current matched segment.
- * - `outlet` is the name of the outlet the component should be placed into.
- * - `canActivate` is an array of DI tokens used to look up CanActivate handlers. See
- *   `CanActivate` for more info.
- * - `canActivateChild` is an array of DI tokens used to look up CanActivateChild handlers. See
- *   `CanActivateChild` for more info.
- * - `canDeactivate` is an array of DI tokens used to look up CanDeactivate handlers. See
- *   `CanDeactivate` for more info.
- * - `canLoad` is an array of DI tokens used to look up CanLoad handlers. See
- *   `CanLoad` for more info.
- * - `data` is additional data provided to the component via `ActivatedRoute`.
- * - `resolve` is a map of DI tokens used to look up data resolvers. See `Resolve` for more
- *   info.
- * - `runGuardsAndResolvers` defines when guards and resolvers will be run. By default they run only
- *    when the matrix parameters of the route change. Options include:
- *    - `paramsChange` (default) - Run guards and resolvers when path or matrix params change. This
- *      mode ignores query param changes.
- *    - `paramsOrQueryParamsChange` - Guards and resolvers will run when any parameters change. This
- *      includes path, matrix, and query params.
- *    - `pathParamsChange` - Run guards and resolvers path or any path params change. This mode is
- *      useful if you want to ignore changes to all optional parameters such as query *and* matrix
- *      params.
- *    - `pathParamsOrQueryParamsChange` - Same as `pathParamsChange`, but also rerun when any query
- *      param changes
- *    - `always` - Run guards and resolvers on every navigation.
- *    - (from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean - Use a predicate
- *      function when none of the pre-configured modes fit the needs of the application. An example
- *      might be when you need to ignore updates to a param such as `sortDirection`, but need to
- *      reload guards and resolvers when changing the `searchRoot` param.
- * - `children` is an array of child route definitions.
- * - `loadChildren` is a reference to lazy loaded child routes. See `LoadChildren` for more
- *   info.
+ * Represents a route configuration for the Router service.
+ * An array of `Route` objects, used in `Router.config` and for nested route configurations
+ * in `Route.children`.
+ *
+ * @see `Route`
+ * @see `Router`
+ * @publicApi
+ */
+export declare type Routes = Route[];
+/**
+ * Represents the result of matching URLs with a custom matching function.
+ *
+ * * `consumed` is an array of the consumed URL segments.
+ * * `posParams` is a map of positional parameters.
+ *
+ * @see `UrlMatcher()`
+ * @publicApi
+ */
+export declare type UrlMatchResult = {
+    consumed: UrlSegment[];
+    posParams?: {
+        [name: string]: UrlSegment;
+    };
+};
+/**
+ * A function for matching a route against URLs. Implement a custom URL matcher
+ * for `Route.matcher` when a combination of `path` and `pathMatch`
+ * is not expressive enough.
+ *
+ * @param segments An array of URL segments.
+ * @param group A segment group.
+ * @param route The route to match against.
+ * @returns The match-result,
  *
  * @usageNotes
+ *
+ * The following matcher matches HTML files.
+ *
+ * ```
+ * export function htmlFiles(url: UrlSegment[]) {
+ *   return url.length === 1 && url[0].path.endsWith('.html') ? ({consumed: url}) : null;
+ * }
+ *
+ * export const routes = [{ matcher: htmlFiles, component: AnyComponent }];
+ * ```
+ *
+ * @publicApi
+ */
+export declare type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => UrlMatchResult;
+/**
+ *
+ * Represents static data associated with a particular route.
+ *
+ * @see `Route#data`
+ *
+ * @publicApi
+ */
+export declare type Data = {
+    [name: string]: any;
+};
+/**
+ *
+ * Represents the resolved data associated with a particular route.
+ *
+ * @see `Route#resolve`.
+ *
+ * @publicApi
+ */
+export declare type ResolveData = {
+    [name: string]: any;
+};
+/**
+ *
+ * A function that is called to resolve a collection of lazy-loaded routes.
+ *
+ * @see `Route#loadChildren`.
+ * @publicApi
+ */
+export declare type LoadChildrenCallback = () => Type<any> | NgModuleFactory<any> | Promise<Type<any>> | Observable<Type<any>>;
+/**
+ *
+ * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load,
+ * or a function that returns such a set.
+ *
+ * @see `Route#loadChildren`.
+ * @publicApi
+ */
+export declare type LoadChildren = string | LoadChildrenCallback;
+/**
+ *
+ * How to handle query parameters in a router link.
+ * One of:
+ * - `merge` : Merge new with current parameters.
+ * - `preserve` : Preserve current parameters.
+ *
+ * @see `RouterLink#queryParamsHandling`.
+ * @publicApi
+ */
+export declare type QueryParamsHandling = 'merge' | 'preserve' | '';
+/**
+ *
+ * A policy for when to run guards and resolvers on a route.
+ *
+ * @see `Route#runGuardsAndResolvers`
+ * @publicApi
+ */
+export declare type RunGuardsAndResolvers = 'pathParamsChange' | 'pathParamsOrQueryParamsChange' | 'paramsChange' | 'paramsOrQueryParamsChange' | 'always' | ((from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean);
+/**
+ * A configuration object that defines a single route.
+ * A set of routes are collected in a `Routes` array to define a `Router` configuration.
+ * The router attempts to match segments of a given URL against each route,
+ * using the configuration options defined in this object.
+ *
+ * Supports static, parameterized, redirect, and wildcard routes, as well as
+ * custom route data and resolve methods.
+ *
+ * For detailed usage information, see the [Routing Guide](guide/router).
+ *
+ * @usageNotes
+ *
  * ### Simple Configuration
  *
+ * The following route specifies that when navigating to, for example,
+ * `/team/11/user/bob`, the router creates the 'Team' component
+ * with the 'User' child component in it.
+ *
  * ```
  * [{
  *   path: 'team/:id',
@@ -68,11 +147,12 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * When navigating to `/team/11/user/bob`, the router will create the team component with the user
- * component in it.
- *
  * ### Multiple Outlets
  *
+ * The following route creates sibling components with multiple outlets.
+ * When navigating to `/team/11(aux:chat/jim)`, the router creates the 'Team' component next to
+ * the 'Chat' component. The 'Chat' component is placed into the 'aux' outlet.
+ *
  * ```
  * [{
  *   path: 'team/:id',
@@ -84,22 +164,27 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * When navigating to `/team/11(aux:chat/jim)`, the router will create the team component next to
- * the chat component. The chat component will be placed into the aux outlet.
- *
  * ### Wild Cards
  *
+ * The following route uses wild-card notation to specify a component
+ * that is always instantiated regardless of where you navigate to.
+ *
  * ```
  * [{
  *   path: '**',
- *   component: Sink
+ *   component: WildcardComponent
  * }]
  * ```
  *
- * Regardless of where you navigate to, the router will instantiate the sink component.
- *
  * ### Redirects
  *
+ * The following route uses the `redirectTo` property to ignore a segment of
+ * a given URL when looking for a child path.
+ *
+ * When navigating to '/team/11/legacy/user/jim', the router changes the URL segment
+ * '/team/11/legacy/user/jim' to '/team/11/user/jim', and then instantiates
+ * the Team component with the User child component in it.
+ *
  * ```
  * [{
  *   path: 'team/:id',
@@ -114,17 +199,17 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * When navigating to '/team/11/legacy/user/jim', the router will change the url to
- * '/team/11/user/jim', and then will instantiate the team component with the user component
- * in it.
- *
- * If the `redirectTo` value starts with a '/', then it is an absolute redirect. E.g., if in the
- * example above we change the `redirectTo` to `/user/:name`, the result url will be '/user/jim'.
- *
+ * The redirect path can be relative, as shown in this example, or absolute.
+ * If we change the `redirectTo` value in the example to the absolute URL segment '/user/:name',
+ * the result URL is also absolute, '/user/jim'.
+
  * ### Empty Path
  *
  * Empty-path route configurations can be used to instantiate components that do not 'consume'
- * any url segments. Let's look at the following configuration:
+ * any URL segments.
+ *
+ * In the following configuration, when navigating to
+ * `/team/11`, the router instantiates the 'AllUsers' component.
  *
  * ```
  * [{
@@ -140,9 +225,11 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * When navigating to `/team/11`, the router will instantiate the AllUsers component.
+ * Empty-path routes can have children. In the following example, when navigating
+ * to `/team/11/user/jim`, the router instantiates the wrapper component with
+ * the user component in it.
  *
- * Empty-path routes can have children.
+ * Note that an empty path route inherits its parent's parameters and data.
  *
  * ```
  * [{
@@ -159,21 +246,11 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * When navigating to `/team/11/user/jim`, the router will instantiate the wrapper component with
- * the user component in it.
- *
- * An empty path route inherits its parent's params and data. This is because it cannot have its
- * own params, and, as a result, it often uses its parent's params and data as its own.
- *
  * ### Matching Strategy
  *
- * By default the router will look at what is left in the url, and check if it starts with
- * the specified path (e.g., `/team/11/user` starts with `team/:id`).
- *
- * We can change the matching strategy to make sure that the path covers the whole unconsumed url,
- * which is akin to `unconsumedUrl === path` or `$` regular expressions.
- *
- * This is particularly important when redirecting empty-path routes.
+ * The default path-match strategy is 'prefix', which means that the router
+ * checks URL elements from the left to see if the URL matches a specified path.
+ * For example, '/team/11/user' matches 'team/:id'.
  *
  * ```
  * [{
@@ -186,11 +263,14 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * Since an empty path is a prefix of any url, even when navigating to '/main', the router will
- * still apply the redirect.
+ * You can specify the path-match strategy 'full' to make sure that the path
+ * covers the whole unconsumed URL. It is important to do this when redirecting
+ * empty-path routes. Otherwise, because an empty path is a prefix of any URL,
+ * the router would apply the redirect even when navigating to the redirect destination,
+ * creating an endless loop.
  *
- * If `pathMatch: full` is provided, the router will apply the redirect if and only if navigating to
- * '/'.
+ * In the following example, supplying the 'full' `patchMatch` strategy ensures
+ * that the router applies the redirect if and only if navigating to '/'.
  *
  * ```
  * [{
@@ -205,13 +285,15 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  *
  * ### Componentless Routes
  *
- * It is useful at times to have the ability to share parameters between sibling components.
- *
- * Say we have two components--ChildCmp and AuxCmp--that we want to put next to each other and both
- * of them require some id parameter.
+ * You can share parameters between sibling components.
+ * For example, suppose that two sibling components should go next to each other,
+ * and both of them require an ID parameter. You can accomplish this using a route
+ * that does not specify a component at the top level.
  *
- * One way to do that would be to have a bogus parent component, so both the siblings can get the id
- * parameter from it. This is not ideal. Instead, you can use a componentless route.
+ * In the following example, 'ChildCmp' and 'AuxCmp' are siblings.
+ * When navigating to 'parent/10/(a//aux:b)', the route instantiates
+ * the main child and aux child components next to each other.
+ * For this to work, the application component must have the primary and aux outlets defined.
  *
  * ```
  * [{
@@ -223,15 +305,13 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * So when navigating to `parent/10/(a//aux:b)`, the route will instantiate the main child and aux
- * child components next to each other. In this example, the application component
- * has to have the primary and aux outlets defined.
- *
- * The router will also merge the `params`, `data`, and `resolve` of the componentless parent into
- * the `params`, `data`, and `resolve` of the children. This is done because there is no component
- * that can inject the activated route of the componentless parent.
+ * The router merges the parameters, data, and resolve of the componentless
+ * parent into the parameters, data, and resolve of the children.
  *
- * This is especially useful when child components are defined as follows:
+ * This is especially useful when child components are defined
+ * with an empty path string, as in the following example.
+ * With this configuration, navigating to '/parent/10' creates
+ * the main child and aux components.
  *
  * ```
  * [{
@@ -243,14 +323,16 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * With this configuration in place, navigating to '/parent/10' will create the main child and aux
- * components.
- *
  * ### Lazy Loading
  *
- * Lazy loading speeds up our application load time by splitting it into multiple bundles, and
- * loading them on demand. The router is designed to make lazy loading simple and easy. Instead of
- * providing the children property, you can provide the `loadChildren` property, as follows:
+ * Lazy loading speeds up application load time by splitting the application
+ * into multiple bundles and loading them on demand.
+ * To use lazy loading, provide the `loadChildren` property  instead of the `children` property.
+ *
+ * Given the following example route, the router uses the registered
+ * `NgModuleFactoryLoader` to fetch an NgModule associated with 'team'.
+ * It then extracts the set of routes defined in that NgModule,
+ * and transparently adds those routes to the main configuration.
  *
  * ```
  * [{
@@ -260,130 +342,101 @@ import { UrlSegment, UrlSegmentGroup } from './url_tree';
  * }]
  * ```
  *
- * The router will use registered NgModuleFactoryLoader to fetch an NgModule associated with 'team'.
- * Then it will extract the set of routes defined in that NgModule, and will transparently add
- * those routes to the main configuration.
- *
- * @publicApi
- */
-export declare type Routes = Route[];
-/**
- * @description Represents the results of the URL matching.
- *
- * * `consumed` is an array of the consumed URL segments.
- * * `posParams` is a map of positional parameters.
- *
- * @publicApi
- */
-export declare type UrlMatchResult = {
-    consumed: UrlSegment[];
-    posParams?: {
-        [name: string]: UrlSegment;
-    };
-};
-/**
- * @description
- *
- * A function matching URLs
- *
- * A custom URL matcher can be provided when a combination of `path` and `pathMatch` isn't
- * expressive enough.
- *
- * For instance, the following matcher matches html files.
- *
- * ```
- * export function htmlFiles(url: UrlSegment[]) {
- *   return url.length === 1 && url[0].path.endsWith('.html') ? ({consumed: url}) : null;
- * }
- *
- * export const routes = [{ matcher: htmlFiles, component: AnyComponent }];
- * ```
- *
- * @publicApi
- */
-export declare type UrlMatcher = (segments: UrlSegment[], group: UrlSegmentGroup, route: Route) => UrlMatchResult;
-/**
- * @description
- *
- * Represents the static data associated with a particular route.
- *
- * See `Routes` for more details.
- *
- * @publicApi
- */
-export declare type Data = {
-    [name: string]: any;
-};
-/**
- * @description
- *
- * Represents the resolved data associated with a particular route.
- *
- * See `Routes` for more details.
- *
- * @publicApi
- */
-export declare type ResolveData = {
-    [name: string]: any;
-};
-/**
- * @description
- *
- * The type of `loadChildren`.
- *
- * See `Routes` for more details.
- *
- * @publicApi
- */
-export declare type LoadChildrenCallback = () => Type<any> | NgModuleFactory<any> | Promise<Type<any>> | Observable<Type<any>>;
-/**
- * @description
- *
- * The type of `loadChildren`.
- *
- * See `Routes` for more details.
- *
- * @publicApi
- */
-export declare type LoadChildren = string | LoadChildrenCallback;
-/**
- * @description
- *
- * The type of `queryParamsHandling`.
- *
- * See `RouterLink` for more details.
- *
- */
-export declare type QueryParamsHandling = 'merge' | 'preserve' | '';
-/**
- * @description
- *
- * The type of `runGuardsAndResolvers`.
- *
- * See `Routes` for more details.
- * @publicApi
- */
-export declare type RunGuardsAndResolvers = 'pathParamsChange' | 'pathParamsOrQueryParamsChange' | 'paramsChange' | 'paramsOrQueryParamsChange' | 'always' | ((from: ActivatedRouteSnapshot, to: ActivatedRouteSnapshot) => boolean);
-/**
- * See `Routes` for more details.
- *
  * @publicApi
  */
 export interface Route {
+    /**
+     * The path to match against, a URL string that uses router matching notation.
+     * Can include wild-card characters (*).   [where is that defined?]
+     * Default is "/" (the root path).
+     */
     path?: string;
+    /**
+     * The path-matching strategy, one of 'prefix' or 'full'.
+     * Default is 'prefix'.
+     *
+     * By default, the router checks URL elements from the left to see if the URL
+     * matches a given  path, and stops when there is a match. For example,
+     * '/team/11/user' matches 'team/:id'.
+     * The path-match strategy 'full' matches against the entire URL.
+     * It is important to do this when redirecting empty-path routes.
+     * Otherwise, because an empty path is a prefix of any URL,
+     * the router would apply the redirect even when navigating
+     * to the redirect destination, creating an endless loop.
+     *
+     */
     pathMatch?: string;
+    /**
+     * A URL-matching function to use as a custom strategy for path matching.
+     * If present, supersedes `path` and `pathMatch`.
+     */
     matcher?: UrlMatcher;
+    /**
+     * The component to instantiate when the path matches.
+     * Can be empty if child routes specify components.
+     */
     component?: Type<any>;
+    /**
+     * A URL to which to redirect when a the path matches.
+     * Absolute if the URL begins with a slash (/), otherwise relative to the path URL.
+     * When not present, router does not redirect.
+     */
     redirectTo?: string;
+    /**
+     * Name of a `RouterOutlet` object where the component can be placed
+     * when the path matches.
+     */
     outlet?: string;
+    /**
+     * An array of dependency-injection tokens used to look up `CanActivate()`
+     * handlers, in order to determine if the current user is allowed to
+     * activate the component. By default, any user can activate.
+     */
     canActivate?: any[];
+    /**
+     * An array of DI tokens used to look up `CanActivateChild()` handlers,
+     * in order to determine if the current user is allowed to activate
+     * a child of the component. By default, any user can activate a child.
+     */
     canActivateChild?: any[];
+    /**
+     * An array of DI tokens used to look up `CanDeactivate()`
+     * handlers, in order to determine if the current user is allowed to
+     * deactivate the component. By default, any user can deactivate.
+     *
+     */
     canDeactivate?: any[];
+    /**
+     * An array of DI tokens used to look up `CanLoad()`
+     * handlers, in order to determine if the current user is allowed to
+     * load the component. By default, any user can load.
+     */
     canLoad?: any[];
+    /**
+     * Additional developer-defined data provided to the component via
+     * `ActivatedRoute`. By default, no additional data is passed.
+     */
     data?: Data;
+    /**
+     * A map of DI tokens used to look up data resolvers. See `Resolve`.
+     */
     resolve?: ResolveData;
+    /**
+     * An array of child `Route` objects that specifies a nested route
+     * configuration.
+     */
     children?: Routes;
+    /**
+     * A `LoadChildren` object specifying lazy-loaded child routes.
+     */
     loadChildren?: LoadChildren;
+    /**
+     * Defines when guards and resolvers will be run. One of
+     * - `paramsOrQueryParamsChange` : Run when query parameters change.
+     * - `always` : Run on every execution.
+     * By default, guards and resolvers run only when the matrix
+     * parameters of the route change.
+     */
     runGuardsAndResolvers?: RunGuardsAndResolvers;
 }
 export declare class LoadedRouterConfig {