feat(upgrade): more closely align UpgradeModule#bootstrap() with angular.bootstrap() (angular#46214)

Previously, [UpgradeModule#bootstrap()][1], while being a replacement
for and accepting the same arguments as [angular.bootstrap()][2], did
not return the same value as `angular.bootstrap()` (i.e. the AngularJS
injector in most cases). This made it less straight forward to migrate
some usecases that relied on the return value of `.bootstrap()`. The
work-around was to access the injector via [UpgradeModule#$injector][3]
(after the app had been bootstrapped with `UpgradeModule#bootstrap()`).

This commit addresses this by ensuring `UpgradeModule#bootstrap()`
returns the same value as `angular.bootstrap()`, making it easier to
replace the latter with the former.

[1]: https://angular.io/api/upgrade/static/UpgradeModule#bootstrap
[2]: https://docs.angularjs.org/api/ng/function/angular.bootstrap
[3]: https://angular.io/api/upgrade/static/UpgradeModule#%24injector

Fixes angular#46211

PR Close angular#46214

Author: gkalpak

goldens/public-api/upgrade/static/index.md

@@ -75,7 +75,7 @@ export class UpgradeModule {
     injector: Injector,
     ngZone: NgZone,
     platformRef: PlatformRef);
-    bootstrap(element: Element, modules?: string[], config?: any): void;
+    bootstrap(element: Element, modules?: string[], config?: any): any;
     injector: Injector;
     ngZone: NgZone;
     // (undocumented)

packages/upgrade/static/src/upgrade_module.ts

@@ -91,11 +91,11 @@ import {NgAdapterInjector} from './util';
  * 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
+ * * 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
+ * * 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.
@@ -170,9 +170,12 @@ export class UpgradeModule {
    * @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 /*angular.IAngularBootstrapConfig*/) {
+      element: Element, modules: string[] = [], config?: any /*angular.IAngularBootstrapConfig*/):
+      any /*ReturnType<typeof angular.bootstrap>*/ {
     const INIT_MODULE_NAME = UPGRADE_MODULE_NAME + '.init';
 
     // Create an ng1 module to bootstrap
@@ -303,9 +306,7 @@ export class UpgradeModule {
     windowAngular.resumeBootstrap = undefined;
 
     // Bootstrap the AngularJS application inside our zone
-    this.ngZone.run(() => {
-      bootstrap(element, [upgradeModule.name], config);
-    });
+    const returnValue = this.ngZone.run(() => bootstrap(element, [upgradeModule.name], config));
 
     // Patch resumeBootstrap() to run inside the ngZone
     if (windowAngular.resumeBootstrap) {
@@ -317,5 +318,7 @@ export class UpgradeModule {
         return ngZone.run(() => windowAngular.resumeBootstrap.apply(this, args));
       };
     }
+
+    return returnValue;
   }
 }

packages/upgrade/static/test/integration/upgrade_module_spec.ts

@@ -125,6 +125,29 @@ withEachNg1Version(() => {
 
         expect(bootstrapSpy).toHaveBeenCalledOnceWith(element, jasmine.any(Array), config);
       });
+
+      it('should forward the return value of `angular.bootstrap()`', async () => {
+        // Set up spies.
+        const bootstrapSpy = spyOn(getAngularJSGlobal(), 'bootstrap').and.callThrough();
+
+        // Define `Ng2Module`.
+        @NgModule({
+          imports: [BrowserModule, UpgradeModule],
+        })
+        class Ng2Module {
+          ngDoBootstrap() {}
+        }
+
+        // Bootstrap the ng2 app.
+        const appRef = await platformBrowserDynamic().bootstrapModule(Ng2Module);
+        const upgrade = appRef.injector.get(UpgradeModule);
+
+        // Bootstrap the hybrid app.
+        const retValue = upgrade.bootstrap(html(`<ng2></ng2>`), []);
+
+        expect(retValue).toBe(bootstrapSpy.calls.mostRecent().returnValue);
+        expect(retValue).toBe(upgrade.$injector);  // In most cases, it will be the ng1 injector.
+      });
     });
   });
 });