diff --git a/docs/dependency-injection.md b/docs/dependency-injection.md index ebda6da..3af1c14 100644 --- a/docs/dependency-injection.md +++ b/docs/dependency-injection.md @@ -80,4 +80,39 @@ export class UserDialog { } ``` +## Asserting injection context +When creating reusable helper functions that use `inject()`, you may want to ensure they are only called from an injection context. The `assertInInjectionContext()` function helps you enforce this constraint and provide clear error messages. + +**Consider** using `assertInInjectionContext()` in helper functions that use `inject()`. + +```ts title="❌ Without assertion - unclear error" +export function injectBody(): HTMLElement { + return inject(DOCUMENT).body; + // Error: NullInjectorError: No provider for DOCUMENT! +} +``` + +```ts title="✅ With assertion - clear error" +export function injectBody(): HTMLElement { + assertInInjectionContext(injectBody); + return inject(DOCUMENT).body; + // Error: NG0203: injectBody() can only be used within an injection context +} +``` + +:::info Why? +`assertInInjectionContext()` provides a clearer, more actionable error message that points to your helper function instead of the generic `inject()` call. This makes debugging easier for developers using your code. +::: + +**Do** call helper functions from injection contexts. + +- ✅ Constructor +- ✅ Field initializer +- ✅ Within `runInInjectionContext()` +- ❌ Event handler +- ❌ Lifecycle hook + +:::info Why? +Calling `inject()` or `assertInInjectionContext()` outside an injection context throws [error NG0203](https://v21.angular.dev/errors/NG0203). Make sure to call these functions only during construction or initialization phases. +::: diff --git a/versioned_docs/version-19/dependency-injection.md b/versioned_docs/version-19/dependency-injection.md index 136ccf2..cbeb556 100644 --- a/versioned_docs/version-19/dependency-injection.md +++ b/versioned_docs/version-19/dependency-injection.md @@ -80,4 +80,41 @@ export class DialogComponent { } ``` +## Asserting injection context + +When creating reusable helper functions that use `inject()`, you may want to ensure they are only called from an injection context. The `assertInInjectionContext()` function helps you enforce this constraint and provide clear error messages. + +**Consider** using `assertInInjectionContext()` in helper functions that use `inject()`. + +```ts title="❌ Without assertion - unclear error" +export function injectBody(): HTMLElement { + return inject(DOCUMENT).body; + // Error: NullInjectorError: No provider for DOCUMENT! +} +``` + +```ts title="✅ With assertion - clear error" +export function injectBody(): HTMLElement { + assertInInjectionContext(injectBody); + return inject(DOCUMENT).body; + // Error: NG0203: injectBody() can only be used within an injection context +} +``` + +:::info Why? +`assertInInjectionContext()` provides a clearer, more actionable error message that points to your helper function instead of the generic `inject()` call. This makes debugging easier for developers using your code. +::: + +**Do** call helper functions from injection contexts. + +- ✅ Constructor +- ✅ Field initializer +- ✅ Within `runInInjectionContext()` +- ❌ Event handler +- ❌ Lifecycle hook + +:::info Why? +Calling `inject()` or `assertInInjectionContext()` outside an injection context throws [error NG0203](https://v19.angular.dev/errors/NG0203). Make sure to call these functions only during construction or initialization phases. +::: + diff --git a/versioned_docs/version-20/dependency-injection.md b/versioned_docs/version-20/dependency-injection.md index ebda6da..a67aabe 100644 --- a/versioned_docs/version-20/dependency-injection.md +++ b/versioned_docs/version-20/dependency-injection.md @@ -80,4 +80,39 @@ export class UserDialog { } ``` +## Asserting injection context +When creating reusable helper functions that use `inject()`, you may want to ensure they are only called from an injection context. The `assertInInjectionContext()` function helps you enforce this constraint and provide clear error messages. + +**Consider** using `assertInInjectionContext()` in helper functions that use `inject()`. + +```ts title="❌ Without assertion - unclear error" +export function injectBody(): HTMLElement { + return inject(DOCUMENT).body; + // Error: NullInjectorError: No provider for DOCUMENT! +} +``` + +```ts title="✅ With assertion - clear error" +export function injectBody(): HTMLElement { + assertInInjectionContext(injectBody); + return inject(DOCUMENT).body; + // Error: NG0203: injectBody() can only be used within an injection context +} +``` + +:::info Why? +`assertInInjectionContext()` provides a clearer, more actionable error message that points to your helper function instead of the generic `inject()` call. This makes debugging easier for developers using your code. +::: + +**Do** call helper functions from injection contexts. + +- ✅ Constructor +- ✅ Field initializer +- ✅ Within `runInInjectionContext()` +- ❌ Event handler +- ❌ Lifecycle hook + +:::info Why? +Calling `inject()` or `assertInInjectionContext()` outside an injection context throws [error NG0203](https:/v20.angular.dev/errors/NG0203). Make sure to call these functions only during construction or initialization phases. +:::