feat(core): support object-based DI flags in TestBed.inject() (angular#46761)

This commit applies the changes similar to the ones performed for the `inject()` function in angular@df246bb.

The `TestBed.inject` function is updated to use previously added object-based API for options: now the flags argument supports passing an object which configures injection flags.

DEPRECATED:

The bit field signature of `TestBed.inject()` has been deprecated, in favor of the new options object.

PR Close angular#46761

Author: AndrewKushnir

aio/tests/e2e/src/api-pages.e2e-spec.ts

@@ -76,11 +76,11 @@ describe('Api pages', () => {
 
   it('should show all overloads of interface methods', async () => {
     await page.navigateTo('api/core/testing/TestBed');
-    expect(await (await page.getInstanceMethodOverloads('inject')).length).toEqual(2);
+    expect(await (await page.getInstanceMethodOverloads('inject')).length).toEqual(4);
   });
 
   it('should show all overloads of pseudo-class methods', async () => {
     await page.navigateTo('api/core/testing/TestBed');
-    expect(await (await page.getInstanceMethodOverloads('inject')).length).toEqual(2);
+    expect(await (await page.getInstanceMethodOverloads('inject')).length).toEqual(4);
   });
 });

goldens/public-api/core/index.md

@@ -492,6 +492,10 @@ export const ENVIRONMENT_INITIALIZER: InjectionToken<() => void>;
 export abstract class EnvironmentInjector implements Injector {
     // (undocumented)
     abstract destroy(): void;
+    abstract get<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions & {
+        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): T;
     // @deprecated
     abstract get<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
@@ -733,6 +737,10 @@ export abstract class Injector {
         parent?: Injector;
         name?: string;
     }): Injector;
+    abstract get<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions & {
+        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;

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

@@ -12,6 +12,7 @@ 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';
 import { NgZone } from '@angular/core';
 import { Pipe } from '@angular/core';
@@ -115,8 +116,16 @@ export interface TestBed {
     get(token: any, notFoundValue?: any): any;
     initTestEnvironment(ngModule: Type<any> | Type<any>[], platform: PlatformRef, options?: TestEnvironmentOptions): void;
     // (undocumented)
-    inject<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+    inject<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions & {
+        optional?: false;
+    }): T;
+    // (undocumented)
+    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>[];

packages/core/src/core_private_export.ts

@@ -12,7 +12,7 @@ export {defaultIterableDiffers as ɵdefaultIterableDiffers, defaultKeyValueDiffe
 export {ChangeDetectorStatus as ɵChangeDetectorStatus, isDefaultChangeDetectionStrategy as ɵisDefaultChangeDetectionStrategy} from './change_detection/constants';
 export {Console as ɵConsole} from './console';
 export {getDebugNodeR2 as ɵgetDebugNodeR2} from './debug/debug_node';
-export {setCurrentInjector as ɵsetCurrentInjector} from './di/injector_compatibility';
+export {convertToBitFlags as ɵconvertToBitFlags, setCurrentInjector as ɵsetCurrentInjector} from './di/injector_compatibility';
 export {getInjectableDef as ɵgetInjectableDef, ɵɵInjectableDeclaration, ɵɵInjectorDef} from './di/interface/defs';
 export {INJECTOR_SCOPE as ɵINJECTOR_SCOPE} from './di/scope';
 export {formatRuntimeError as ɵformatRuntimeError, RuntimeError as ɵRuntimeError} from './errors';

packages/core/src/di/injector.ts

@@ -45,6 +45,28 @@ 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`.
+   * @throws When the `notFoundValue` is `undefined` or `Injector.THROW_IF_NOT_FOUND`.
+   */
+  abstract get<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions&{
+    optional?: false;
+  }): 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`.
+   */
+  abstract get<T>(token: ProviderToken<T>, notFoundValue: null|undefined, options: InjectOptions): T
+      |null;
   /**
    * Retrieves an instance from the injector based on the provided token.
    * @returns The instance from the injector if defined, otherwise the `notFoundValue`.

packages/core/src/di/r3_injector.ts

@@ -77,6 +77,21 @@ interface Record<T> {
  * @developerPreview
  */
 export abstract class EnvironmentInjector implements Injector {
+  /**
+   * 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`.
+   */
+  abstract get<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions&{
+    optional?: false;
+  }): 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`.
+   */
+  abstract get<T>(token: ProviderToken<T>, notFoundValue: null|undefined, options: InjectOptions): T
+      |null;
   /**
    * Retrieves an instance from the injector based on the provided token.
    * @returns The instance from the injector if defined, otherwise the `notFoundValue`.

packages/core/test/acceptance/di_spec.ts

@@ -7,7 +7,7 @@
  */
 
 import {CommonModule} from '@angular/common';
-import {Attribute, ChangeDetectorRef, Component, ComponentFactoryResolver, ComponentRef, createEnvironmentInjector, Directive, ElementRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EventEmitter, forwardRef, Host, HostBinding, ImportedNgModuleProviders, importProvidersFrom, ImportProvidersSource, inject, Inject, Injectable, InjectFlags, InjectionToken, INJECTOR, Injector, Input, LOCALE_ID, ModuleWithProviders, NgModule, NgZone, Optional, Output, Pipe, PipeTransform, Provider, Self, SkipSelf, TemplateRef, Type, ViewChild, ViewContainerRef, ViewEncapsulation, ViewRef, ɵcreateInjector as createInjector, ɵDEFAULT_LOCALE_ID as DEFAULT_LOCALE_ID, ɵINJECTOR_SCOPE} from '@angular/core';
+import {Attribute, ChangeDetectorRef, Component, ComponentFactoryResolver, ComponentRef, createEnvironmentInjector, Directive, ElementRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EventEmitter, forwardRef, Host, HostBinding, ImportedNgModuleProviders, importProvidersFrom, ImportProvidersSource, inject, Inject, Injectable, InjectFlags, InjectionToken, InjectOptions, INJECTOR, Injector, Input, LOCALE_ID, ModuleWithProviders, NgModule, NgZone, Optional, Output, Pipe, PipeTransform, Provider, Self, SkipSelf, TemplateRef, Type, ViewChild, ViewContainerRef, ViewEncapsulation, ViewRef, ɵcreateInjector as createInjector, ɵDEFAULT_LOCALE_ID as DEFAULT_LOCALE_ID, ɵINJECTOR_SCOPE} from '@angular/core';
 import {ViewRef as ViewRefInternal} from '@angular/core/src/render3/view_ref';
 import {TestBed} from '@angular/core/testing';
 import {By} from '@angular/platform-browser';
@@ -3467,6 +3467,39 @@ describe('di', () => {
         expect(envInjector.get(TOKEN, undefined, InjectFlags.Optional)).toBeNull();
       });
 
+      it('should include `null` into the result type when the optional flag is used', () => {
+        const TOKEN = new InjectionToken<string>('TOKEN');
+
+        @Component({
+          standalone: true,
+          template: '',
+        })
+        class TestCmp {
+          nodeInjector = inject(Injector);
+          envInjector = inject(EnvironmentInjector);
+        }
+
+        const {nodeInjector, envInjector} = TestBed.createComponent(TestCmp).componentInstance;
+
+        const flags: InjectOptions = {optional: true};
+
+        let nodeInjectorResult = nodeInjector.get(TOKEN, undefined, flags);
+        expect(nodeInjectorResult).toBe(null);
+
+        // Verify that `null` can be a valid value (from typing standpoint),
+        // the line below would fail a type check in case the result doesn't
+        // have `null` in the type.
+        nodeInjectorResult = null;
+
+        let envInjectorResult = envInjector.get(TOKEN, undefined, flags);
+        expect(envInjectorResult).toBe(null);
+
+        // Verify that `null` can be a valid value (from typing standpoint),
+        // the line below would fail a type check in case the result doesn't
+        // have `null` in the type.
+        envInjectorResult = null;
+      });
+
       it('should be able to use skipSelf injection in NodeInjector', () => {
         const TOKEN = new InjectionToken<string>('TOKEN', {
           providedIn: 'root',

packages/core/test/bundling/animations/bundle.golden_symbols.json

@@ -650,6 +650,9 @@
   {
     "name": "containsElement"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "convertToMap"
   },

packages/core/test/bundling/cyclic_import/bundle.golden_symbols.json

@@ -458,6 +458,9 @@
   {
     "name": "connectableObservableDescriptor"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createElementNode"
   },

packages/core/test/bundling/forms_reactive/bundle.golden_symbols.json

@@ -677,6 +677,9 @@
   {
     "name": "controlPath"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createDirectivesInstances"
   },

packages/core/test/bundling/forms_template_driven/bundle.golden_symbols.json

@@ -647,6 +647,9 @@
   {
     "name": "controlPath"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createDirectivesInstances"
   },

packages/core/test/bundling/hello_world/bundle.golden_symbols.json

@@ -323,6 +323,9 @@
   {
     "name": "connectableObservableDescriptor"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createElementRef"
   },

packages/core/test/bundling/router/bundle.golden_symbols.json

@@ -809,6 +809,9 @@
   {
     "name": "containsTree"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "convertToParamMap"
   },

packages/core/test/bundling/standalone_bootstrap/bundle.golden_symbols.json

@@ -392,6 +392,9 @@
   {
     "name": "connectableObservableDescriptor"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createElementRef"
   },

packages/core/test/bundling/todo/bundle.golden_symbols.json

@@ -557,6 +557,9 @@
   {
     "name": "connectableObservableDescriptor"
   },
+  {
+    "name": "convertToBitFlags"
+  },
   {
     "name": "createDirectivesInstances"
   },

packages/core/test/test_bed_spec.ts

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
-import {APP_INITIALIZER, ChangeDetectorRef, Compiler, Component, Directive, ElementRef, ErrorHandler, getNgModuleById, Inject, Injectable, InjectionToken, Injector, Input, LOCALE_ID, ModuleWithProviders, NgModule, Optional, Pipe, Type, ViewChild, ɵsetClassMetadata as setClassMetadata, ɵɵdefineComponent as defineComponent, ɵɵdefineInjector as defineInjector, ɵɵdefineNgModule as defineNgModule, ɵɵelementEnd as elementEnd, ɵɵelementStart as elementStart, ɵɵsetNgModuleScope as setNgModuleScope, ɵɵtext as text} from '@angular/core';
+import {APP_INITIALIZER, ChangeDetectorRef, Compiler, Component, Directive, ElementRef, ErrorHandler, getNgModuleById, Inject, Injectable, InjectFlags, InjectionToken, InjectOptions, Injector, Input, LOCALE_ID, ModuleWithProviders, NgModule, Optional, Pipe, Type, ViewChild, ɵsetClassMetadata as setClassMetadata, ɵɵdefineComponent as defineComponent, ɵɵdefineInjector as defineInjector, ɵɵdefineNgModule as defineNgModule, ɵɵelementEnd as elementEnd, ɵɵelementStart as elementStart, ɵɵsetNgModuleScope as setNgModuleScope, ɵɵtext as text} from '@angular/core';
 import {TestBed, TestBedImpl} from '@angular/core/testing/src/test_bed';
 import {By} from '@angular/platform-browser';
 import {expect} from '@angular/platform-browser/testing/src/matchers';
@@ -1853,6 +1853,46 @@ describe('TestBed', () => {
     fixture.detectChanges();
     expect(fixture!.nativeElement.textContent).toContain('changed');
   });
+
+  describe('TestBed.inject', () => {
+    describe('injection flags', () => {
+      it('should be able to optionally inject a token', () => {
+        const TOKEN = new InjectionToken<string>('TOKEN');
+
+        expect(TestBed.inject(TOKEN, undefined, {optional: true})).toBeNull();
+        expect(TestBed.inject(TOKEN, undefined, InjectFlags.Optional)).toBeNull();
+
+        expect(TestBed.inject(TOKEN, undefined, {optional: true})).toBeNull();
+        expect(TestBed.inject(TOKEN, undefined, InjectFlags.Optional)).toBeNull();
+      });
+
+      it('should include `null` into the result type when the optional flag is used', () => {
+        const TOKEN = new InjectionToken<string>('TOKEN');
+
+        const flags: InjectOptions = {optional: true};
+        let result = TestBed.inject(TOKEN, undefined, flags);
+        expect(result).toBe(null);
+
+        // Verify that `null` can be a valid value (from typing standpoint),
+        // the line below would fail a type check in case the result doesn't
+        // have `null` in the type.
+        result = null;
+      });
+
+      it('should be able to use skipSelf injection', () => {
+        const TOKEN = new InjectionToken<string>('TOKEN');
+        TestBed.configureTestingModule({
+          providers: [{provide: TOKEN, useValue: 'from TestBed'}],
+        });
+
+        expect(TestBed.inject(TOKEN)).toBe('from TestBed');
+
+        expect(TestBed.inject(TOKEN, undefined, {skipSelf: true, optional: true})).toBeNull();
+        expect(TestBed.inject(TOKEN, undefined, InjectFlags.SkipSelf | InjectFlags.Optional))
+            .toBeNull();
+      });
+    });
+  });
 });
 
 

packages/core/testing/src/test_bed.ts

@@ -16,13 +16,15 @@ import {
   Directive,
   InjectFlags,
   InjectionToken,
+  InjectOptions,
   Injector,
   NgModule,
   NgZone,
   Pipe,
   PlatformRef,
   ProviderToken,
   Type,
+  ɵconvertToBitFlags as convertToBitFlags,
   ɵflushModuleScopingQueueAsMuchAsPossible as flushModuleScopingQueueAsMuchAsPossible,
   ɵgetUnknownElementStrictMode as getUnknownElementStrictMode,
   ɵgetUnknownPropertyStrictMode as getUnknownPropertyStrictMode,
@@ -87,7 +89,14 @@ export interface TestBed {
 
   compileComponents(): Promise<any>;
 
+  inject<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions&{
+    optional?: false
+  }): T;
+  inject<T>(token: ProviderToken<T>, notFoundValue: null|undefined, options: InjectOptions): T|null;
+  inject<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   inject<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   inject<T>(token: ProviderToken<T>, notFoundValue: null, flags?: InjectFlags): T|null;
 
   /** @deprecated from v9.0.0 use TestBed.inject */
@@ -290,10 +299,19 @@ export class TestBedImpl implements TestBed {
     return TestBedImpl.INSTANCE.overrideProvider(token, provider);
   }
 
+  static inject<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions&{
+    optional?: false
+  }): T;
+  static inject<T>(token: ProviderToken<T>, notFoundValue: null|undefined, options: InjectOptions):
+      T|null;
+  static inject<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   static inject<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   static inject<T>(token: ProviderToken<T>, notFoundValue: null, flags?: InjectFlags): T|null;
-  static inject<T>(token: ProviderToken<T>, notFoundValue?: T|null, flags?: InjectFlags): T|null {
-    return TestBedImpl.INSTANCE.inject(token, notFoundValue, flags);
+  static inject<T>(
+      token: ProviderToken<T>, notFoundValue?: T|null, flags?: InjectFlags|InjectOptions): T|null {
+    return TestBedImpl.INSTANCE.inject(token, notFoundValue, convertToBitFlags(flags));
   }
 
   /** @deprecated from v9.0.0 use TestBed.inject */
@@ -468,14 +486,22 @@ export class TestBedImpl implements TestBed {
     return this.compiler.compileComponents();
   }
 
+  inject<T>(token: ProviderToken<T>, notFoundValue: undefined, options: InjectOptions&{
+    optional: true
+  }): T|null;
+  inject<T>(token: ProviderToken<T>, notFoundValue?: T, options?: InjectOptions): T;
+  inject<T>(token: ProviderToken<T>, notFoundValue: null, options?: InjectOptions): T|null;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   inject<T>(token: ProviderToken<T>, notFoundValue?: T, flags?: InjectFlags): T;
+  /** @deprecated use object-based flags (`InjectOptions`) instead. */
   inject<T>(token: ProviderToken<T>, notFoundValue: null, flags?: InjectFlags): T|null;
-  inject<T>(token: ProviderToken<T>, notFoundValue?: T|null, flags?: InjectFlags): T|null {
+  inject<T>(token: ProviderToken<T>, notFoundValue?: T|null, flags?: InjectFlags|InjectOptions): T
+      |null {
     if (token as unknown === TestBed) {
       return this as any;
     }
     const UNDEFINED = {} as unknown as T;
-    const result = this.testModuleRef.injector.get(token, UNDEFINED, flags);
+    const result = this.testModuleRef.injector.get(token, UNDEFINED, convertToBitFlags(flags));
     return result === UNDEFINED ? this.compiler.injector.get(token, notFoundValue, flags) as any :
                                   result;
   }