@angular/upgrade 13.1.0-next.1 → 13.2.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular/upgrade",
-  "version": "13.1.0-next.1",
+  "version": "13.2.0-next.0",
   "description": "Angular - the library for easing update from v1 to v2",
   "author": "angular",
   "license": "MIT",
@@ -11,10 +11,10 @@
     "tslib": "^2.3.0"
   },
   "peerDependencies": {
-    "@angular/core": "13.1.0-next.1",
-    "@angular/compiler": "13.1.0-next.1",
-    "@angular/platform-browser": "13.1.0-next.1",
-    "@angular/platform-browser-dynamic": "13.1.0-next.1"
+    "@angular/core": "13.2.0-next.0",
+    "@angular/compiler": "13.2.0-next.0",
+    "@angular/platform-browser": "13.2.0-next.0",
+    "@angular/platform-browser-dynamic": "13.2.0-next.0"
   },
   "repository": {
     "type": "git",

package/static/static.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.1
+ * @license Angular v13.2.0-next.0
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -165,6 +165,8 @@ export declare function downgradeInjectable(token: any, downgradedModule?: strin
  * `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
@@ -255,7 +257,125 @@ export declare function downgradeInjectable(token: any, downgradedModule?: strin
  *
  * @publicApi
  */
-export declare function downgradeModule<T>(moduleOrBootstrapFn: Type<T> | NgModuleFactory<T> | ((extraProviders: StaticProvider[]) => Promise<NgModuleRef<T>>)): string;
+export 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](guide/upgrade-performance).
+ *
+ * @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="alert is-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](guide/upgrade-performance).
+ *
+ * <div class="alert is-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 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.
+ */
+export declare function downgradeModule<T>(moduleOrBootstrapFn: NgModuleFactory<T>): string;
 
 /**
  * Returns the current AngularJS global.

package/static/testing/testing.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.1
+ * @license Angular v13.2.0-next.0
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */

package/upgrade.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.1.0-next.1
+ * @license Angular v13.2.0-next.0
  * (c) 2010-2021 Google LLC. https://angular.io/
  * License: MIT
  */