feat(core): remove InjectFlags from public API (angular#60318)

Removes the deprecated `InjectFlags` symbol from the `@angular/core` public API, as well as all the places that accept it. The previous commit includes an automated migration to switch over to the new way of passing in flags.

BREAKING CHANGE:
* `InjectFlags` has been removed.
* `inject` no longer accepts `InjectFlags`.
* `Injector.get` no longer accepts `InjectFlags`.
* `EnvironmentInjector.get` no longer accepts `InjectFlags`.
* `TestBed.get` no longer accepts `InjectFlags`.
* `TestBed.inject` no longer accepts `InjectFlags`.

PR Close angular#60318

Author: crisbeto

goldens/public-api/core/index.api.md

@@ -692,8 +692,6 @@ export abstract class EnvironmentInjector implements Injector {
     }): T;
     abstract get<T>(token: ProviderToken<T>, notFoundValue: null | undefined, options: InjectOptions): T | null;
     abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
-    // @deprecated
-    abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
     // @deprecated (undocumented)
     abstract get<T>(token: string | ProviderToken<T>, notFoundValue?: any): any;
     // @deprecated
@@ -853,9 +851,6 @@ export const Inject: InjectDecorator;
 // @public (undocumented)
 export function inject<T>(token: ProviderToken<T>): T;
 
