Injection Tokens seem to intimidate many developers. They don't understand what they are, how to use them, and their purpose.
To overcome the fear of this feature, it is important to have a basic understanding of how Angular's Dependency Injection works. (A separate article will dive deeper into the inner workings of Angular's DI system for a full understanding).
Here's an example of how the singleton pattern operates. When we add @Injectable({providedIn: 'root'})
to one of our services:
@Injectable({ providedIn: 'root' })
export class MyService {
// ...
}
The first time, we will call MyService
Angular will store the service in a record
of the RootInjector
with the key being class MyService
and the value being an object containing a factory of MyService
, the current value and a multi
flag.
record:{
//...
[index]:{
key: class MyService,
value: {
factory: f MyService_Factory(t),
multi: undefined
value: {}
}
//...
}
This way, the next time we want to inject our service through the constructor or the inject
function in another Component, Angular's DI will look for the service in the record
object and return its current value or create it using the factory function.
It's also crucial to understand what happens when we provide our service directly in the bootstrapApplication
or Component provider array.
To inject MyService we write the following:
@Component({
// ...
providers: [MyService],
})
export class AppComponent {}
This code is a shorthand syntax for
@Component({
// ...
providers: [{provide: MyService, useClass: MyService}],
})
export class AppComponent {}
By creating an InjectionToken, we are creating a "static" key for our record
or dictionary
of services.
By writing this:
export const DATA = new InjectionToken<string>('data');
We are creating a "constant" of type string
.
The InjectionToken can take an object as second parameter containing a factory function and a providedIn
attribut (Although this parameter will be deprecated as the default value is root and there is no other possibility). The factory function acts like a default value if no other value is provided.
Let's take a look at the following example to clarify it.
export const DATA = new InjectionToken<string>('data', {
factory: () => 'toto',
});
Angular will store our token inside the record
object of the RootInjector
:
record: {
//...
[index]: {
key: InjectionToken {_desc: 'data', ngMetadataName: 'InjectionToken'}
value: {
factory: () => 'toto',
multi: undefined,
value: "toto"
}
},
//...
}
Then when we inject it inside a Component, Angular's DI will look for DATA
key in the RootInjector
's record
and inject the corresponding value. ('toto' is this example)
@Component({
// ...
template: `{{ data }} `, // toto
})
export class AppComponent {
data = inject(DATA);
}
However, in a Component provider array, we can override this Token to map DATA
with another value. This time Angular will store the value inside the record
of the NodeInjector
.
@Component({
// ...
provider: [{provide: DATA, useValue: 'titi'}],
template: `{{ data }} `, // titi
})
export class AppComponent {
data = inject(DATA);
}
When Angular searches for the DATA
token, it first examines the component's NodeInjector
, then the NodeInjector
of its parent and finally the RootInjector
. As a result, in this example, the output value will be 'titi'.
Providing your InjectionToken
useValue
The useValue
keyword allows us to supply a string, number, interface, class instance or any constant value. It is very useful for setting up configuration properties.
export type Environment = 'local' | 'dev' | 'int' | 'prod';
export interface AppConfig {
version: string;
apiUrl: string;
environment: Environment;
}
export const APP_CONFIG = new InjectionToken<AppConfig>('app.config');
export const getAppConfigProvider = (value: AppConfig): ValueProvider => ({
provide: APP_CONFIG,
useValue: value,
});
bootstrapApplication(AppComponent, {
providers: [
getAppConfigProvider(environment) // environment files
],
});
In the example above, we are creating an InjectionToken to store our environment configuration.
This is the recommended method for accessing environment variables in an Nx workspace, as it avoids circular dependencies.
To retrieve our environment properties, we inject the token inside our component.
@Component({
selector: 'app-root',
standalone: true,
template: `{{ config.version }}`,
})
export class AppComponent {
config = inject(APP_CONFIG);
}
useClass
The useClass
keyword allows us to instantiate a new class. This is useful for implementing the dependency inversion principle for instance.
The dependency inversion principle is a software design principle that states that different layers depend on abstractions, rather than on each other. This inversion makes the code more flexible, maintainable and more testable.
export interface Search<T> {
search: (search: string) => T[];
}
export const SEARCH = new InjectionToken<Search<object>>('search');
@Component({
selector: 'shareable',
standalone: true,
imports: [ReactiveFormsModule, NgFor, AsyncPipe, JsonPipe],
template: `
<input type="text" [formControl]="searchInput" />
<button (click)="search()"></button>
<div *ngFor="let d of data | async">{{ d | json }}</div>
`,
})
export class ShareableComponent {
searchService = inject(SEARCH, {optional: true});
data = new BehaviorSubject<object[]>([]);
searchInput = new FormControl('', { nonNullable: true });
// We are not injecting `searchService` with the constructor,
// because `inject` function infers the type.
constructor() {
if (!this.searchService)
throw new Error(`SEARCH TOKEN must be PROVIDED`);
}
search() {
this.data.next(this.searchService.search(this.searchInput.value));
}
}
The ShareableComponent
displays an input field, a search button and a list of the search results. When we hit the search button, the component searches "somewhere" and displays the results. This component is highly generic and does not require any additional information about how or where to search. Implementation details are provided by the parent component.
Let's see how we can utilize the ShareableComponent
.
First, we will create an utility function to provide our Token. This creates a better developer experience and reduces the likelihood of errors as it adds strong typing to our function.
export const getSearchServiceProvider = <T, C extends Search<T>>(clazz: new () => C): ClassProvider => ({
provide: SEARCH,
useClass: clazz,
});
Using the above function, we can supply the desire implementation of the Search
interface within the component that calls the ShareableComponent
. When Angular attempts to inject the SEARCH
InjectionToken , it will traverse each NodeInjector
up the component tree until it finds the provided implementation.
@Injectable()
export class DetailSearchService implements Search<Detail> {
search = (search: string): Detail[] => {
// implementation of our search function
}
}
@Component({
selector: 'parent',
standalone: true,
imports: [ShareableComponent],
providers: [getSearchServiceProvider(DetailSearchService)],
template: `
<shareable></shareable>
`,
})
export class ParentComponent {}
If we want to reuse ShareableComponent
with a different implementation of search, this becomes very easy.
useFactory
The useFactory
keyword allows us to provide an object though a factory function.
export const USER = new InjectionToken<string>('user');
export const getUserProvider = (index: number): FactoryProvider => ({
provide: USER,
useFactory: () => inject(Store).select(selectUser(index)),
});
The inject
function enables us to incorporate other services within the factory function.
Alternatively, if you do not wish to use the inject
function, the FactoryProvider
has a third parameter named deps
where you can inject other injectable services.
export const getUserProvider = (index: number): FactoryProvider => ({
provide: USER,
useFactory: (store: Store) => store.select(selectUser(index))],
deps: [Store],
});
But I advice you to use the inject
function. It's cleaner and easier to understand.
We can then use this provider as follow to retrieve one user from the store:
@Component({
selector: 'app-root',
standalone: true,
providers: [getUserProvider(2)],
template: ` <div>{{ user }}</div> `,
})
export class ParentComponent {
user = inject(USER);
}
useExisting
The useExisting
keyword allows us to map an existing instance of a service to a new token, creating an alias.
When examining the record
object created by Angular, we have the following:
record:{
//...
[index]:{
key: InjectionToken {_desc: 'data', ngMetadataName: 'InjectionToken', ɵprov: undefined},
value: {
factory: () => ɵɵinject(resolveForwardRef(provider.useExisting)),
multi: undefined
value: {}
}
//...
}
Angular resolves the InjectionToken by forwarding the reference to the class specified in the useExisting
parameter. It searches the NodeInjector
and RootInjector
for the class, so it must be set beforehand or an error will occur.
NullInjectorError: No provider for XXX!
Notes
When providing an InjectionToken through the providers, there is not type safety. For example, the following code would not produce a Typescript error, even though the type is inferred as number
for num
, but a string
is provided. (We might have an error at runtime.)
export const NUMBER = new InjectionToken('number');
@Component({
providers: [{provide: NUMBER, useValue: 'toto'}],
// ...
})
export class ParentComponent {
num = inject(NUMBER);
//^ (property) ParentComponent.num: number
}
To ensure type safety, I advise to create a utility function to provide your token.
export const NUMBER = new InjectionToken<number>('number');
export const getNumberProvider = (num: number): ValueProvider => ({
provide: NUMBER,
useValue: num
});
// NUMBER token should be provided through this function
@Component({
providers: [getNumberProvider('toto')],
//^ Argument of type 'string' is not assignable to parameter of type 'number'
// ...
})
export class ParentComponent {
num = inject(NUMBER);
}
This way, our implementation is safe and any errors will occur at compile time, rather than at runtime.
That's it for this article! You should now have a good understanding of InjectionToken and what they do mean. I hope that this information has demystified them for you and you will no longer feel intimidated by them.
I hope you learned new Angular concept. If you liked it, you can find me on Twitter or Github.
👉 If you want to accelerate your Angular and Nx learning journey, come and check out Angular challenges.
Top comments (3)
Great one 🚀
Thanks. means a lot from you🙏