diff --git a/packages/core/src/linker/ng_module_factory_loader.ts b/packages/core/src/linker/ng_module_factory_loader.ts index c4660f71f8..f5a8b9aec6 100644 --- a/packages/core/src/linker/ng_module_factory_loader.ts +++ b/packages/core/src/linker/ng_module_factory_loader.ts @@ -17,6 +17,8 @@ import {NgModuleFactory} from './ng_module_factory'; * Used to load ng module factories. * * @publicApi + * @deprecated the `string` form of `loadChildren` is deprecated, and `NgModuleFactoryLoader` is + * part of its implementation. See `LoadChildren` for more details. */ export abstract class NgModuleFactoryLoader { abstract load(path: string): Promise>; diff --git a/packages/core/src/linker/system_js_ng_module_factory_loader.ts b/packages/core/src/linker/system_js_ng_module_factory_loader.ts index db9d2455c5..6221d67333 100644 --- a/packages/core/src/linker/system_js_ng_module_factory_loader.ts +++ b/packages/core/src/linker/system_js_ng_module_factory_loader.ts @@ -24,6 +24,8 @@ declare var System: any; * token. * * @publicApi + * @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoaderConfig` + * is part of its implementation. See `LoadChildren` for more details. */ export abstract class SystemJsNgModuleLoaderConfig { /** @@ -47,6 +49,8 @@ const DEFAULT_CONFIG: SystemJsNgModuleLoaderConfig = { /** * NgModuleFactoryLoader that uses SystemJS to load NgModuleFactory * @publicApi + * @deprecated the `string` form of `loadChildren` is deprecated, and `SystemJsNgModuleLoader` is + * part of its implementation. See `LoadChildren` for more details. */ @Injectable() export class SystemJsNgModuleLoader implements NgModuleFactoryLoader { diff --git a/packages/router/src/config.ts b/packages/router/src/config.ts index e49dc3d04f..17e9ca699d 100644 --- a/packages/router/src/config.ts +++ b/packages/router/src/config.ts @@ -93,6 +93,18 @@ export type ResolveData = { /** * * A function that is called to resolve a collection of lazy-loaded routes. + * + * Often this function will be implemented using an ES dynamic `import()` expression. For example: + * + * ``` + * [{ + * path: 'lazy', + * loadChildren: () => import('./lazy-route/lazy.module').then(mod => mod.LazyModule), + * }]; + * ``` + * + * This function _must_ match the form above: an arrow function of the form + * `() => import('...').then(mod => mod.MODULE)`. * * @see `Route#loadChildren`. * @publicApi @@ -105,10 +117,24 @@ export type LoadChildrenCallback = () => Type| NgModuleFactory| Observ * 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. * + * The string form of `LoadChildren` is deprecated (see `DeprecatedLoadChildren`). The function + * form (`LoadChildrenCallback`) should be used instead. + * * @see `Route#loadChildren`. * @publicApi */ -export type LoadChildren = string | LoadChildrenCallback; +export type LoadChildren = LoadChildrenCallback | DeprecatedLoadChildren; + +/** + * A string of the form `path/to/file#exportName` that acts as a URL for a set of routes to load. + * + * @see `Route#loadChildren` + * @publicApi + * @deprecated the `string` form of `loadChildren` is deprecated in favor of the proposed ES dynamic + * `import()` expression, which offers a more natural and standards-based mechanism to dynamically + * load an ES module at runtime. + */ +export type DeprecatedLoadChildren = string; /** * diff --git a/packages/router/src/index.ts b/packages/router/src/index.ts index 17abc4a990..4362289a19 100644 --- a/packages/router/src/index.ts +++ b/packages/router/src/index.ts @@ -7,7 +7,7 @@ */ -export {Data, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config'; +export {Data, DeprecatedLoadChildren, LoadChildren, LoadChildrenCallback, ResolveData, Route, Routes, RunGuardsAndResolvers, UrlMatchResult, UrlMatcher} from './config'; export {RouterLink, RouterLinkWithHref} from './directives/router_link'; export {RouterLinkActive} from './directives/router_link_active'; export {RouterOutlet} from './directives/router_outlet'; diff --git a/tools/public_api_guard/core/core.d.ts b/tools/public_api_guard/core/core.d.ts index 6bf194273b..214218ba97 100644 --- a/tools/public_api_guard/core/core.d.ts +++ b/tools/public_api_guard/core/core.d.ts @@ -586,6 +586,7 @@ export declare abstract class NgModuleFactory { abstract create(parentInjector: Injector | null): NgModuleRef; } +/** @deprecated */ export declare abstract class NgModuleFactoryLoader { abstract load(path: string): Promise>; } @@ -1297,11 +1298,13 @@ export interface SkipSelfDecorator { export declare type StaticProvider = ValueProvider | ExistingProvider | StaticClassProvider | ConstructorProvider | FactoryProvider | any[]; +/** @deprecated */ export declare class SystemJsNgModuleLoader implements NgModuleFactoryLoader { constructor(_compiler: Compiler, config?: SystemJsNgModuleLoaderConfig); load(path: string): Promise>; } +/** @deprecated */ export declare abstract class SystemJsNgModuleLoaderConfig { factoryPathPrefix: string; factoryPathSuffix: string; diff --git a/tools/public_api_guard/router/router.d.ts b/tools/public_api_guard/router/router.d.ts index 43e640ffdb..7d138b7b54 100644 --- a/tools/public_api_guard/router/router.d.ts +++ b/tools/public_api_guard/router/router.d.ts @@ -101,6 +101,9 @@ export declare class DefaultUrlSerializer implements UrlSerializer { serialize(tree: UrlTree): string; } +/** @deprecated */ +export declare type DeprecatedLoadChildren = string; + export declare type DetachedRouteHandle = {}; export declare type Event = RouterEvent | RouteConfigLoadStart | RouteConfigLoadEnd | ChildActivationStart | ChildActivationEnd | ActivationStart | ActivationEnd | Scroll; @@ -145,7 +148,7 @@ export declare class GuardsCheckStart extends RouterEvent { toString(): string; } -export declare type LoadChildren = string | LoadChildrenCallback; +export declare type LoadChildren = LoadChildrenCallback | DeprecatedLoadChildren; export declare type LoadChildrenCallback = () => Type | NgModuleFactory | Observable> | Promise | Type | any>;