feat(core): add assertInInjectionContext (#49529)

alxhub · atscott · commit 89d291c367e6 · 2023-03-28T18:47:58.000-07:00
This commit adds an assertion function to the public API, which allows authors of functions which rely on `inject` to validate that they're being called with the right context. This mostly produces a nicer error message than calling `inject()` and relying on Angular's default error message for that. PR Close #49529
diff --git a/goldens/public-api/core/index.md b/goldens/public-api/core/index.md
@@ -98,6 +98,9 @@ export class ApplicationRef {
 // @public (undocumented)
 export function asNativeElements(debugEls: DebugElement[]): any;
 
+// @public
+export function assertInInjectionContext(debugFn: Function): void;
+
 // @public
 export function assertPlatform(requiredToken: any): PlatformRef;
 
diff --git a/packages/core/src/di/contextual.ts b/packages/core/src/di/contextual.ts
@@ -6,9 +6,10 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
+import {RuntimeError, RuntimeErrorCode} from '../errors';
 import type {Injector} from './injector';
-import {setCurrentInjector} from './injector_compatibility';
-import {setInjectImplementation} from './inject_switch';
+import {getCurrentInjector, setCurrentInjector} from './injector_compatibility';
+import {getInjectImplementation, setInjectImplementation} from './inject_switch';
 import {R3Injector} from './r3_injector';
 
 /**
@@ -37,3 +38,22 @@ export function runInInjectionContext<ReturnT>(injector: Injector, fn: () => Ret
     setInjectImplementation(previousInjectImplementation);
   }
 }
+
+/**
+ * Asserts that the current stack frame is within an injection context and has access to `inject`.
+ *
+ * @param debugFn a reference to the function making the assertion (used for the error message).
+ *
+ * @publicApi
+ */
+export function assertInInjectionContext(debugFn: Function): void {
+  // Taking a `Function` instead of a string name here prevents the unminified name of the function
+  // from being retained in the bundle regardless of minification.
+  if (!getInjectImplementation() && !getCurrentInjector()) {
+    throw new RuntimeError(
+        RuntimeErrorCode.MISSING_INJECTION_CONTEXT,
+        ngDevMode &&
+            (debugFn.name +
+             '() can only be used within an injection context such as a constructor, a factory function, a field initializer, or a function used with `runInInjectionContext`'));
+  }
+}
diff --git a/packages/core/src/di/index.ts b/packages/core/src/di/index.ts
@@ -13,7 +13,7 @@
  */
 
 export * from './metadata';
-export {runInInjectionContext} from './contextual';
+export {assertInInjectionContext, runInInjectionContext} from './contextual';
 export {InjectFlags} from './interface/injector';
 export {ɵɵdefineInjectable, defineInjectable, ɵɵdefineInjector, InjectableType, InjectorType} from './interface/defs';
 export {forwardRef, resolveForwardRef, ForwardRefFn} from './forward_ref';
diff --git a/packages/core/src/di/injector_compatibility.ts b/packages/core/src/di/injector_compatibility.ts
@@ -43,6 +43,10 @@ export const SOURCE = '__source';
  */
 let _currentInjector: Injector|undefined|null = undefined;
 
+export function getCurrentInjector(): Injector|undefined|null {
+  return _currentInjector;
+}
+
 export function setCurrentInjector(injector: Injector|null|undefined): Injector|undefined|null {
   const former = _currentInjector;
   _currentInjector = injector;
@@ -57,7 +61,7 @@ export function injectInjectorOnly<T>(token: ProviderToken<T>, flags = InjectFla
     throw new RuntimeError(
         RuntimeErrorCode.MISSING_INJECTION_CONTEXT,
         ngDevMode &&
-            `inject() must be called from an injection context such as a constructor, a factory function, a field initializer, or a function used with \`EnvironmentInjector#runInContext\`.`);
+            `inject() must be called from an injection context such as a constructor, a factory function, a field initializer, or a function used with \`runInInjectionContext\`.`);
   } else if (_currentInjector === null) {
     return injectRootLimpMode(token, undefined, flags);
   } else {
diff --git a/packages/core/test/acceptance/di_spec.ts b/packages/core/test/acceptance/di_spec.ts
@@ -7,7 +7,8 @@
  */
 
 import {CommonModule} from '@angular/common';
-import {Attribute, ChangeDetectorRef, Component, ComponentFactoryResolver, ComponentRef, createEnvironmentInjector, createNgModule, Directive, ElementRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EventEmitter, forwardRef, Host, HostBinding, ImportedNgModuleProviders, importProvidersFrom, ImportProvidersSource, inject, Inject, Injectable, InjectFlags, InjectionToken, InjectOptions, INJECTOR, Injector, Input, LOCALE_ID, makeEnvironmentProviders, ModuleWithProviders, NgModule, NgModuleRef, NgZone, Optional, Output, Pipe, PipeTransform, Provider, runInInjectionContext, Self, SkipSelf, TemplateRef, Type, ViewChild, ViewContainerRef, ViewEncapsulation, ViewRef, ɵcreateInjector as createInjector, ɵDEFAULT_LOCALE_ID as DEFAULT_LOCALE_ID, ɵINJECTOR_SCOPE, ɵInternalEnvironmentProviders as InternalEnvironmentProviders} from '@angular/core';
+import {assertInInjectionContext, Attribute, ChangeDetectorRef, Component, ComponentFactoryResolver, ComponentRef, createEnvironmentInjector, createNgModule, Directive, ElementRef, ENVIRONMENT_INITIALIZER, EnvironmentInjector, EventEmitter, forwardRef, Host, HostBinding, ImportedNgModuleProviders, importProvidersFrom, ImportProvidersSource, inject, Inject, Injectable, InjectFlags, InjectionToken, InjectOptions, INJECTOR, Injector, Input, LOCALE_ID, makeEnvironmentProviders, ModuleWithProviders, NgModule, NgModuleRef, NgZone, Optional, Output, Pipe, PipeTransform, Provider, runInInjectionContext, Self, SkipSelf, TemplateRef, Type, ViewChild, ViewContainerRef, ViewEncapsulation, ViewRef, ɵcreateInjector as createInjector, ɵDEFAULT_LOCALE_ID as DEFAULT_LOCALE_ID, ɵINJECTOR_SCOPE, ɵInternalEnvironmentProviders as InternalEnvironmentProviders} from '@angular/core';
+import {RuntimeError, RuntimeErrorCode} from '@angular/core/src/errors';
 import {ViewRef as ViewRefInternal} from '@angular/core/src/render3/view_ref';
 import {TestBed} from '@angular/core/testing';
 import {By} from '@angular/platform-browser';
@@ -3810,6 +3811,39 @@ describe('di', () => {
     });
   });
 
+  describe('assertInInjectionContext', () => {
+    function placeholder() {}
+
+    it('should throw if not in an injection context', () => {
+      expect(() => assertInInjectionContext(placeholder))
+          .toThrowMatching(
+              (e: Error) => e instanceof RuntimeError &&
+                  e.code === RuntimeErrorCode.MISSING_INJECTION_CONTEXT);
+    });
+
+    it('should not throw if in an EnvironmentInjector context', () => {
+      expect(() => {
+        TestBed.runInInjectionContext(() => {
+          assertInInjectionContext(placeholder);
+        });
+      }).not.toThrow();
+    });
+
+
+    it('should not throw if in an element injector context', () => {
+      expect(() => {
+        @Component({template: ''})
+        class EmptyCmp {
+        }
+
+        const fixture = TestBed.createComponent(EmptyCmp);
+        runInInjectionContext(fixture.componentRef.injector, () => {
+          assertInInjectionContext(placeholder);
+        });
+      }).not.toThrow();
+    });
+  });
+
   it('should be able to use Host in `useFactory` dependency config', () => {
     // Scenario:
     // ---------
