Providers and dependency injection in NestJS

This chapter follows Controllers in NestJS.

A provider is anything Nest can inject: most often a service class, but also a repository, a client for another API, a factory, or a plain configuration value. Classes that use a provider never create it. They declare it as a constructor parameter, and Nest’s injector supplies an instance. That inversion is what lets a test hand a controller a fake service, and what lets one database connection be shared by every feature.

A service as a provider

nest g service cats creates a class marked with @Injectable(). The decorator lets Nest read the class’s constructor parameter types, so the class can itself receive dependencies.

1
import { Injectable, NotFoundException } from '@nestjs/common';
2
import { UsersService } from '../users/users.service';
3
import { CreateCatDto } from './dto/create-cat.dto';
4
import { Cat } from './cat.entity';
5

6
@Injectable()
7
export class CatsService {
8
  private readonly cats: Cat[] = [];
9

10
  constructor(private readonly usersService: UsersService) {}
11

12
  create(dto: CreateCatDto): Cat {
13
    const cat = { id: this.cats.length + 1, ...dto };
14
    this.cats.push(cat);
15
    return cat;
16
  }
17

18
  findOne(id: number): Cat {
19
    const cat = this.cats.find((c) => c.id === id);
20
    if (!cat) throw new NotFoundException(`Cat ${id} not found`);
21
    return cat;
22
  }
23
}

Two declarations are needed for the injection to work: CatsService appears in the providers of CatsModule, and UsersService is exported by a module that CatsModule imports. Modules in NestJS explains both.

How the injector resolves a dependency

Every provider is registered under a token. For a class, the token is the class itself. When Nest creates CatsService, it reads the parameter types that TypeScript emitted for the constructor, finds UsersService, looks up a provider with that token in the module’s scope, creates it first if needed, and passes it in.

flowchart LR
  ctrl[CatsController] -->|needs| catsTok[CatsService token]
  catsTok --> catsInst[CatsService instance]
  catsInst -->|needs| usersTok[UsersService token]
  usersTok --> usersInst[UsersService instance]

The lookup happens once, at startup. By default each provider is a singleton: one instance per application, shared by everyone who injects it. Because the constructor types are the lookup keys, injecting an interface does not work. Interfaces disappear at compile time and leave nothing to look up. Use a class, or a custom token as in the next section.

Custom providers

The shorthand providers: [CatsService] stands for { provide: CatsService, useClass: CatsService }. The long form separates the token from what is created, which gives four options:

1
import { Module } from '@nestjs/common';
2
import { ConfigService } from '@nestjs/config';
3

4
export const CLOCK = Symbol('CLOCK');
5
export const CACHE_TTL = 'CACHE_TTL';
6

7
@Module({
8
  providers: [
9
    { provide: CatsRepository, useClass: InMemoryCatsRepository },
10
    { provide: CLOCK, useValue: { now: () => new Date() } },
11
    {
12
      provide: CACHE_TTL,
13
      useFactory: (config: ConfigService) => config.get<number>('CACHE_TTL', 60),
14
      inject: [ConfigService],
15
    },
16
    { provide: AppLogger, useExisting: PinoLogger },
17
  ],
18
})
19
export class CatsModule {}

• useClass creates a different class for the token, for example an in-memory repository in development and a database one in production.
• useValue hands over an existing object as is. Tests use it to replace a service with a mock.
• useFactory calls a function, which may be async, and injects the result. inject lists the factory’s own dependencies.
• useExisting makes a second token point at a provider that already exists, without creating another instance.

A token that is not a class needs @Inject() at the injection site, because there is no type to read:

1
constructor(
2
  @Inject(CLOCK) private readonly clock: { now(): Date },
3
  @Inject(CACHE_TTL) private readonly cacheTtl: number,
4
) {}

@Optional() next to @Inject() lets the dependency be undefined when no provider is registered, instead of failing at startup.

Injection scopes

The scope decides how long an instance lives:

1
import { Inject, Injectable, Scope } from '@nestjs/common';
2
import { REQUEST } from '@nestjs/core';
3
import type { Request } from 'express';
4

5
@Injectable({ scope: Scope.REQUEST })
6
export class TenantContext {
7
  constructor(@Inject(REQUEST) private readonly request: Request) {}
8

9
  get tenantId(): string | undefined {
10
    return this.request.header('x-tenant-id');
11
  }
12
}

Request scope bubbles up: a singleton that injects TenantContext becomes request-scoped too, and so does every controller above it. Nest then creates that whole chain on every request, which costs memory and time. Prefer passing request data as method arguments, and reach for request scope only when that is impractical.

Circular dependencies

When CatsService injects UsersService and UsersService injects CatsService, neither can be created first. Nest reports the cycle at startup. forwardRef() defers one side of the lookup:

1
constructor(
2
  @Inject(forwardRef(() => CatsService))
3
  private readonly catsService: CatsService,
4
) {}

The same wrapper exists for modules that import each other: imports: [forwardRef(() => CatsModule)]. Treat it as a stopgap. A cycle usually means some logic belongs in a third provider that both sides can depend on.

Next: The NestJS request lifecycle.