@@ -40,6 +40,240 @@ let moduleUid = 0;
4040 * `downgradeModule()` requires either an `NgModuleFactory`, `NgModule` class or a function:
4141 * - `NgModuleFactory`: If you pass an `NgModuleFactory`, it will be used to instantiate a module
4242 * using `platformBrowser`'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}.
43+ * NOTE: this type of the argument is deprecated. Please either provide an `NgModule` class or a
44+ * bootstrap function instead.
45+ * - `NgModule` class: If you pass an NgModule class, it will be used to instantiate a module
46+ * using `platformBrowser`'s {@link PlatformRef#bootstrapModule bootstrapModule()}.
47+ * - `Function`: If you pass a function, it is expected to return a promise resolving to an
48+ * `NgModuleRef`. The function is called with an array of extra {@link StaticProvider Providers}
49+ * that are expected to be available from the returned `NgModuleRef`'s `Injector`.
50+ *
51+ * `downgradeModule()` returns the name of the created AngularJS wrapper module. You can use it to
52+ * declare a dependency in your main AngularJS module.
53+ *
54+ * {@example upgrade/static/ts/lite/module.ts region="basic-how-to"}
55+ *
56+ * For more details on how to use `downgradeModule()` see
57+ * [Upgrading for Performance](guide/upgrade-performance).
58+ *
59+ * @usageNotes
60+ *
61+ * Apart from `UpgradeModule`, you can use the rest of the `upgrade/static` helpers as usual to
62+ * build a hybrid application. Note that the Angular pieces (e.g. downgraded services) will not be
63+ * available until the downgraded module has been bootstrapped, i.e. by instantiating a downgraded
64+ * component.
65+ *
66+ * <div class="alert is-important">
67+ *
68+ * You cannot use `downgradeModule()` and `UpgradeModule` in the same hybrid application.<br />
69+ * Use one or the other.
70+ *
71+ * </div>
72+ *
73+ * ### Differences with `UpgradeModule`
74+ *
75+ * Besides their different API, there are two important internal differences between
76+ * `downgradeModule()` and `UpgradeModule` that affect the behavior of hybrid applications:
77+ *
78+ * 1. Unlike `UpgradeModule`, `downgradeModule()` does not bootstrap the main AngularJS module
79+ * inside the {@link NgZone Angular zone}.
80+ * 2. Unlike `UpgradeModule`, `downgradeModule()` does not automatically run a
81+ * [$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest) when changes are
82+ * detected in the Angular part of the application.
83+ *
84+ * What this means is that applications using `UpgradeModule` will run change detection more
85+ * frequently in order to ensure that both frameworks are properly notified about possible changes.
86+ * This will inevitably result in more change detection runs than necessary.
87+ *
88+ * `downgradeModule()`, on the other side, does not try to tie the two change detection systems as
89+ * tightly, restricting the explicit change detection runs only to cases where it knows it is
90+ * necessary (e.g. when the inputs of a downgraded component change). This improves performance,
91+ * especially in change-detection-heavy applications, but leaves it up to the developer to manually
92+ * notify each framework as needed.
93+ *
94+ * For a more detailed discussion of the differences and their implications, see
95+ * [Upgrading for Performance](guide/upgrade-performance).
96+ *
97+ * <div class="alert is-helpful">
98+ *
99+ * You can manually trigger a change detection run in AngularJS using
100+ * [scope.$apply(...)](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply) or
101+ * [$rootScope.$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest).
102+ *
103+ * You can manually trigger a change detection run in Angular using {@link NgZone#run
104+ * ngZone.run(...)}.
105+ *
106+ * </div>
107+ *
108+ * ### Downgrading multiple modules
109+ *
110+ * It is possible to downgrade multiple modules and include them in an AngularJS application. In
111+ * that case, each downgraded module will be bootstrapped when an associated downgraded component or
112+ * injectable needs to be instantiated.
113+ *
114+ * Things to keep in mind, when downgrading multiple modules:
115+ *
116+ * - Each downgraded component/injectable needs to be explicitly associated with a downgraded
117+ * module. See `downgradeComponent()` and `downgradeInjectable()` for more details.
118+ *
119+ * - If you want some injectables to be shared among all downgraded modules, you can provide them as
120+ * `StaticProvider`s, when creating the `PlatformRef` (e.g. via `platformBrowser` or
121+ * `platformBrowserDynamic`).
122+ *
123+ * - When using {@link PlatformRef#bootstrapmodule `bootstrapModule()`} or
124+ * {@link PlatformRef#bootstrapmodulefactory `bootstrapModuleFactory()`} to bootstrap the
125+ * downgraded modules, each one is considered a "root" module. As a consequence, a new instance
126+ * will be created for every injectable provided in `"root"` (via
127+ * {@link Injectable#providedIn `providedIn`}).
128+ * If this is not your intention, you can have a shared module (that will act as act as the "root"
129+ * module) and create all downgraded modules using that module's injector:
130+ *
131+ * {@example upgrade/static/ts/lite-multi-shared/module.ts region="shared-root-module"}
132+ *
133+ * @publicApi
134+ */
135+ export function downgradeModule < T > ( moduleOrBootstrapFn : Type < T > | (
136+ ( extraProviders : StaticProvider [ ] ) => Promise < NgModuleRef < T > > ) ) : string ;
137+ /**
138+ * @description
139+ *
140+ * A helper function for creating an AngularJS module that can bootstrap an Angular module
141+ * "on-demand" (possibly lazily) when a {@link downgradeComponent downgraded component} needs to be
142+ * instantiated.
143+ *
144+ * *Part of the [upgrade/static](api?query=upgrade/static) library for hybrid upgrade apps that
145+ * support AOT compilation.*
146+ *
147+ * It allows loading/bootstrapping the Angular part of a hybrid application lazily and not having to
148+ * pay the cost up-front. For example, you can have an AngularJS application that uses Angular for
149+ * specific routes and only instantiate the Angular modules if/when the user visits one of these
150+ * routes.
151+ *
152+ * The Angular module will be bootstrapped once (when requested for the first time) and the same
153+ * reference will be used from that point onwards.
154+ *
155+ * `downgradeModule()` requires either an `NgModuleFactory`, `NgModule` class or a function:
156+ * - `NgModuleFactory`: If you pass an `NgModuleFactory`, it will be used to instantiate a module
157+ * using `platformBrowser`'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}.
158+ * NOTE: this type of the argument is deprecated. Please either provide an `NgModule` class or a
159+ * bootstrap function instead.
160+ * - `NgModule` class: If you pass an NgModule class, it will be used to instantiate a module
161+ * using `platformBrowser`'s {@link PlatformRef#bootstrapModule bootstrapModule()}.
162+ * - `Function`: If you pass a function, it is expected to return a promise resolving to an
163+ * `NgModuleRef`. The function is called with an array of extra {@link StaticProvider Providers}
164+ * that are expected to be available from the returned `NgModuleRef`'s `Injector`.
165+ *
166+ * `downgradeModule()` returns the name of the created AngularJS wrapper module. You can use it to
167+ * declare a dependency in your main AngularJS module.
168+ *
169+ * {@example upgrade/static/ts/lite/module.ts region="basic-how-to"}
170+ *
171+ * For more details on how to use `downgradeModule()` see
172+ * [Upgrading for Performance](guide/upgrade-performance).
173+ *
174+ * @usageNotes
175+ *
176+ * Apart from `UpgradeModule`, you can use the rest of the `upgrade/static` helpers as usual to
177+ * build a hybrid application. Note that the Angular pieces (e.g. downgraded services) will not be
178+ * available until the downgraded module has been bootstrapped, i.e. by instantiating a downgraded
179+ * component.
180+ *
181+ * <div class="alert is-important">
182+ *
183+ * You cannot use `downgradeModule()` and `UpgradeModule` in the same hybrid application.<br />
184+ * Use one or the other.
185+ *
186+ * </div>
187+ *
188+ * ### Differences with `UpgradeModule`
189+ *
190+ * Besides their different API, there are two important internal differences between
191+ * `downgradeModule()` and `UpgradeModule` that affect the behavior of hybrid applications:
192+ *
193+ * 1. Unlike `UpgradeModule`, `downgradeModule()` does not bootstrap the main AngularJS module
194+ * inside the {@link NgZone Angular zone}.
195+ * 2. Unlike `UpgradeModule`, `downgradeModule()` does not automatically run a
196+ * [$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest) when changes are
197+ * detected in the Angular part of the application.
198+ *
199+ * What this means is that applications using `UpgradeModule` will run change detection more
200+ * frequently in order to ensure that both frameworks are properly notified about possible changes.
201+ * This will inevitably result in more change detection runs than necessary.
202+ *
203+ * `downgradeModule()`, on the other side, does not try to tie the two change detection systems as
204+ * tightly, restricting the explicit change detection runs only to cases where it knows it is
205+ * necessary (e.g. when the inputs of a downgraded component change). This improves performance,
206+ * especially in change-detection-heavy applications, but leaves it up to the developer to manually
207+ * notify each framework as needed.
208+ *
209+ * For a more detailed discussion of the differences and their implications, see
210+ * [Upgrading for Performance](guide/upgrade-performance).
211+ *
212+ * <div class="alert is-helpful">
213+ *
214+ * You can manually trigger a change detection run in AngularJS using
215+ * [scope.$apply(...)](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$apply) or
216+ * [$rootScope.$digest()](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$digest).
217+ *
218+ * You can manually trigger a change detection run in Angular using {@link NgZone#run
219+ * ngZone.run(...)}.
220+ *
221+ * </div>
222+ *
223+ * ### Downgrading multiple modules
224+ *
225+ * It is possible to downgrade multiple modules and include them in an AngularJS application. In
226+ * that case, each downgraded module will be bootstrapped when an associated downgraded component or
227+ * injectable needs to be instantiated.
228+ *
229+ * Things to keep in mind, when downgrading multiple modules:
230+ *
231+ * - Each downgraded component/injectable needs to be explicitly associated with a downgraded
232+ * module. See `downgradeComponent()` and `downgradeInjectable()` for more details.
233+ *
234+ * - If you want some injectables to be shared among all downgraded modules, you can provide them as
235+ * `StaticProvider`s, when creating the `PlatformRef` (e.g. via `platformBrowser` or
236+ * `platformBrowserDynamic`).
237+ *
238+ * - When using {@link PlatformRef#bootstrapmodule `bootstrapModule()`} or
239+ * {@link PlatformRef#bootstrapmodulefactory `bootstrapModuleFactory()`} to bootstrap the
240+ * downgraded modules, each one is considered a "root" module. As a consequence, a new instance
241+ * will be created for every injectable provided in `"root"` (via
242+ * {@link Injectable#providedIn `providedIn`}).
243+ * If this is not your intention, you can have a shared module (that will act as act as the "root"
244+ * module) and create all downgraded modules using that module's injector:
245+ *
246+ * {@example upgrade/static/ts/lite-multi-shared/module.ts region="shared-root-module"}
247+ *
248+ * @publicApi
249+ *
250+ * @deprecated Passing `NgModuleFactory` as the `downgradeModule` function argument is deprecated,
251+ * please pass an NgModule class reference instead.
252+ */
253+ export function downgradeModule < T > ( moduleOrBootstrapFn : NgModuleFactory < T > ) : string ;
254+ /**
255+ * @description
256+ *
257+ * A helper function for creating an AngularJS module that can bootstrap an Angular module
258+ * "on-demand" (possibly lazily) when a {@link downgradeComponent downgraded component} needs to be
259+ * instantiated.
260+ *
261+ * *Part of the [upgrade/static](api?query=upgrade/static) library for hybrid upgrade apps that
262+ * support AOT compilation.*
263+ *
264+ * It allows loading/bootstrapping the Angular part of a hybrid application lazily and not having to
265+ * pay the cost up-front. For example, you can have an AngularJS application that uses Angular for
266+ * specific routes and only instantiate the Angular modules if/when the user visits one of these
267+ * routes.
268+ *
269+ * The Angular module will be bootstrapped once (when requested for the first time) and the same
270+ * reference will be used from that point onwards.
271+ *
272+ * `downgradeModule()` requires either an `NgModuleFactory`, `NgModule` class or a function:
273+ * - `NgModuleFactory`: If you pass an `NgModuleFactory`, it will be used to instantiate a module
274+ * using `platformBrowser`'s {@link PlatformRef#bootstrapModuleFactory bootstrapModuleFactory()}.
275+ * NOTE: this type of the argument is deprecated. Please either provide an `NgModule` class or a
276+ * bootstrap function instead.
43277 * - `NgModule` class: If you pass an NgModule class, it will be used to instantiate a module
44278 * using `platformBrowser`'s {@link PlatformRef#bootstrapModule bootstrapModule()}.
45279 * - `Function`: If you pass a function, it is expected to return a promise resolving to an
0 commit comments