UNPKG

@angular/upgrade

Version:

Angular - the library for easing update from v1 to v2

1,087 lines (1,073 loc) 53.5 kB
/** * @license Angular v21.0.3 * (c) 2010-2025 Google LLC. https://angular.dev/ * License: MIT */ import * as i0 from '@angular/core'; import { Type, StaticProvider, NgModuleRef, NgModuleFactory, OnInit, OnChanges, DoCheck, OnDestroy, ElementRef, Injector, SimpleChanges, NgZone, PlatformRef } from '@angular/core'; export { VERSION } from './upgrade.js'; type Ng1Token = string; type Ng1Expression = string | Function; interface IAnnotatedFunction extends Function { $inject?: Function extends { $inject?: string[]; } ? Ng1Token[] : ReadonlyArray<Ng1Token>; } type IInjectable = (Ng1Token | Function)[] | IAnnotatedFunction; type SingleOrListOrMap<T> = T | T[] | { [key: string]: T; }; interface IModule { name: string; requires: (string | IInjectable)[]; config(fn: IInjectable): IModule; directive(selector: string, factory: IInjectable): IModule; component(selector: string, component: IComponent): IModule; controller(name: string, type: IInjectable): IModule; factory(key: Ng1Token, factoryFn: IInjectable): IModule; value(key: Ng1Token, value: any): IModule; constant(token: Ng1Token, value: any): IModule; run(a: IInjectable): IModule; } interface ICompileService { (element: Element | NodeList | Node[] | string, transclude?: Function): ILinkFn; } interface ILinkFn { (scope: IScope, cloneAttachFn?: ICloneAttachFunction, options?: ILinkFnOptions): IAugmentedJQuery; $$slots?: { [slotName: string]: ILinkFn; }; } interface ILinkFnOptions { parentBoundTranscludeFn?: Function; transcludeControllers?: { [key: string]: any; }; futureParentElement?: Node; } interface IRootScopeService { $new(isolate?: boolean): IScope; $id: string; $parent: IScope; $root: IScope; $watch(exp: Ng1Expression, fn?: (a1?: any, a2?: any) => void): Function; $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function; $destroy(): any; $apply(exp?: Ng1Expression): any; $digest(): any; $evalAsync(exp: Ng1Expression, locals?: any): void; $on(event: string, fn?: (event?: any, ...args: any[]) => void): Function; $$childTail: IScope; $$childHead: IScope; $$nextSibling: IScope; $$phase: any; [key: string]: any; } interface IScope extends IRootScopeService { } interface IAngularBootstrapConfig { strictDi?: boolean; } interface IDirective { compile?: IDirectiveCompileFn; controller?: IController; controllerAs?: string; bindToController?: boolean | { [key: string]: string; }; link?: IDirectiveLinkFn | IDirectivePrePost; name?: string; priority?: number; replace?: boolean; require?: DirectiveRequireProperty; restrict?: string; scope?: boolean | { [key: string]: string; }; template?: string | Function; templateUrl?: string | Function; templateNamespace?: string; terminal?: boolean; transclude?: DirectiveTranscludeProperty; } type DirectiveRequireProperty = SingleOrListOrMap<string>; type DirectiveTranscludeProperty = boolean | 'element' | { [key: string]: string; }; interface IDirectiveCompileFn { (templateElement: IAugmentedJQuery, templateAttributes: IAttributes, transclude: ITranscludeFunction): IDirectivePrePost; } interface IDirectivePrePost { pre?: IDirectiveLinkFn; post?: IDirectiveLinkFn; } interface IDirectiveLinkFn { (scope: IScope, instanceElement: IAugmentedJQuery, instanceAttributes: IAttributes, controller: any, transclude: ITranscludeFunction): void; } interface IComponent { bindings?: { [key: string]: string; }; controller?: string | IInjectable; controllerAs?: string; require?: DirectiveRequireProperty; template?: string | Function; templateUrl?: string | Function; transclude?: DirectiveTranscludeProperty; } interface IAttributes { $observe(attr: string, fn: (v: string) => void): void; [key: string]: any; } interface ITranscludeFunction { (scope: IScope, cloneAttachFn: ICloneAttachFunction): IAugmentedJQuery; (cloneAttachFn?: ICloneAttachFunction): IAugmentedJQuery; } interface ICloneAttachFunction { (clonedElement: IAugmentedJQuery, scope: IScope): any; } type IAugmentedJQuery = Node[] & { on?: (name: string, fn: () => void) => void; data?: (name: string, value?: any) => any; text?: () => string; inheritedData?: (name: string, value?: any) => any; children?: () => IAugmentedJQuery; contents?: () => IAugmentedJQuery; parent?: () => IAugmentedJQuery; empty?: () => void; append?: (content: IAugmentedJQuery | string) => IAugmentedJQuery; controller?: (name: string) => any; isolateScope?: () => IScope; injector?: () => IInjectorService; triggerHandler?: (eventTypeOrObject: string | Event, extraParameters?: any[]) => IAugmentedJQuery; remove?: () => void; removeData?: () => void; }; interface IProvider { $get: IInjectable; } interface IProvideService { provider(token: Ng1Token, provider: IProvider): IProvider; factory(token: Ng1Token, factory: IInjectable): IProvider; service(token: Ng1Token, type: IInjectable): IProvider; value(token: Ng1Token, value: any): IProvider; constant(token: Ng1Token, value: any): void; decorator(token: Ng1Token, factory: IInjectable): void; } interface IParseService { (expression: string): ICompiledExpression; } interface ICompiledExpression { (context: any, locals: any): any; assign?: (context: any, value: any) => any; } interface IHttpBackendService { (method: string, url: string, post?: any, callback?: Function, headers?: any, timeout?: number, withCredentials?: boolean): void; } interface ICacheObject { put<T>(key: string, value?: T): T; get(key: string): any; } interface ITemplateCacheService extends ICacheObject { } type IController = string | IInjectable; interface IControllerService { (controllerConstructor: IController, locals?: any, later?: any, ident?: any): any; (controllerName: string, locals?: any): any; } interface IInjectorService { get(key: string): any; has(key: string): boolean; } interface IIntervalService { (func: Function, delay: number, count?: number, invokeApply?: boolean, ...args: any[]): Promise<any>; cancel(promise: Promise<any>): boolean; } interface ITestabilityService { findBindings(element: Element, expression: string, opt_exactMatch?: boolean): Element[]; findModels(element: Element, expression: string, opt_exactMatch?: boolean): Element[]; getLocation(): string; setLocation(url: string): void; whenStable(callback: Function): void; } interface INgModelController { $render(): void; $isEmpty(value: any): boolean; $setValidity(validationErrorKey: string, isValid: boolean): void; $setPristine(): void; $setDirty(): void; $setUntouched(): void; $setTouched(): void; $rollbackViewValue(): void; $validate(): void; $commitViewValue(): void; $setViewValue(value: any, trigger: string): void; $viewValue: any; $modelValue: any; $parsers: Function[]; $formatters: Function[]; $validators: { [key: string]: Function; }; $asyncValidators: { [key: string]: Function; }; $viewChangeListeners: Function[]; $error: Object; $pending: Object; $untouched: boolean; $touched: boolean; $pristine: boolean; $dirty: boolean; $valid: boolean; $invalid: boolean; $name: string; } declare let angular: { bootstrap: (e: Element, modules: (string | IInjectable)[], config?: IAngularBootstrapConfig) => IInjectorService; module: (prefix: string, dependencies?: string[]) => IModule; element: { (e: string | Element | Document | IAugmentedJQuery): IAugmentedJQuery; cleanData: (nodes: Node[] | NodeList) => void; }; injector: (modules: Array<string | IInjectable>, strictDi?: boolean) => IInjectorService; version: { major: number; }; resumeBootstrap: () => void; getTestability: (e: Element) => ITestabilityService; }; /** * @deprecated Use `setAngularJSGlobal` instead. * * @publicApi */ declare function setAngularLib(ng: any): void; /** * @deprecated Use `getAngularJSGlobal` instead. * * @publicApi */ declare function getAngularLib(): any; /** * Resets the AngularJS global. * * Used when AngularJS is loaded lazily, and not available on `window`. * * @publicApi */ declare function setAngularJSGlobal(ng: any): void; /** * Returns the current AngularJS global. * * @publicApi */ declare function getAngularJSGlobal(): any; declare const bootstrap: typeof angular.bootstrap; declare const module_: typeof angular.module; declare const element: typeof angular.element; declare const injector: typeof angular.injector; declare const resumeBootstrap: typeof angular.resumeBootstrap; declare const getTestability: typeof angular.getTestability; type angular1_d_DirectiveRequireProperty = DirectiveRequireProperty; type angular1_d_DirectiveTranscludeProperty = DirectiveTranscludeProperty; type angular1_d_IAngularBootstrapConfig = IAngularBootstrapConfig; type angular1_d_IAnnotatedFunction = IAnnotatedFunction; type angular1_d_IAttributes = IAttributes; type angular1_d_IAugmentedJQuery = IAugmentedJQuery; type angular1_d_ICacheObject = ICacheObject; type angular1_d_ICloneAttachFunction = ICloneAttachFunction; type angular1_d_ICompileService = ICompileService; type angular1_d_ICompiledExpression = ICompiledExpression; type angular1_d_IComponent = IComponent; type angular1_d_IController = IController; type angular1_d_IControllerService = IControllerService; type angular1_d_IDirective = IDirective; type angular1_d_IDirectiveCompileFn = IDirectiveCompileFn; type angular1_d_IDirectiveLinkFn = IDirectiveLinkFn; type angular1_d_IDirectivePrePost = IDirectivePrePost; type angular1_d_IHttpBackendService = IHttpBackendService; type angular1_d_IInjectable = IInjectable; type angular1_d_IInjectorService = IInjectorService; type angular1_d_IIntervalService = IIntervalService; type angular1_d_ILinkFn = ILinkFn; type angular1_d_ILinkFnOptions = ILinkFnOptions; type angular1_d_IModule = IModule; type angular1_d_INgModelController = INgModelController; type angular1_d_IParseService = IParseService; type angular1_d_IProvideService = IProvideService; type angular1_d_IProvider = IProvider; type angular1_d_IRootScopeService = IRootScopeService; type angular1_d_IScope = IScope; type angular1_d_ITemplateCacheService = ITemplateCacheService; type angular1_d_ITestabilityService = ITestabilityService; type angular1_d_ITranscludeFunction = ITranscludeFunction; type angular1_d_Ng1Expression = Ng1Expression; type angular1_d_Ng1Token = Ng1Token; type angular1_d_SingleOrListOrMap<T> = SingleOrListOrMap<T>; declare const angular1_d_bootstrap: typeof bootstrap; declare const angular1_d_element: typeof element; declare const angular1_d_getAngularJSGlobal: typeof getAngularJSGlobal; declare const angular1_d_getAngularLib: typeof getAngularLib; declare const angular1_d_getTestability: typeof getTestability; declare const angular1_d_injector: typeof injector; declare const angular1_d_module_: typeof module_; declare const angular1_d_resumeBootstrap: typeof resumeBootstrap; declare const angular1_d_setAngularJSGlobal: typeof setAngularJSGlobal; declare const angular1_d_setAngularLib: typeof setAngularLib; declare namespace angular1_d { export { angular1_d_bootstrap as bootstrap, angular1_d_element as element, angular1_d_getAngularJSGlobal as getAngularJSGlobal, angular1_d_getAngularLib as getAngularLib, angular1_d_getTestability as getTestability, angular1_d_injector as injector, angular1_d_module_ as module_, angular1_d_resumeBootstrap as resumeBootstrap, angular1_d_setAngularJSGlobal as setAngularJSGlobal, angular1_d_setAngularLib as setAngularLib }; export type { angular1_d_DirectiveRequireProperty as DirectiveRequireProperty, angular1_d_DirectiveTranscludeProperty as DirectiveTranscludeProperty, angular1_d_IAngularBootstrapConfig as IAngularBootstrapConfig, angular1_d_IAnnotatedFunction as IAnnotatedFunction, angular1_d_IAttributes as IAttributes, angular1_d_IAugmentedJQuery as IAugmentedJQuery, angular1_d_ICacheObject as ICacheObject, angular1_d_ICloneAttachFunction as ICloneAttachFunction, angular1_d_ICompileService as ICompileService, angular1_d_ICompiledExpression as ICompiledExpression, angular1_d_IComponent as IComponent, angular1_d_IController as IController, angular1_d_IControllerService as IControllerService, angular1_d_IDirective as IDirective, angular1_d_IDirectiveCompileFn as IDirectiveCompileFn, angular1_d_IDirectiveLinkFn as IDirectiveLinkFn, angular1_d_IDirectivePrePost as IDirectivePrePost, angular1_d_IHttpBackendService as IHttpBackendService, angular1_d_IInjectable as IInjectable, angular1_d_IInjectorService as IInjectorService, angular1_d_IIntervalService as IIntervalService, angular1_d_ILinkFn as ILinkFn, angular1_d_ILinkFnOptions as ILinkFnOptions, angular1_d_IModule as IModule, angular1_d_INgModelController as INgModelController, angular1_d_IParseService as IParseService, angular1_d_IProvideService as IProvideService, angular1_d_IProvider as IProvider, angular1_d_IRootScopeService as IRootScopeService, angular1_d_IScope as IScope, angular1_d_ITemplateCacheService as ITemplateCacheService, angular1_d_ITestabilityService as ITestabilityService, angular1_d_ITranscludeFunction as ITranscludeFunction, angular1_d_Ng1Expression as Ng1Expression, angular1_d_Ng1Token as Ng1Token, angular1_d_SingleOrListOrMap as SingleOrListOrMap }; } /** * @description * * A helper function that allows an Angular component to be used from AngularJS. * * *Part of the [upgrade/static](api?query=upgrade%2Fstatic) * library for hybrid upgrade apps that support AOT compilation* * * This helper function returns a factory function to be used for registering * an AngularJS wrapper directive for "downgrading" an Angular component. * * @usageNotes * ### Examples * * Let's assume that you have an Angular component called `ng2Heroes` that needs * to be made available in AngularJS templates. * * {@example upgrade/static/ts/full/module.ts region="ng2-heroes"} * * We must create an AngularJS [directive](https://docs.angularjs.org/guide/directive) * that will make this Angular component available inside AngularJS templates. * The `downgradeComponent()` function returns a factory function that we * can use to define the AngularJS directive that wraps the "downgraded" component. * * {@example upgrade/static/ts/full/module.ts region="ng2-heroes-wrapper"} * * For more details and examples on downgrading Angular components to AngularJS components please * visit the [Upgrade guide](https://angular.io/guide/upgrade#using-angular-components-from-angularjs-code). * * @param info contains information about the Component that is being downgraded: * * - `component: Type<any>`: The type of the Component that will be downgraded * - `downgradedModule?: string`: The name of the downgraded module (if any) that the component * "belongs to", as returned by a call to `downgradeModule()`. It is the module, whose * corresponding Angular module will be bootstrapped, when the component needs to be instantiated. * <br /> * (This option is only necessary when using `downgradeModule()` to downgrade more than one * Angular module.) * - `propagateDigest?: boolean`: Whether to perform {@link /api/core/ChangeDetectorRef#detectChanges detectChanges} on the * component on every {@link https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest $digest}. * If set to `false`, change detection will still be performed when any of the component's inputs changes. * (Default: true) * * @returns a factory function that can be used to register the component in an * AngularJS module. * * @publicApi */ declare function downgradeComponent(info: { component: Type<any>; downgradedModule?: string; propagateDigest?: boolean; /** @deprecated since v4. This parameter is no longer used */ inputs?: string[]; /** @deprecated since v4. This parameter is no longer used */ outputs?: string[]; /** @deprecated since v4. This parameter is no longer used */ selectors?: string[]; }): any; /** * @description * * A helper function to allow an Angular service to be accessible from AngularJS. * * *Part of the [upgrade/static](api?query=upgrade%2Fstatic) * library for hybrid upgrade apps that support AOT compilation* * * This helper function returns a factory function that provides access to the Angular * service identified by the `token` parameter. * * @usageNotes * ### Examples * * First ensure that the service to be downgraded is provided in an `NgModule` * that will be part of the upgrade application. For example, let's assume we have * defined `HeroesService` * * {@example upgrade/static/ts/full/module.ts region="ng2-heroes-service"} * * and that we have included this in our upgrade app `NgModule` * * {@example upgrade/static/ts/full/module.ts region="ng2-module"} * * Now we can register the `downgradeInjectable` factory function for the service * on an AngularJS module. * * {@example upgrade/static/ts/full/module.ts region="downgrade-ng2-heroes-service"} * * Inside an AngularJS component's controller we can get hold of the * downgraded service via the name we gave when downgrading. * * {@example upgrade/static/ts/full/module.ts region="example-app"} * * <div class="docs-alert docs-alert-important"> * * When using `downgradeModule()`, downgraded injectables will not be available until the Angular * module that provides them is instantiated. In order to be safe, you need to ensure that the * downgraded injectables are not used anywhere _outside_ the part of the app where it is * guaranteed that their module has been instantiated. * * For example, it is _OK_ to use a downgraded service in an upgraded component that is only used * from a downgraded Angular component provided by the same Angular module as the injectable, but * it is _not OK_ to use it in an AngularJS component that may be used independently of Angular or * use it in a downgraded Angular component from a different module. * * </div> * * @param token an `InjectionToken` that identifies a service provided from Angular. * @param downgradedModule the name of the downgraded module (if any) that the injectable * "belongs to", as returned by a call to `downgradeModule()`. It is the module, whose injector will * be used for instantiating the injectable.<br /> * (This option is only necessary when using `downgradeModule()` to downgrade more than one Angular * module.) * * @returns a [factory function](https://docs.angularjs.org/guide/di) that can be * used to register the service on an AngularJS module. * * @publicApi */ declare function downgradeInjectable(token: any, downgradedModule?: string): Function; /** * @description * * A helper function for creating an AngularJS module that can bootstrap an Angular module * "on-demand" (possibly lazily) when a {@link downgradeComponent downgraded component} needs to be * instantiated. * * *Part of the [upgrade/static](api?query=upgrade/static) library for hybrid upgrade apps that * support AOT compilation.* * * It allows loading/bootstrapping the Angular part of a hybrid application lazily and not having to * pay the cost up-front. For example, you can have an AngularJS application that uses Angular for * specific routes and only instantiate the Angular modules if/when the user visits one of these * routes. * * The Angular module will be bootstrapped once (when requested for the first time) and the same * reference will be used from that point onwards. * * `downgradeModule()` requires either an `NgModuleFactory`, `NgModule` class or a function: * - `NgModuleFactory`: If you pass an `NgModuleFactory`, it will be used to instantiate a module * using `platformBrowser`'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}. * NOTE: this type of the argument is deprecated. Please either provide an `NgModule` class or a * bootstrap function instead. * - `NgModule` class: If you pass an NgModule class, it will be used to instantiate a module * using `platformBrowser`'s {@link PlatformRef#bootstrapModule bootstrapModule()}. * - `Function`: If you pass a function, it is expected to return a promise resolving to an * `NgModuleRef`. The function is called with an array of extra {@link StaticProvider Providers} * that are expected to be available from the returned `NgModuleRef`'s `Injector`. * * `downgradeModule()` returns the name of the created AngularJS wrapper module. You can use it to * declare a dependency in your main AngularJS module. * * {@example upgrade/static/ts/lite/module.ts region="basic-how-to"} * * For more details on how to use `downgradeModule()` see * [Upgrading for Performance](https://angular.io/guide/upgrade). * * @usageNotes * * Apart from `UpgradeModule`, you can use the rest of the `upgrade/static` helpers as usual to * build a hybrid application. Note that the Angular pieces (e.g. downgraded services) will not be * available until the downgraded module has been bootstrapped, i.e. by instantiating a downgraded * component. * * <div class="docs-alert docs-alert-important"> * * You cannot use `downgradeModule()` and `UpgradeModule` in the same hybrid application.<br /> * Use one or the other. * * </div> * * ### Differences with `UpgradeModule` * * Besides their different API, there are two important internal differences between * `downgradeModule()` and `UpgradeModule` that affect the behavior of hybrid applications: * * 1. Unlike `UpgradeModule`, `downgradeModule()` does not bootstrap the main AngularJS module * inside the {@link NgZone Angular zone}. * 2. Unlike `UpgradeModule`, `downgradeModule()` does not automatically run a * [$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest) when changes are * detected in the Angular part of the application. * * What this means is that applications using `UpgradeModule` will run change detection more * frequently in order to ensure that both frameworks are properly notified about possible changes. * This will inevitably result in more change detection runs than necessary. * * `downgradeModule()`, on the other side, does not try to tie the two change detection systems as * tightly, restricting the explicit change detection runs only to cases where it knows it is * necessary (e.g. when the inputs of a downgraded component change). This improves performance, * especially in change-detection-heavy applications, but leaves it up to the developer to manually * notify each framework as needed. * * For a more detailed discussion of the differences and their implications, see * [Upgrading for Performance](https://angular.io/guide/upgrade). * * <div class="docs-alert docs-alert-helpful"> * * You can manually trigger a change detection run in AngularJS using * [scope.$apply(...)](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply) or * [$rootScope.$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest). * * You can manually trigger a change detection run in Angular using {@link NgZone#run * ngZone.run(...)}. * * </div> * * ### Downgrading multiple modules * * It is possible to downgrade multiple modules and include them in an AngularJS application. In * that case, each downgraded module will be bootstrapped when an associated downgraded component or * injectable needs to be instantiated. * * Things to keep in mind, when downgrading multiple modules: * * - Each downgraded component/injectable needs to be explicitly associated with a downgraded * module. See `downgradeComponent()` and `downgradeInjectable()` for more details. * * - If you want some injectables to be shared among all downgraded modules, you can provide them as * `StaticProvider`s, when creating the `PlatformRef` (e.g. via `platformBrowser` or * `platformBrowserDynamic`). * * - When using {@link PlatformRef#bootstrapmodule `bootstrapModule()`} or * {@link PlatformRef#bootstrapmodulefactory `bootstrapModuleFactory()`} to bootstrap the * downgraded modules, each one is considered a "root" module. As a consequence, a new instance * will be created for every injectable provided in `"root"` (via * {@link /api/core/Injectable#providedIn providedIn} * If this is not your intention, you can have a shared module (that will act as act as the "root" * module) and create all downgraded modules using that module's injector: * * {@example upgrade/static/ts/lite-multi-shared/module.ts region="shared-root-module"} * * @publicApi */ declare function downgradeModule<T>(moduleOrBootstrapFn: Type<T> | ((extraProviders: StaticProvider[]) => Promise<NgModuleRef<T>>)): string; /** * @description * * A helper function for creating an AngularJS module that can bootstrap an Angular module * "on-demand" (possibly lazily) when a {@link downgradeComponent downgraded component} needs to be * instantiated. * * *Part of the [upgrade/static](api?query=upgrade/static) library for hybrid upgrade apps that * support AOT compilation.* * * It allows loading/bootstrapping the Angular part of a hybrid application lazily and not having to * pay the cost up-front. For example, you can have an AngularJS application that uses Angular for * specific routes and only instantiate the Angular modules if/when the user visits one of these * routes. * * The Angular module will be bootstrapped once (when requested for the first time) and the same * reference will be used from that point onwards. * * `downgradeModule()` requires either an `NgModuleFactory`, `NgModule` class or a function: * - `NgModuleFactory`: If you pass an `NgModuleFactory`, it will be used to instantiate a module * using `platformBrowser`'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}. * NOTE: this type of the argument is deprecated. Please either provide an `NgModule` class or a * bootstrap function instead. * - `NgModule` class: If you pass an NgModule class, it will be used to instantiate a module * using `platformBrowser`'s {@link PlatformRef#bootstrapModule bootstrapModule()}. * - `Function`: If you pass a function, it is expected to return a promise resolving to an * `NgModuleRef`. The function is called with an array of extra {@link StaticProvider Providers} * that are expected to be available from the returned `NgModuleRef`'s `Injector`. * * `downgradeModule()` returns the name of the created AngularJS wrapper module. You can use it to * declare a dependency in your main AngularJS module. * * {@example upgrade/static/ts/lite/module.ts region="basic-how-to"} * * For more details on how to use `downgradeModule()` see * [Upgrading for Performance](https://angular.io/guide/upgrade). * * @usageNotes * * Apart from `UpgradeModule`, you can use the rest of the `upgrade/static` helpers as usual to * build a hybrid application. Note that the Angular pieces (e.g. downgraded services) will not be * available until the downgraded module has been bootstrapped, i.e. by instantiating a downgraded * component. * * <div class="docs-alert docs-alert-important"> * * You cannot use `downgradeModule()` and `UpgradeModule` in the same hybrid application.<br /> * Use one or the other. * * </div> * * ### Differences with `UpgradeModule` * * Besides their different API, there are two important internal differences between * `downgradeModule()` and `UpgradeModule` that affect the behavior of hybrid applications: * * 1. Unlike `UpgradeModule`, `downgradeModule()` does not bootstrap the main AngularJS module * inside the {@link NgZone Angular zone}. * 2. Unlike `UpgradeModule`, `downgradeModule()` does not automatically run a * [$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest) when changes are * detected in the Angular part of the application. * * What this means is that applications using `UpgradeModule` will run change detection more * frequently in order to ensure that both frameworks are properly notified about possible changes. * This will inevitably result in more change detection runs than necessary. * * `downgradeModule()`, on the other side, does not try to tie the two change detection systems as * tightly, restricting the explicit change detection runs only to cases where it knows it is * necessary (e.g. when the inputs of a downgraded component change). This improves performance, * especially in change-detection-heavy applications, but leaves it up to the developer to manually * notify each framework as needed. * * For a more detailed discussion of the differences and their implications, see * [Upgrading for Performance](https://angular.io/guide/upgrade). * * <div class="docs-alert docs-alert-helpful"> * * You can manually trigger a change detection run in AngularJS using * [scope.$apply(...)](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply) or * [$rootScope.$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest). * * You can manually trigger a change detection run in Angular using {@link NgZone#run * ngZone.run(...)}. * * </div> * * ### Downgrading multiple modules * * It is possible to downgrade multiple modules and include them in an AngularJS application. In * that case, each downgraded module will be bootstrapped when an associated downgraded component or * injectable needs to be instantiated. * * Things to keep in mind, when downgrading multiple modules: * * - Each downgraded component/injectable needs to be explicitly associated with a downgraded * module. See `downgradeComponent()` and `downgradeInjectable()` for more details. * * - If you want some injectables to be shared among all downgraded modules, you can provide them as * `StaticProvider`s, when creating the `PlatformRef` (e.g. via `platformBrowser` or * `platformBrowserDynamic`). * * - When using {@link PlatformRef#bootstrapmodule `bootstrapModule()`} or * {@link PlatformRef#bootstrapmodulefactory `bootstrapModuleFactory()`} to bootstrap the * downgraded modules, each one is considered a "root" module. As a consequence, a new instance * will be created for every injectable provided in `"root"` (via * {@link /api/core/Injectable#providedIn providedIn} * If this is not your intention, you can have a shared module (that will act as act as the "root" * module) and create all downgraded modules using that module's injector: * * {@example upgrade/static/ts/lite-multi-shared/module.ts region="shared-root-module"} * * @publicApi * * @deprecated Passing `NgModuleFactory` as the `downgradeModule` function argument is deprecated, * please pass an NgModule class reference instead. */ declare function downgradeModule<T>(moduleOrBootstrapFn: NgModuleFactory<T>): string; /** * @description * * A helper class that allows an AngularJS component to be used from Angular. * * *Part of the [upgrade/static](api?query=upgrade%2Fstatic) * library for hybrid upgrade apps that support AOT compilation.* * * This helper class should be used as a base class for creating Angular directives * that wrap AngularJS components that need to be "upgraded". * * @usageNotes * ### Examples * * Let's assume that you have an AngularJS component called `ng1Hero` that needs * to be made available in Angular templates. * * {@example upgrade/static/ts/full/module.ts region="ng1-hero"} * * We must create a `Directive` that will make this AngularJS component * available inside Angular templates. * * {@example upgrade/static/ts/full/module.ts region="ng1-hero-wrapper"} * * In this example you can see that we must derive from the `UpgradeComponent` * base class but also provide an {@link Directive `@Directive`} decorator. This is * because the AOT compiler requires that this information is statically available at * compile time. * * Note that we must do the following: * * specify the directive's selector (`ng1-hero`) * * specify all inputs and outputs that the AngularJS component expects * * derive from `UpgradeComponent` * * call the base class from the constructor, passing * * the AngularJS name of the component (`ng1Hero`) * * the `ElementRef` and `Injector` for the component wrapper * * @publicApi * @extensible */ declare class UpgradeComponent implements OnInit, OnChanges, DoCheck, OnDestroy { private helper; private $element; private $componentScope; private directive; private bindings; private controllerInstance?; private bindingDestination?; private pendingChanges; private unregisterDoCheckWatcher?; /** * Create a new `UpgradeComponent` instance. You should not normally need to do this. * Instead you should derive a new class from this one and call the super constructor * from the base class. * * {@example upgrade/static/ts/full/module.ts region="ng1-hero-wrapper" } * * * The `name` parameter should be the name of the AngularJS directive. * * The `elementRef` and `injector` parameters should be acquired from Angular by dependency * injection into the base class constructor. */ constructor(name: string, elementRef: ElementRef, injector: Injector); /** @docs-private */ ngOnInit(): void; /** @docs-private */ ngOnChanges(changes: SimpleChanges): void; /** @docs-private */ ngDoCheck(): void; /** @docs-private */ ngOnDestroy(): void; private initializeBindings; private initializeOutputs; private bindOutputs; private forwardChanges; static ɵfac: i0.ɵɵFactoryDeclaration<UpgradeComponent, never>; static ɵdir: i0.ɵɵDirectiveDeclaration<UpgradeComponent, never, never, {}, {}, never, never, true, never>; } /** * @description * * An `NgModule`, which you import to provide AngularJS core services, * and has an instance method used to bootstrap the hybrid upgrade application. * * *Part of the [upgrade/static](api?query=upgrade/static) * library for hybrid upgrade apps that support AOT compilation* * * The `upgrade/static` package contains helpers that allow AngularJS and Angular components * to be used together inside a hybrid upgrade application, which supports AOT compilation. * * Specifically, the classes and functions in the `upgrade/static` module allow the following: * * 1. Creation of an Angular directive that wraps and exposes an AngularJS component so * that it can be used in an Angular template. See `UpgradeComponent`. * 2. Creation of an AngularJS directive that wraps and exposes an Angular component so * that it can be used in an AngularJS template. See `downgradeComponent`. * 3. Creation of an Angular root injector provider that wraps and exposes an AngularJS * service so that it can be injected into an Angular context. See * {@link UpgradeModule#upgrading-an-angular-1-service Upgrading an AngularJS service} below. * 4. Creation of an AngularJS service that wraps and exposes an Angular injectable * so that it can be injected into an AngularJS context. See `downgradeInjectable`. * 5. Bootstrapping of a hybrid Angular application which contains both of the frameworks * coexisting in a single application. * * @usageNotes * * ```ts * import {UpgradeModule} from '@angular/upgrade/static'; * ``` * * See also the {@link UpgradeModule#examples examples} below. * * ### Mental Model * * When reasoning about how a hybrid application works it is useful to have a mental model which * describes what is happening and explains what is happening at the lowest level. * * 1. There are two independent frameworks running in a single application, each framework treats * the other as a black box. * 2. Each DOM element on the page is owned exactly by one framework. Whichever framework * instantiated the element is the owner. Each framework only updates/interacts with its own * DOM elements and ignores others. * 3. AngularJS directives always execute inside the AngularJS framework codebase regardless of * where they are instantiated. * 4. Angular components always execute inside the Angular framework codebase regardless of * where they are instantiated. * 5. An AngularJS component can be "upgraded"" to an Angular component. This is achieved by * defining an Angular directive, which bootstraps the AngularJS component at its location * in the DOM. See `UpgradeComponent`. * 6. An Angular component can be "downgraded" to an AngularJS component. This is achieved by * defining an AngularJS directive, which bootstraps the Angular component at its location * in the DOM. See `downgradeComponent`. * 7. Whenever an "upgraded"/"downgraded" component is instantiated the host element is owned by * the framework doing the instantiation. The other framework then instantiates and owns the * view for that component. * 1. This implies that the component bindings will always follow the semantics of the * instantiation framework. * 2. The DOM attributes are parsed by the framework that owns the current template. So * attributes in AngularJS templates must use kebab-case, while AngularJS templates must use * camelCase. * 3. However the template binding syntax will always use the Angular style, e.g. square * brackets (`[...]`) for property binding. * 8. Angular is bootstrapped first; AngularJS is bootstrapped second. AngularJS always owns the * root component of the application. * 9. The new application is running in an Angular zone, and therefore it no longer needs calls to * `$apply()`. * * ### The `UpgradeModule` class * * This class is an `NgModule`, which you import to provide AngularJS core services, * and has an instance method used to bootstrap the hybrid upgrade application. * * * Core AngularJS services<br /> * Importing this `NgModule` will add providers for the core * [AngularJS services](https://docs.angularjs.org/api/ng/service) to the root injector. * * * Bootstrap<br /> * The runtime instance of this class contains a {@link UpgradeModule#bootstrap `bootstrap()`} * method, which you use to bootstrap the top level AngularJS module onto an element in the * DOM for the hybrid upgrade app. * * It also contains properties to access the {@link UpgradeModule#injector root injector}, the * bootstrap `NgZone` and the * [AngularJS $injector](https://docs.angularjs.org/api/auto/service/$injector). * * ### Examples * * Import the `UpgradeModule` into your top level Angular {@link NgModule NgModule}. * * {@example upgrade/static/ts/full/module.ts region='ng2-module'} * * Then inject `UpgradeModule` into your Angular `NgModule` and use it to bootstrap the top level * [AngularJS module](https://docs.angularjs.org/api/ng/type/angular.Module) in the * `ngDoBootstrap()` method. * * {@example upgrade/static/ts/full/module.ts region='bootstrap-ng1'} * * Finally, kick off the whole process, by bootstrapping your top level Angular `NgModule`. * * {@example upgrade/static/ts/full/module.ts region='bootstrap-ng2'} * * ### Upgrading an AngularJS service * * There is no specific API for upgrading an AngularJS service. Instead you should just follow the * following recipe: * * Let's say you have an AngularJS service: * * {@example upgrade/static/ts/full/module.ts region="ng1-text-formatter-service"} * * Then you should define an Angular provider to be included in your `NgModule` `providers` * property. * * {@example upgrade/static/ts/full/module.ts region="upgrade-ng1-service"} * * Then you can use the "upgraded" AngularJS service by injecting it into an Angular component * or service. * * {@example upgrade/static/ts/full/module.ts region="use-ng1-upgraded-service"} * * @publicApi */ declare class UpgradeModule { /** The bootstrap zone for the upgrade application */ ngZone: NgZone; /** * The owning `NgModuleRef`s `PlatformRef` instance. * This is used to tie the lifecycle of the bootstrapped AngularJS apps to that of the Angular * `PlatformRef`. */ private platformRef; /** * The AngularJS `$injector` for the upgrade application. */ $injector: any; /** The Angular Injector **/ injector: Injector; private readonly applicationRef; constructor( /** The root `Injector` for the upgrade application. */ injector: Injector, /** The bootstrap zone for the upgrade application */ ngZone: NgZone, /** * The owning `NgModuleRef`s `PlatformRef` instance. * This is used to tie the lifecycle of the bootstrapped AngularJS apps to that of the Angular * `PlatformRef`. */ platformRef: PlatformRef); /** * Bootstrap an AngularJS application from this NgModule * @param element the element on which to bootstrap the AngularJS application * @param [modules] the AngularJS modules to bootstrap for this application * @param [config] optional extra AngularJS bootstrap configuration * @return The value returned by * [angular.bootstrap()](https://docs.angularjs.org/api/ng/function/angular.bootstrap). */ bootstrap(element: Element, modules?: string[], config?: any): any; static ɵfac: i0.ɵɵFactoryDeclaration<UpgradeModule, never>; static ɵmod: i0.ɵɵNgModuleDeclaration<UpgradeModule, never, never, never>; static ɵinj: i0.ɵɵInjectorDeclaration<UpgradeModule>; } declare const $COMPILE = "$compile"; declare const $CONTROLLER = "$controller"; declare const $DELEGATE = "$delegate"; declare const $EXCEPTION_HANDLER = "$exceptionHandler"; declare const $HTTP_BACKEND = "$httpBackend"; declare const $INJECTOR = "$injector"; declare const $INTERVAL = "$interval"; declare const $PARSE = "$parse"; declare const $PROVIDE = "$provide"; declare const $ROOT_ELEMENT = "$rootElement"; declare const $ROOT_SCOPE = "$rootScope"; declare const $SCOPE = "$scope"; declare const $TEMPLATE_CACHE = "$templateCache"; declare const $TEMPLATE_REQUEST = "$templateRequest"; declare const $$TESTABILITY = "$$testability"; declare const COMPILER_KEY = "$$angularCompiler"; declare const DOWNGRADED_MODULE_COUNT_KEY = "$$angularDowngradedModuleCount"; declare const GROUP_PROJECTABLE_NODES_KEY = "$$angularGroupProjectableNodes"; declare const INJECTOR_KEY = "$$angularInjector"; declare const LAZY_MODULE_REF = "$$angularLazyModuleRef"; declare const NG_ZONE_KEY = "$$angularNgZone"; declare const UPGRADE_APP_TYPE_KEY = "$$angularUpgradeAppType"; declare const REQUIRE_INJECTOR: string; declare const REQUIRE_NG_MODEL = "?ngModel"; declare const UPGRADE_MODULE_NAME = "$$UpgradeModule"; declare const constants_d_$$TESTABILITY: typeof $$TESTABILITY; declare const constants_d_$COMPILE: typeof $COMPILE; declare const constants_d_$CONTROLLER: typeof $CONTROLLER; declare const constants_d_$DELEGATE: typeof $DELEGATE; declare const constants_d_$EXCEPTION_HANDLER: typeof $EXCEPTION_HANDLER; declare const constants_d_$HTTP_BACKEND: typeof $HTTP_BACKEND; declare const constants_d_$INJECTOR: typeof $INJECTOR; declare const constants_d_$INTERVAL: typeof $INTERVAL; declare const constants_d_$PARSE: typeof $PARSE; declare const constants_d_$PROVIDE: typeof $PROVIDE; declare const constants_d_$ROOT_ELEMENT: typeof $ROOT_ELEMENT; declare const constants_d_$ROOT_SCOPE: typeof $ROOT_SCOPE; declare const constants_d_$SCOPE: typeof $SCOPE; declare const constants_d_$TEMPLATE_CACHE: typeof $TEMPLATE_CACHE; declare const constants_d_$TEMPLATE_REQUEST: typeof $TEMPLATE_REQUEST; declare const constants_d_COMPILER_KEY: typeof COMPILER_KEY; declare const constants_d_DOWNGRADED_MODULE_COUNT_KEY: typeof DOWNGRADED_MODULE_COUNT_KEY; declare const constants_d_GROUP_PROJECTABLE_NODES_KEY: typeof GROUP_PROJECTABLE_NODES_KEY; declare const constants_d_INJECTOR_KEY: typeof INJECTOR_KEY; declare const constants_d_LAZY_MODULE_REF: typeof LAZY_MODULE_REF; declare const constants_d_NG_ZONE_KEY: typeof NG_ZONE_KEY; declare const constants_d_REQUIRE_INJECTOR: typeof REQUIRE_INJECTOR; declare const constants_d_REQUIRE_NG_MODEL: typeof REQUIRE_NG_MODEL; declare const constants_d_UPGRADE_APP_TYPE_KEY: typeof UPGRADE_APP_TYPE_KEY; declare const constants_d_UPGRADE_MODULE_NAME: typeof UPGRADE_MODULE_NAME; declare namespace constants_d { export { constants_d_$$TESTABILITY as $$TESTABILITY, constants_d_$COMPILE as $COMPILE, constants_d_$CONTROLLER as $CONTROLLER, constants_d_$DELEGATE as $DELEGATE, constants_d_$EXCEPTION_HANDLER as $EXCEPTION_HANDLER, constants_d_$HTTP_BACKEND as $HTTP_BACKEND, constants_d_$INJECTOR as $INJECTOR, constants_d_$INTERVAL as $INTERVAL, constants_d_$PARSE as $PARSE, constants_d_$PROVIDE as $PROVIDE, constants_d_$ROOT_ELEMENT as $ROOT_ELEMENT, constants_d_$ROOT_SCOPE as $ROOT_SCOPE, constants_d_$SCOPE as $SCOPE, constants_d_$TEMPLATE_CACHE as $TEMPLATE_CACHE, constants_d_$TEMPLATE_REQUEST as $TEMPLATE_REQUEST, constants_d_COMPILER_KEY as COMPILER_KEY, constants_d_DOWNGRADED_MODULE_COUNT_KEY as DOWNGRADED_MODULE_COUNT_KEY, constants_d_GROUP_PROJECTABLE_NODES_KEY as GROUP_PROJECTABLE_NODES_KEY, constants_d_INJECTOR_KEY as INJECTOR_KEY, constants_d_LAZY_MODULE_REF as LAZY_MODULE_REF, constants_d_NG_ZONE_KEY as NG_ZONE_KEY, constants_d_REQUIRE_INJECTOR as REQUIRE_INJECTOR, constants_d_REQUIRE_NG_MODEL as REQUIRE_NG_MODEL, constants_d_UPGRADE_APP_TYPE_KEY as UPGRADE_APP_TYPE_KEY, constants_d_UPGRADE_MODULE_NAME as UPGRADE_MODULE_NAME, }; } /** * @fileoverview * While Angular only uses Trusted Types internally for the time being, * references to Trusted Types could leak into our public API, which would force * anyone compiling against @angular/upgrade to provide the @types/trusted-types * package in their compilation unit. * * Until https://github.com/microsoft/TypeScript/issues/30024 is resolved, we * will keep Angular's public API surface free of references to Trusted Types. * For internal and semi-private APIs that need to reference Trusted Types, the * minimal type definitions for the Trusted Types API provided by this module * should be used instead. They are marked as "declare" to prevent them from * being renamed by compiler optimization. * * Adapted from * https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/trusted-types/index.d.ts * but restricted to the API surface used within Angular, mimicking the approach * in packages/core/src/util/security/trusted_type_defs.ts. */ type TrustedHTML = string & { __brand__: 'TrustedHTML'; }; interface IBindingDestination { [key: string]: any; $onChanges?: (changes: SimpleChanges) => void; } interface IControllerInstance extends IBindingDestination { $doCheck?: () => void; $onDestroy?: () => void; $onInit?: () => void; $postLink?: () => void; } declare class UpgradeHelper { private name; readonly $injector: IInjectorService; readonly element: Element; readonly $element: IAugmentedJQuery; readonly directive: IDirective; private readonly $compile; private readonly $controller; constructor(injector: Injector, name: string, elementRef: ElementRef, directive?: IDirective); static getDirective($injector: IInjectorService, name: string): IDirective; static getTemplate($injector: IInjectorService, directive: IDirective, fetchRemoteTemplate?: boolean, $element?: IAugmentedJQuery): string | TrustedHTML | Promise<string | TrustedHTML>; buildController(controllerType: IController, $scope: IScope): any; compileTemplate(template?: string | TrustedHTML): ILinkFn; onDestroy($scope: IScope, controllerInstance?: any): void; prepareTransclusion(): ILinkFn | undefined; resolveAndBindRequiredControllers(controllerInstance: IControllerInstance | null): SingleOrListOrMap<IControllerInstance> | null; private compileHtml; private extractChildNodes; private getDirectiveRequire; private resolveRequire; } type upgrade_helper_d_IBindingDestination = IBindingDestination; type upgrade_helper_d_IControllerInstance = IControllerInstance; type upgrade_helper_d_UpgradeHelper = UpgradeHelper; declare const upgrade_helper_d_UpgradeHelper: typeof UpgradeHelper; declare namespace upgrade_helper_d { export { upgrade_helper_d_UpgradeHelper as UpgradeHelper }; export type { upgrade_helper_d_IBindingDestination as IBindingDestination, upgrade_helper_d_IControllerInstance as IControllerInstance }; } declare function onError(e: any): void; /** * Clean the jqLite/jQuery data on the element and all its descendants. * Equivalent to how jqLite/jQuery invoke `cleanData()` on an Element when removed: * https://github.com/angular/angular.js/blob/2e72ea13fa98bebf6ed4b5e3c45eaf5f990ed16f/src/jqLite.js#L349-L355 * https://github.com/jquery/jquery/blob/6984d1747623dbc5e87fd6c261a5b6b1628c107c/src/manipulation.js#L182 * * NOTE: * `cleanData()` will also invoke the AngularJS `$destroy` DOM event on the element: * https://github.com/angular/angular.js/blob/2e72ea13fa98bebf6ed4b5e3c45eaf5f990ed16f/src/Angular.js#L1932-L1945 * * @param node The DOM node whose data needs to be cleaned. */ declare function cleanData(node: Node): void; declare function controllerKey(name: string): string; /** * Destroy an AngularJS app given the app `$injector`. * * NOTE: Destroying an app is not officially supported by AngularJS, but try to do our best by * destroying `$rootScope` and clean the jqLite/jQuery d