feat(core): alias createNgModuleRef as createNgModule

This commit adds the `createNgModuleRef` function alias to the public API. The alias is called `createNgModule`. The `createNgModule` name is more consistent with the rest of the API surface, where functions that return `*Ref`s don't include the `Ref` into the function name, for example: `createPlatform`, `ViewContainerRef.createComponent`, etc.

DEPRECATED:

The `createNgModuleRef` is deprecated in favor of newly added `createNgModule` one.

aio/content/guide/deprecations.md

@@ -134,7 +134,7 @@ In the [API reference section](api) of this site, deprecated APIs are indicated
 | [`ModuleWithComponentFactories`](api/core/ModuleWithComponentFactories)                                    | none                                                                                                                                                              | v13                   | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context.                                                                                                                  |
 | [`Compiler`](api/core/Compiler)                                                                            | none                                                                                                                                                              | v13                   | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context.                                                                                                                  |
 | [`CompilerFactory`](api/core/CompilerFactory)                                                              | none                                                                                                                                                              | v13                   | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context.                                                                                                                  |
-| [`NgModuleFactory`](api/core/NgModuleFactory)                                                              | Use non-factory based framework APIs like [PlatformRef.bootstrapModule](api/core/PlatformRef#bootstrapModule) and [createNgModuleRef](api/core/createNgModuleRef) | v13                   | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context.                                                                                                                  |
+| [`NgModuleFactory`](api/core/NgModuleFactory)                                                              | Use non-factory based framework APIs like [PlatformRef.bootstrapModule](api/core/PlatformRef#bootstrapModule) and [createNgModule](api/core/createNgModule) | v13                   | Ivy JIT mode doesn't require accessing this symbol. See [JIT API changes due to ViewEngine deprecation](#jit-api-changes) for additional context.                                                                                                                  |
 | [Factory-based signature of `ViewContainerRef.createComponent`](api/core/ViewContainerRef#createComponent) | [Type-based signature of `ViewContainerRef.createComponent`](api/core/ViewContainerRef#createComponent)                                                           | v13                   | Angular no longer requires component factories to dynamically create components. Use different signature of the `createComponent` method, which allows passing Component class directly.                                                                           |
 | [`ComponentFactory`](api/core/ComponentFactory)                                                            | Use non-factory based framework APIs.                                                                                                                             | v13                   | Since Ivy, Component factories are not required. Angular provides other APIs where Component classes can be used directly.                                                                                                                                         |
 | [`ComponentFactoryResolver`](api/core/ComponentFactoryResolver)                                            | Use non-factory based framework APIs.                                                                                                                             | v13                   | Since Ivy, Component factories are not required, thus there is no need to resolve them.                                                                                                                                                                            |

aio/src/app/custom-elements/elements-loader.ts

@@ -1,4 +1,4 @@
-import { createNgModuleRef, Inject, Injectable, NgModuleRef, Type } from '@angular/core';
+import { createNgModule, Inject, Injectable, NgModuleRef, Type } from '@angular/core';
 import { ELEMENT_MODULE_LOAD_CALLBACKS_TOKEN, WithCustomElementComponent } from './element-registry';
 import { from, Observable, of } from 'rxjs';
 import { createCustomElement } from '@angular/elements';
@@ -46,7 +46,7 @@ export class ElementsLoader {
       const loadedAndRegistered =
         (modulePathLoader() as Promise<Type<WithCustomElementComponent>>)
           .then(elementModule => {
-            const elementModuleRef = createNgModuleRef(elementModule, this.moduleRef.injector);
+            const elementModuleRef = createNgModule(elementModule, this.moduleRef.injector);
             const injector = elementModuleRef.injector;
             const CustomElementComponent = elementModuleRef.instance.customElementComponent;
             const CustomElement = createCustomElement(CustomElementComponent, {injector});

goldens/public-api/core/index.md

@@ -303,7 +303,10 @@ export interface ContentChildrenDecorator {
 export function createEnvironmentInjector(providers: Array<Provider | ImportedNgModuleProviders>, parent: EnvironmentInjector, debugName?: string | null): EnvironmentInjector;
 
 // @public
-export function createNgModuleRef<T>(ngModule: Type<T>, parentInjector?: Injector): NgModuleRef<T>;
+export function createNgModule<T>(ngModule: Type<T>, parentInjector?: Injector): NgModuleRef<T>;
+
+// @public @deprecated
+export const createNgModuleRef: typeof createNgModule;
 
 // @public
 export function createPlatform(injector: Injector): PlatformRef;

packages/common/src/directives/ng_component_outlet.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {ComponentRef, createNgModuleRef, Directive, Injector, Input, NgModuleFactory, NgModuleRef, OnChanges, OnDestroy, SimpleChanges, Type, ViewContainerRef} from '@angular/core';
+import {ComponentRef, createNgModule, Directive, Injector, Input, NgModuleFactory, NgModuleRef, OnChanges, OnDestroy, SimpleChanges, Type, ViewContainerRef} from '@angular/core';
 
 
 /**
@@ -106,7 +106,7 @@ export class NgComponentOutlet implements OnChanges, OnDestroy {
         if (this._moduleRef) this._moduleRef.destroy();
 
         if (ngModule) {
-          this._moduleRef = createNgModuleRef(ngModule, getParentInjector(injector));
+          this._moduleRef = createNgModule(ngModule, getParentInjector(injector));
         } else if (ngModuleFactory) {
           this._moduleRef = ngModuleFactory.create(getParentInjector(injector));
         } else {

packages/compiler-cli/integrationtest/src/bootstrap.ts

@@ -6,10 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {createNgModuleRef} from '@angular/core';
+import {createNgModule} from '@angular/core';
 
 import {BasicComp} from './basic';
 import {MainModule} from './module';
 
-const ngModuleRef = createNgModuleRef(MainModule);
+const ngModuleRef = createNgModule(MainModule);
 ngModuleRef.instance.appRef.bootstrap(BasicComp);

packages/core/src/core.ts

@@ -36,7 +36,7 @@ export * from './core_private_export';
 export * from './core_render3_private_export';
 export {SecurityContext} from './sanitization/security';
 export {Sanitizer} from './sanitization/sanitizer';
-export {createNgModuleRef, createEnvironmentInjector} from './render3/ng_module_ref';
+export {createNgModule, createNgModuleRef, createEnvironmentInjector} from './render3/ng_module_ref';
 
 import {global} from './util/global';
 if (typeof ngDevMode !== 'undefined' && ngDevMode) {

packages/core/src/linker/ng_module_factory.ts

@@ -67,7 +67,7 @@ export interface InternalNgModuleRef<T> extends NgModuleRef<T> {
  * JIT mode. See [JIT API changes due to ViewEngine deprecation](guide/deprecations#jit-api-changes)
  * for additional context. Angular provides APIs that accept NgModule classes directly (such as
  * [PlatformRef.bootstrapModule](api/core/PlatformRef#bootstrapModule) and
- * [createNgModuleRef](api/core/createNgModuleRef)), consider switching to those APIs instead of
+ * [createNgModule](api/core/createNgModule)), consider switching to those APIs instead of
  * using factory-based ones.
  */
 export abstract class NgModuleFactory<T> {

packages/core/src/linker/view_container_ref.ts

@@ -401,7 +401,7 @@ const R3ViewContainerRef = class ViewContainerRef extends VE_ViewContainerRef {
       // so that a component can use DI tokens provided in MgModules. For this reason, we can not
       // rely on the provided injector, since it might be detached from the DI tree (for example, if
       // it was created via `Injector.create` without specifying a parent injector, or if an
-      // injector is retrieved from an `NgModuleRef` created via `createNgModuleRef` using an
+      // injector is retrieved from an `NgModuleRef` created via `createNgModule` using an
       // NgModule outside of a module tree). Instead, we always use `ViewContainerRef`'s parent
       // injector, which is normally connected to the DI tree, which includes module injector
       // subtree.

packages/core/src/render3/ng_module_ref.ts

@@ -24,15 +24,26 @@ import {maybeUnwrapFn} from './util/misc_utils';
 
 /**
  * Returns a new NgModuleRef instance based on the NgModule class and parent injector provided.
+ *
  * @param ngModule NgModule class.
  * @param parentInjector Optional injector instance to use as a parent for the module injector. If
  *     not provided, `NullInjector` will be used instead.
+ * @returns NgModuleRef that represents an NgModule instance.
+ *
  * @publicApi
  */
-export function createNgModuleRef<T>(
+export function createNgModule<T>(
     ngModule: Type<T>, parentInjector?: Injector): viewEngine_NgModuleRef<T> {
   return new NgModuleRef<T>(ngModule, parentInjector ?? null);
 }
+
+/**
+ * The `createNgModule` function alias for backwards-compatibility.
+ * Please avoid using it directly and use `createNgModule` instead.
+ *
+ * @deprecated Use `createNgModule` instead.
+ */
+export const createNgModuleRef = createNgModule;
 export class NgModuleRef<T> extends viewEngine_NgModuleRef<T> implements InternalNgModuleRef<T>,
                                                                          EnvironmentInjector {
   // tslint:disable-next-line:require-internal-with-underscore

packages/core/test/acceptance/ng_module_spec.ts

@@ -7,7 +7,7 @@
  */
 
 import {CommonModule} from '@angular/common';
-import {Component, createNgModuleRef, CUSTOM_ELEMENTS_SCHEMA, destroyPlatform, Directive, Injectable, InjectionToken, NgModule, NgModuleRef, NO_ERRORS_SCHEMA, Pipe, ɵsetClassMetadata as setClassMetadata, ɵɵdefineComponent as defineComponent, ɵɵdefineInjector as defineInjector, ɵɵdefineNgModule as defineNgModule, ɵɵelement as element, ɵɵproperty as property} from '@angular/core';
+import {Component, createNgModule, CUSTOM_ELEMENTS_SCHEMA, destroyPlatform, Directive, Injectable, InjectionToken, NgModule, NgModuleRef, NO_ERRORS_SCHEMA, Pipe, ɵsetClassMetadata as setClassMetadata, ɵɵdefineComponent as defineComponent, ɵɵdefineInjector as defineInjector, ɵɵdefineNgModule as defineNgModule, ɵɵelement as element, ɵɵproperty as property} from '@angular/core';
 import {KNOWN_CONTROL_FLOW_DIRECTIVES} from '@angular/core/src/render3/instructions/element_validation';
 import {TestBed} from '@angular/core/testing';
 import {BrowserModule} from '@angular/platform-browser';
@@ -975,7 +975,7 @@ describe('NgModule', () => {
     });
   });
 
-  describe('createNgModuleRef function', () => {
+  describe('createNgModule function', () => {
     it('should create an NgModuleRef instance', () => {
       const TOKEN_A = new InjectionToken('A');
       const TOKEN_B = new InjectionToken('B');
@@ -996,14 +996,13 @@ describe('NgModule', () => {
       }
 
       // Simple case, just passing NgModule class.
-      const ngModuleRef = createNgModuleRef(AppModule);
+      const ngModuleRef = createNgModule(AppModule);
       expect(ngModuleRef).toBeAnInstanceOf(NgModuleRef);
       expect(ngModuleRef.injector.get(TOKEN_A)).toBe('TokenValueA');
       expect(ngModuleRef.injector.get(TOKEN_B, null)).toBe(null);
 
       // Both NgModule and parent Injector are present.
-      const ngModuleRef2 =
-          createNgModuleRef(ChildModule, ngModuleRef.injector /* parent injector */);
+      const ngModuleRef2 = createNgModule(ChildModule, ngModuleRef.injector /* parent injector */);
       expect(ngModuleRef2).toBeAnInstanceOf(NgModuleRef);
       expect(ngModuleRef2.injector.get(TOKEN_A)).toBe('TokenValueA');
       expect(ngModuleRef2.injector.get(TOKEN_B)).toBe('TokenValueB');