-// @public @deprecated (undocumented)
-export function inject<T>(token: ProviderToken<T>, flags?: InjectFlags): T | null;
-
 // @public (undocumented)
 export function inject<T>(token: ProviderToken<T>, options: InjectOptions & {
     optional?: false;
@@ -915,15 +910,6 @@ export interface InjectDecorator {
     new (token: any): Inject;
 }
 
-// @public @deprecated
-export enum InjectFlags {
-    Default = 0,
-    Host = 1,
-    Optional = 8,
-    Self = 2,
-    SkipSelf = 4
-}
-
 // @public
 export class InjectionToken<T> {
     constructor(_desc: string, options?: {
@@ -962,9 +948,7 @@ export abstract class Injector {
         optional?: false;
     }): T;
     abstract get<T>(token: ProviderToken<T>, notFoundValue: null | undefined, options: InjectOptions): T | null;
-    abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions | InjectFlags): T;
-    // @deprecated
-    abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+    abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
     // @deprecated (undocumented)
     abstract get<T>(token: string | ProviderToken<T>, notFoundValue?: any): any;
     // (undocumented)

goldens/public-api/core/testing/index.api.md

@@ -12,7 +12,6 @@ import { ɵDeferBlockBehavior as DeferBlockBehavior } from '@angular/core';
 import { ɵDeferBlockState as DeferBlockState } from '@angular/core';
 import { Directive } from '@angular/core';
 import { ElementRef } from '@angular/core';
-import { InjectFlags } from '@angular/core';
 import { InjectionToken } from '@angular/core';
 import { InjectOptions } from '@angular/core';
 import { NgModule } from '@angular/core';
@@ -126,8 +125,6 @@ export interface TestBed {
     execute(tokens: any[], fn: Function, context?: any): any;
     flushEffects(): void;
     // @deprecated (undocumented)
-    get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): any;
-    // @deprecated (undocumented)
     get(token: any, notFoundValue?: any): any;
     initTestEnvironment(ngModule: Type<any> | Type<any>[], platform: PlatformRef, options?: TestEnvironmentOptions): void;
     // (undocumented)
@@ -138,10 +135,6 @@ export interface TestBed {
     inject<T>(token: ProviderToken<T>, notFoundValue: null | undefined, options: InjectOptions): T | null;
     // (undocumented)
     inject<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
-    // @deprecated (undocumented)
-    inject<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
-    // @deprecated (undocumented)
-    inject<T>(token: ProviderToken<T>, notFoundValue: null, flags?: InjectFlags): T | null;
     // (undocumented)
     get ngModule(): Type<any> | Type<any>[];
     // (undocumented)

packages/core/src/change_detection/change_detector_ref.ts

@@ -6,8 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {InjectFlags} from '../di';
-import {InternalInjectFlags} from '../di/interface/injector';
+import {InjectFlags, InternalInjectFlags} from '../di/interface/injector';
 import {TNode, TNodeType} from '../render3/interfaces/node';
 import {isComponentHost} from '../render3/interfaces/type_checks';
 import {DECLARATION_COMPONENT_VIEW, LView} from '../render3/interfaces/view';

packages/core/src/di/index.ts

@@ -14,7 +14,6 @@
 
 export * from './metadata';
 export {assertInInjectionContext, runInInjectionContext} from './contextual';
-export {InjectFlags} from './interface/injector';
 export {
   ɵɵdefineInjectable,
   defineInjectable,

packages/core/src/di/injector.ts

@@ -11,7 +11,7 @@ import {THROW_IF_NOT_FOUND, ɵɵinject} from './injector_compatibility';
 import {InjectorMarkers} from './injector_marker';
 import {INJECTOR} from './injector_token';
 import {ɵɵdefineInjectable} from './interface/defs';
-import {InjectFlags, InjectOptions} from './interface/injector';
+import {InjectOptions} from './interface/injector';
 import {Provider, StaticProvider} from './interface/provider';
 import {NullInjector} from './null_injector';
 import {ProviderToken} from './provider_token';
@@ -44,13 +44,6 @@ export abstract class Injector {
   static THROW_IF_NOT_FOUND = THROW_IF_NOT_FOUND;
   static NULL: Injector = /* @__PURE__ */ new NullInjector();
 
-  /**
-   * Internal note on the `options?: InjectOptions|InjectFlags` override of the `get`
-   * method: consider dropping the `InjectFlags` part in one of the major versions.
-   * It can **not** be done in minor/patch, since it's breaking for custom injectors
-   * that only implement the old `InjectorFlags` interface.
-   */
-
   /**
    * Retrieves an instance from the injector based on the provided token.
    * @returns The instance from the injector if defined, otherwise the `notFoundValue`.
@@ -78,18 +71,7 @@ export abstract class Injector {
    * @returns The instance from the injector if defined, otherwise the `notFoundValue`.
    * @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
    */
-  abstract get<T>(
-    token: ProviderToken<T>,
-    notFoundValue?: T,
-    options?: InjectOptions | InjectFlags,
-  ): T;
-  /**
-   * Retrieves an instance from the injector based on the provided token.
-   * @returns The instance from the injector if defined, otherwise the `notFoundValue`.
-   * @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
-   * @deprecated use object-based flags (`InjectOptions`) instead.
-   */
-  abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+  abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
   /**
    * @deprecated from v4.0.0 use ProviderToken<T>
    * @suppress {duplicate}

packages/core/src/di/injector_compatibility.ts

@@ -54,7 +54,7 @@ export class RetrievingInjector implements PrimitivesInjector {
   retrieve<T>(token: PrimitivesInjectionToken<T>, options: unknown): T | NotFound {
     const flags: InjectFlags =
       convertToBitFlags(options as InjectOptions | undefined) || InjectFlags.Default;
-    return this.injector.get(
+    return (this.injector as BackwardsCompatibleInjector).get(
       token as unknown as InjectionToken<T>,
       // When a dependency is requested with an optional flag, DI returns null as the default value.
       flags & InjectFlags.Optional ? null : undefined,
@@ -69,6 +69,14 @@ const NEW_LINE = /\n/gm;
 const NO_NEW_LINE = 'ɵ';
 export const SOURCE = '__source';
 
+/**
+ * Temporary type to allow internal symbols to use inject flags. This should be
+ * removed once we consolidate the flags and the object literal approach.
+ */
+export type BackwardsCompatibleInjector = Injector & {
+  get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectFlags | InjectOptions): T;
+};
+
 export function injectInjectorOnly<T>(token: ProviderToken<T>): T;
 export function injectInjectorOnly<T>(token: ProviderToken<T>, flags?: InjectFlags): T | null;
 export function injectInjectorOnly<T>(
@@ -150,17 +158,6 @@ Please check that 1) the type for the parameter at index ${index} is correct and
  * @publicApi
  */
 export function inject<T>(token: ProviderToken<T>): T;
-/**
- * @param token A token that represents a dependency that should be injected.
- * @param flags Control how injection is executed. The flags correspond to injection strategies that
- *     can be specified with parameter decorators `@Host`, `@Self`, `@SkipSelf`, and `@Optional`.
- * @returns the injected value if operation is successful, `null` otherwise.
- * @throws if called outside of a supported context.
- *
- * @publicApi
- * @deprecated prefer an options object instead of `InjectFlags`
- */
-export function inject<T>(token: ProviderToken<T>, flags?: InjectFlags): T | null;
 /**
  * @param token A token that represents a dependency that should be injected.
  * @param options Control how injection is executed. Options correspond to injection strategies
@@ -274,13 +271,10 @@ export function inject(token: HostAttributeToken, options: {optional: false}): s
  *
  * @publicApi
  */
-export function inject<T>(
-  token: ProviderToken<T> | HostAttributeToken,
-  flags: InjectFlags | InjectOptions = InjectFlags.Default,
-) {
+export function inject<T>(token: ProviderToken<T> | HostAttributeToken, options?: InjectOptions) {
   // The `as any` here _shouldn't_ be necessary, but without it JSCompiler
   // throws a disambiguation  error due to the multiple signatures.
-  return ɵɵinject(token as any, convertToBitFlags(flags));
+  return ɵɵinject(token as any, convertToBitFlags(options));
 }
 
 // Converts object-based DI flags (`InjectOptions`) to bit flags (`InjectFlags`).

packages/core/src/di/r3_injector.ts

@@ -36,6 +36,7 @@ import {setInjectImplementation} from './inject_switch';
 import {InjectionToken} from './injection_token';
 import type {Injector} from './injector';
 import {
+  BackwardsCompatibleInjector,
   catchInjectorError,
   convertToBitFlags,
   injectArgs,
@@ -152,13 +153,6 @@ export abstract class EnvironmentInjector implements Injector {
    * @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
    */
   abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
-  /**
-   * Retrieves an instance from the injector based on the provided token.
-   * @returns The instance from the injector if defined, otherwise the `notFoundValue`.
-   * @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
-   * @deprecated use object-based flags (`InjectOptions`) instead.
-   */
-  abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
   /**
    * @deprecated from v4.0.0 use ProviderToken<T>
    * @suppress {duplicate}
@@ -238,18 +232,18 @@ export class R3Injector extends EnvironmentInjector implements PrimitivesInjecto
       this.scopes.add(record.value as InjectorScope);
     }
 
-    this.injectorDefTypes = new Set(this.get(INJECTOR_DEF_TYPES, EMPTY_ARRAY, InjectFlags.Self));
+    this.injectorDefTypes = new Set(this.get(INJECTOR_DEF_TYPES, EMPTY_ARRAY, {self: true}));
   }
 
   retrieve<T>(token: PrimitivesInjectionToken<T>, options?: unknown): T | NotFound {
     const flags: InjectFlags =
       convertToBitFlags(options as InjectOptions | undefined) || InjectFlags.Default;
-    return this.get(
+    return (this as BackwardsCompatibleInjector).get(
       token as unknown as InjectionToken<T>,
       // When a dependency is requested with an optional flag, DI returns null as the default value.
       flags & InjectFlags.Optional ? null : undefined,
       flags,
-    );
+    )!;
   }
 
   /**
@@ -314,15 +308,15 @@ export class R3Injector extends EnvironmentInjector implements PrimitivesInjecto
   override get<T>(
     token: ProviderToken<T>,
     notFoundValue: any = THROW_IF_NOT_FOUND,
-    flags: InjectFlags | InjectOptions = InjectFlags.Default,
+    options?: InjectOptions,
   ): T {
     assertNotDestroyed(this);
 
     if (token.hasOwnProperty(NG_ENV_ID)) {
       return (token as any)[NG_ENV_ID](this);
     }
 
-    flags = convertToBitFlags(flags) as InjectFlags;
+    const flags = convertToBitFlags(options) as InjectFlags;
 
     // Set the injection context.
     let prevInjectContext: InjectorProfilerContext;
@@ -403,7 +397,7 @@ export class R3Injector extends EnvironmentInjector implements PrimitivesInjecto
     }
 
     try {
-      const initializers = this.get(ENVIRONMENT_INITIALIZER, EMPTY_ARRAY, InjectFlags.Self);
+      const initializers = this.get(ENVIRONMENT_INITIALIZER, EMPTY_ARRAY, {self: true});
       if (ngDevMode && !Array.isArray(initializers)) {
         throw new RuntimeError(
           RuntimeErrorCode.INVALID_MULTI_PROVIDER,

packages/core/src/i18n/tokens.ts

@@ -8,7 +8,6 @@
 
 import {InjectionToken} from '../di/injection_token';
 import {inject} from '../di/injector_compatibility';
-import {InjectFlags} from '../di/interface/injector';
 
 import {DEFAULT_LOCALE_ID, USD_CURRENCY_CODE} from './localization';
 
@@ -69,8 +68,7 @@ export function getGlobalLocale(): string {
  */
 export const LOCALE_ID: InjectionToken<string> = new InjectionToken(ngDevMode ? 'LocaleId' : '', {
   providedIn: 'root',
-  factory: () =>
-    inject(LOCALE_ID, InjectFlags.Optional | InjectFlags.SkipSelf) || getGlobalLocale(),
+  factory: () => inject(LOCALE_ID, {optional: true, skipSelf: true}) || getGlobalLocale(),
 });
 
 /**

packages/core/src/render3/chained_injector.ts

@@ -7,8 +7,7 @@
  */
 
 import {Injector} from '../di/injector';
-import {convertToBitFlags} from '../di/injector_compatibility';
-import {InjectFlags, InjectOptions} from '../di/interface/injector';
+import {InjectOptions} from '../di/interface/injector';
 import {ProviderToken} from '../di/provider_token';
 import {NOT_FOUND_CHECK_ONLY_ELEMENT_INJECTOR} from '../view/provider_flags';
 
@@ -22,12 +21,11 @@ export class ChainedInjector implements Injector {
     public parentInjector: Injector,
   ) {}
 
-  get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags | InjectOptions): T {
-    flags = convertToBitFlags(flags);
+  get<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T {
     const value = this.injector.get<T | typeof NOT_FOUND_CHECK_ONLY_ELEMENT_INJECTOR>(
       token,
       NOT_FOUND_CHECK_ONLY_ELEMENT_INJECTOR,
-      flags,
+      options,
     );
 
     if (
@@ -42,6 +40,6 @@ export class ChainedInjector implements Injector {
       return value as T;
     }
 
-    return this.parentInjector.get(token, notFoundValue, flags);
+    return this.parentInjector.get(token, notFoundValue, options);
   }
 }

packages/core/src/render3/di.ts

@@ -9,7 +9,7 @@
 import {isForwardRef, resolveForwardRef} from '../di/forward_ref';
 import {injectRootLimpMode, setInjectImplementation} from '../di/inject_switch';
 import {Injector} from '../di/injector';
-import {convertToBitFlags} from '../di/injector_compatibility';
+import {BackwardsCompatibleInjector, convertToBitFlags} from '../di/injector_compatibility';
 import {InjectorMarkers} from '../di/injector_marker';
 import {InjectFlags, InjectOptions} from '../di/interface/injector';
 import {ProviderToken} from '../di/provider_token';
@@ -419,7 +419,11 @@ function lookupTokenUsingModuleInjector<T>(
     const previousInjectImplementation = setInjectImplementation(undefined);
     try {
       if (moduleInjector) {
-        return moduleInjector.get(token, notFoundValue, flags & InjectFlags.Optional);
+        return (moduleInjector as BackwardsCompatibleInjector).get(
+          token,
+          notFoundValue,
+          flags & InjectFlags.Optional,
+        );
       } else {
         return injectRootLimpMode(token, notFoundValue, flags & InjectFlags.Optional);
       }
@@ -986,7 +990,7 @@ function lookupTokenUsingEmbeddedInjector<T>(
       // Before we go to the next LView, check if the token exists on the current embedded injector.
       const embeddedViewInjector = currentLView[EMBEDDED_VIEW_INJECTOR];
       if (embeddedViewInjector) {
-        const embeddedViewInjectorValue = embeddedViewInjector.get(
+        const embeddedViewInjectorValue = (embeddedViewInjector as BackwardsCompatibleInjector).get(
           token,
           NOT_FOUND as T | {},
           flags,