@angular/upgrade
Version:
Angular - the library for easing update from v1 to v2
1,087 lines (1,073 loc) • 53.5 kB
TypeScript
/**
* @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