feat(core): introduce EnvironmentProviders wrapper type

goldens/public-api/core/index.md

@@ -324,7 +324,7 @@ export function createComponent<C>(component: Type<C>, options: {
 }): ComponentRef<C>;
 
 // @public
-export function createEnvironmentInjector(providers: Array<Provider | ImportedNgModuleProviders>, parent: EnvironmentInjector, debugName?: string | null): EnvironmentInjector;
+export function createEnvironmentInjector(providers: Array<Provider | EnvironmentProviders>, parent: EnvironmentInjector, debugName?: string | null): EnvironmentInjector;
 
 // @public
 export function createNgModule<T>(ngModule: Type<T>, parentInjector?: Injector): NgModuleRef<T>;
@@ -504,6 +504,11 @@ export abstract class EnvironmentInjector implements Injector {
     abstract runInContext<ReturnT>(fn: () => ReturnT): ReturnT;
 }
 
+// @public
+export type EnvironmentProviders = {
+    ɵbrand: 'EnvironmentProviders';
+};
+
 // @public
 export class ErrorHandler {
     // (undocumented)
@@ -622,14 +627,11 @@ export interface HostListenerDecorator {
     new (eventName: string, args?: string[]): any;
 }
 
-// @public
-export interface ImportedNgModuleProviders {
-    // (undocumented)
-    ɵproviders: Provider[];
-}
+// @public @deprecated
+export type ImportedNgModuleProviders = EnvironmentProviders;
 
 // @public
-export function importProvidersFrom(...sources: ImportProvidersSource[]): ImportedNgModuleProviders;
+export function importProvidersFrom(...sources: ImportProvidersSource[]): EnvironmentProviders;
 
 // @public
 export type ImportProvidersSource = Type<unknown> | ModuleWithProviders<unknown> | Array<ImportProvidersSource>;
@@ -873,6 +875,9 @@ export class KeyValueDiffers {
 // @public
 export const LOCALE_ID: InjectionToken<string>;
 
+// @public
+export function makeEnvironmentProviders(providers: Provider[]): EnvironmentProviders;
+
 // @public
 export enum MissingTranslationStrategy {
     // (undocumented)
@@ -897,7 +902,7 @@ export interface ModuleWithProviders<T> {
     // (undocumented)
     ngModule: Type<T>;
     // (undocumented)
-    providers?: Provider[];
+    providers?: Array<Provider | EnvironmentProviders>;
 }
 
 // @public
@@ -913,7 +918,7 @@ export interface NgModule {
     id?: string;
     imports?: Array<Type<any> | ModuleWithProviders<{}> | any[]>;
     jit?: true;
-    providers?: Provider[];
+    providers?: Array<Provider | EnvironmentProviders>;
     schemas?: Array<SchemaMetadata | any[]>;
 }
 

goldens/public-api/platform-browser/index.md

@@ -8,9 +8,9 @@ import { ApplicationRef } from '@angular/core';
 import { ComponentRef } from '@angular/core';
 import { DebugElement } from '@angular/core';
 import { DebugNode } from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
 import * as i0 from '@angular/core';
 import * as i1 from '@angular/common';
-import { ImportedNgModuleProviders } from '@angular/core';
 import { InjectionToken } from '@angular/core';
 import { ModuleWithProviders } from '@angular/core';
 import { NgZone } from '@angular/core';
@@ -25,7 +25,7 @@ import { Version } from '@angular/core';
 
 // @public
 export interface ApplicationConfig {
-    providers: Array<Provider | ImportedNgModuleProviders>;
+    providers: Array<Provider | EnvironmentProviders>;
 }
 
 // @public

goldens/public-api/platform-server/index.md

@@ -4,11 +4,11 @@
 
 ```ts
 
+import { EnvironmentProviders } from '@angular/core';
 import * as i0 from '@angular/core';
 import * as i1 from '@angular/common/http';
 import * as i2 from '@angular/platform-browser/animations';
 import * as i3 from '@angular/platform-browser';
-import { ImportedNgModuleProviders } from '@angular/core';
 import { InjectionToken } from '@angular/core';
 import { NgModuleFactory } from '@angular/core';
 import { PlatformRef } from '@angular/core';
@@ -53,7 +53,7 @@ export function renderApplication<T>(rootComponent: Type<T>, options: {
     appId: string;
     document?: string | Document;
     url?: string;
-    providers?: Array<Provider | ImportedNgModuleProviders>;
+    providers?: Array<Provider | EnvironmentProviders>;
     platformProviders?: Provider[];
 }): Promise<string>;
 

goldens/public-api/router/index.md

@@ -11,9 +11,9 @@ import { ComponentFactoryResolver } from '@angular/core';
 import { ComponentRef } from '@angular/core';
 import { ElementRef } from '@angular/core';
 import { EnvironmentInjector } from '@angular/core';
+import { EnvironmentProviders } from '@angular/core';
 import { EventEmitter } from '@angular/core';
 import * as i0 from '@angular/core';
-import { ImportedNgModuleProviders } from '@angular/core';
 import { InjectionToken } from '@angular/core';
 import { Injector } from '@angular/core';
 import { Location as Location_2 } from '@angular/common';
@@ -524,7 +524,7 @@ export abstract class PreloadingStrategy {
 export const PRIMARY_OUTLET = "primary";
 
 // @public
-export function provideRouter(routes: Routes, ...features: RouterFeatures[]): Provider[];
+export function provideRouter(routes: Routes, ...features: RouterFeatures[]): EnvironmentProviders;
 
 // @public
 export function provideRoutes(routes: Routes): Provider[];
@@ -596,7 +596,7 @@ export interface Route {
     outlet?: string;
     path?: string;
     pathMatch?: 'prefix' | 'full';
-    providers?: Array<Provider | ImportedNgModuleProviders>;
+    providers?: Array<Provider | EnvironmentProviders>;
     redirectTo?: string;
     resolve?: ResolveData;
     runGuardsAndResolvers?: RunGuardsAndResolvers;

packages/core/src/application_ref.ts

@@ -18,7 +18,7 @@ import {Console} from './console';
 import {Injectable} from './di/injectable';
 import {InjectionToken} from './di/injection_token';
 import {Injector} from './di/injector';
-import {ImportedNgModuleProviders, Provider, StaticProvider} from './di/interface/provider';
+import {EnvironmentProviders, Provider, StaticProvider} from './di/interface/provider';
 import {EnvironmentInjector} from './di/r3_injector';
 import {INJECTOR_SCOPE} from './di/scope';
 import {ErrorHandler} from './error_handler';
@@ -189,7 +189,7 @@ export function runPlatformInitializers(injector: Injector): void {
  */
 export function internalCreateApplication(config: {
   rootComponent?: Type<unknown>,
-  appProviders?: Array<Provider|ImportedNgModuleProviders>,
+  appProviders?: Array<Provider|EnvironmentProviders>,
   platformProviders?: Provider[],
 }): Promise<ApplicationRef> {
   const {rootComponent, appProviders, platformProviders} = config;

packages/core/src/core_private_export.ts

@@ -14,6 +14,7 @@ export {Console as ɵConsole} from './console';
 export {getDebugNodeR2 as ɵgetDebugNodeR2} from './debug/debug_node';
 export {convertToBitFlags as ɵconvertToBitFlags, setCurrentInjector as ɵsetCurrentInjector} from './di/injector_compatibility';
 export {getInjectableDef as ɵgetInjectableDef, ɵɵInjectableDeclaration, ɵɵInjectorDef} from './di/interface/defs';
+export {InternalEnvironmentProviders as ɵInternalEnvironmentProviders, isEnvironmentProviders as ɵisEnvironmentProviders} from './di/interface/provider';
 export {INJECTOR_SCOPE as ɵINJECTOR_SCOPE} from './di/scope';
 export {formatRuntimeError as ɵformatRuntimeError, RuntimeError as ɵRuntimeError} from './errors';
 export {CurrencyIndex as ɵCurrencyIndex, ExtraLocaleDataIndex as ɵExtraLocaleDataIndex, findLocaleData as ɵfindLocaleData, getLocaleCurrencyCode as ɵgetLocaleCurrencyCode, getLocalePluralCase as ɵgetLocalePluralCase, LocaleDataIndex as ɵLocaleDataIndex, registerLocaleData as ɵregisterLocaleData, unregisterAllLocaleData as ɵunregisterLocaleData} from './i18n/locale_data_api';

packages/core/src/di/index.ts

@@ -19,14 +19,14 @@ export {forwardRef, resolveForwardRef, ForwardRefFn} from './forward_ref';
 export {Injectable, InjectableDecorator, InjectableProvider} from './injectable';
 export {Injector} from './injector';
 export {EnvironmentInjector} from './r3_injector';
-export {importProvidersFrom, ImportProvidersSource} from './provider_collection';
+export {importProvidersFrom, ImportProvidersSource, makeEnvironmentProviders} from './provider_collection';
 export {ENVIRONMENT_INITIALIZER} from './initializer_token';
 export {ProviderToken} from './provider_token';
 export {ɵɵinject, inject, ɵɵinvalidFactoryDep} from './injector_compatibility';
 export {InjectOptions} from './interface/injector';
 export {INJECTOR} from './injector_token';
 export {ReflectiveInjector} from './reflective_injector';
-export {ClassProvider, ModuleWithProviders, ClassSansProvider, ImportedNgModuleProviders, ConstructorProvider, ConstructorSansProvider, ExistingProvider, ExistingSansProvider, FactoryProvider, FactorySansProvider, Provider, StaticClassProvider, StaticClassSansProvider, StaticProvider, TypeProvider, ValueProvider, ValueSansProvider} from './interface/provider';
+export {ClassProvider, ModuleWithProviders, ClassSansProvider, ImportedNgModuleProviders, ConstructorProvider, EnvironmentProviders, ConstructorSansProvider, ExistingProvider, ExistingSansProvider, FactoryProvider, FactorySansProvider, Provider, StaticClassProvider, StaticClassSansProvider, StaticProvider, TypeProvider, ValueProvider, ValueSansProvider} from './interface/provider';
 export {ResolvedReflectiveFactory, ResolvedReflectiveProvider} from './reflective_provider';
 export {ReflectiveKey} from './reflective_key';
 export {InjectionToken} from './injection_token';

packages/core/src/di/interface/defs.ts

@@ -9,7 +9,7 @@
 import {Type} from '../../interface/type';
 import {getClosureSafeProperty} from '../../util/property';
 
-import {ClassProvider, ConstructorProvider, ExistingProvider, FactoryProvider, StaticClassProvider, ValueProvider} from './provider';
+import {ClassProvider, ConstructorProvider, EnvironmentProviders, ExistingProvider, FactoryProvider, StaticClassProvider, ValueProvider} from './provider';
 
 
 
@@ -73,7 +73,7 @@ export interface ɵɵInjectorDef<T> {
   // TODO(alxhub): Narrow down the type here once decorators properly change the return type of the
   // class they are decorating (to add the ɵprov property for example).
   providers: (Type<any>|ValueProvider|ExistingProvider|FactoryProvider|ConstructorProvider|
-              StaticClassProvider|ClassProvider|any[])[];
+              StaticClassProvider|ClassProvider|EnvironmentProviders|any[])[];
 
   imports: (InjectorType<any>|InjectorTypeWithProviders<any>)[];
 }
@@ -119,7 +119,7 @@ export interface InjectorType<T> extends Type<T> {
 export interface InjectorTypeWithProviders<T> {
   ngModule: InjectorType<T>;
   providers?: (Type<any>|ValueProvider|ExistingProvider|FactoryProvider|ConstructorProvider|
-               StaticClassProvider|ClassProvider|any[])[];
+               StaticClassProvider|ClassProvider|EnvironmentProviders|any[])[];
 }
 
 

packages/core/src/di/interface/provider.ts

@@ -332,6 +332,41 @@ export interface ClassProvider extends ClassSansProvider {
 export type Provider = TypeProvider|ValueProvider|ClassProvider|ConstructorProvider|
     ExistingProvider|FactoryProvider|any[];
 
+/**
+ * Encapsulated `Provider`s that are only accepted during creation of an `EnvironmentInjector` (e.g.
+ * in an `NgModule`).
+ *
+ * Using this wrapper type prevents providers which are only designed to work in
+ * application/environment injectors from being accidentally included in
+ * `@Component.providers` and ending up in a component injector.
+ *
+ * This wrapper type prevents access to the `Provider`s inside.
+ *
+ * @see `makeEnvironmentProviders`
+ * @see `importProvidersFrom`
+ *
+ * @publicApi
+ */
+export type EnvironmentProviders = {
+  ɵbrand: 'EnvironmentProviders';
+};
+
+export interface InternalEnvironmentProviders extends EnvironmentProviders {
+  ɵproviders: Provider[];
+
+  /**
+   * If present, indicates that the `EnvironmentProviders` were derived from NgModule providers.
+   *
+   * This is used to produce clearer error messages.
+   */
+  ɵfromNgModule?: true;
+}
+
+export function isEnvironmentProviders(value: Provider|InternalEnvironmentProviders):
+    value is InternalEnvironmentProviders {
+  return value && !!(value as InternalEnvironmentProviders).ɵproviders;
+}
+
 /**
  * Describes a function that is used to process provider lists (such as provider
  * overrides).
@@ -349,7 +384,7 @@ export type ProcessProvidersFunction = (providers: Provider[]) => Provider[];
  */
 export interface ModuleWithProviders<T> {
   ngModule: Type<T>;
-  providers?: Provider[];
+  providers?: Array<Provider|EnvironmentProviders>;
 }
 
 /**
@@ -364,8 +399,6 @@ export interface ModuleWithProviders<T> {
  * @see `importProvidersFrom`
  *
  * @publicApi
- * @developerPreview
+ * @deprecated replaced by `EnvironmentProviders`
  */
-export interface ImportedNgModuleProviders {
-  ɵproviders: Provider[];
-}
+export type ImportedNgModuleProviders = EnvironmentProviders;

packages/core/src/di/provider_collection.ts

@@ -21,9 +21,19 @@ import {resolveForwardRef} from './forward_ref';
 import {ENVIRONMENT_INITIALIZER} from './initializer_token';
 import {ɵɵinject as inject} from './injector_compatibility';
 import {getInjectorDef, InjectorType, InjectorTypeWithProviders} from './interface/defs';
-import {ClassProvider, ConstructorProvider, ExistingProvider, FactoryProvider, ImportedNgModuleProviders, ModuleWithProviders, Provider, StaticClassProvider, TypeProvider, ValueProvider} from './interface/provider';
+import {ClassProvider, ConstructorProvider, EnvironmentProviders, ExistingProvider, FactoryProvider, ImportedNgModuleProviders, InternalEnvironmentProviders, isEnvironmentProviders, ModuleWithProviders, Provider, StaticClassProvider, TypeProvider, ValueProvider} from './interface/provider';
 import {INJECTOR_DEF_TYPES} from './internal_tokens';
 
+/**
+ * Wrap an array of `Provider`s into `EnvironmentProviders`, preventing them from being accidentally
+ * referenced in `@Component in a component injector.
+ */
+export function makeEnvironmentProviders(providers: Provider[]): EnvironmentProviders {
+  return {
+    ɵproviders: providers,
+  } as unknown as EnvironmentProviders;
+}
+
 /**
  * A source of providers for the `importProvidersFrom` function.
  *
@@ -74,9 +84,11 @@ export type ImportProvidersSource =
  * @publicApi
  * @developerPreview
  */
-export function importProvidersFrom(...sources: ImportProvidersSource[]):
-    ImportedNgModuleProviders {
-  return {ɵproviders: internalImportProvidersFrom(true, sources)};
+export function importProvidersFrom(...sources: ImportProvidersSource[]): EnvironmentProviders {
+  return {
+    ɵproviders: internalImportProvidersFrom(true, sources),
+    ɵfromNgModule: true,
+  } as InternalEnvironmentProviders;
 }
 
 export function internalImportProvidersFrom(
@@ -118,7 +130,7 @@ function processInjectorTypesWithProviders(
     typesWithProviders: InjectorTypeWithProviders<unknown>[], providersOut: Provider[]): void {
   for (let i = 0; i < typesWithProviders.length; i++) {
     const {ngModule, providers} = typesWithProviders[i];
-    deepForEach(providers!, provider => {
+    deepForEachProvider(providers! as Array<Provider|InternalEnvironmentProviders>, provider => {
       ngDevMode && validateProvider(provider, providers || EMPTY_ARRAY, ngModule);
       providersOut.push(provider);
     });
@@ -251,12 +263,12 @@ export function walkProviderTree(
     }
 
     // Next, include providers listed on the definition itself.
-    const defProviders = injDef.providers;
+    const defProviders = injDef.providers as Array<SingleProvider|InternalEnvironmentProviders>;
     if (defProviders != null && !isDuplicate) {
       const injectorType = container as InjectorType<any>;
-      deepForEach(defProviders, provider => {
-        ngDevMode && validateProvider(provider, defProviders as SingleProvider[], injectorType);
-        providersOut.push(provider);
+      deepForEachProvider(defProviders, provider => {
+        ngDevMode && validateProvider(provider as SingleProvider, defProviders, injectorType);
+        providersOut.push(provider as SingleProvider);
       });
     }
   } else {
@@ -270,7 +282,8 @@ export function walkProviderTree(
 }
 
 function validateProvider(
-    provider: SingleProvider, providers: SingleProvider[], containerType: Type<unknown>): void {
+    provider: SingleProvider, providers: Array<SingleProvider|InternalEnvironmentProviders>,
+    containerType: Type<unknown>): void {
   if (isTypeProvider(provider) || isValueProvider(provider) || isFactoryProvider(provider) ||
       isExistingProvider(provider)) {
     return;
@@ -284,6 +297,21 @@ function validateProvider(
   }
 }
 
+function deepForEachProvider(
+    providers: Array<Provider|InternalEnvironmentProviders>,
+    fn: (provider: SingleProvider) => void): void {
+  for (let provider of providers) {
+    if (isEnvironmentProviders(provider)) {
+      provider = provider.ɵproviders;
+    }
+    if (Array.isArray(provider)) {
+      deepForEachProvider(provider, fn);
+    } else {
+      fn(provider);
+    }
+  }
+}
+
 export const USE_VALUE =
     getClosureSafeProperty<ValueProvider>({provide: String, useValue: getClosureSafeProperty});