skip to content

In a NestJS app, a per-tenant connection provider is marked Scope.REQUEST and every endpoint that reaches it gets slower. Why, and what can replace it?

level: seniorimportance: should knowfreq 45%

answer

  1. scope travels up the chain
  2. controller rebuilt per request
  3. transient does not bubble
  4. durable sub-trees per tenant
  5. context without request scope

basics

~20 s

In NestJS, Scope.REQUEST bubbles up the injection chain: every provider and controller that depends on the tenant connection becomes request-scoped and is rebuilt per request. Durable providers or a singleton reading tenant context avoid that.

solid answer

~40 s

A provider with `scope: Scope.REQUEST` gets a new instance per request, and so does everything that injects it, directly or transitively, up to the controller; anything that depends on a request-scoped provider is request-scoped itself. One tenant-connection factory used by most repositories therefore turns most of the graph into per-request objects, built and garbage-collected on every call. `Scope.TRANSIENT` does not bubble: each consumer gets its own instance, but stays a singleton. Alternatives: **durable providers** (`durable: true` plus a `ContextIdStrategy` registered with `ContextIdFactory.apply()`), which keep one sub-tree per tenant; or singletons that read the tenant from a per-request store based on `AsyncLocalStorage` and pick the connection at call time.

code

typescript · 53 lines
typescript
import { Controller, Get, Inject, Injectable, Module, Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';

export const TENANT_CONNECTION = Symbol('TENANT_CONNECTION');
type TenantConnection = { tenantId: string };

@Injectable()
export class TenantConnectionPool {
  private readonly byTenant = new Map<string, TenantConnection>();
  forTenant(tenantId: string): TenantConnection {
    let conn = this.byTenant.get(tenantId);
    if (!conn) {
      conn = { tenantId };
      this.byTenant.set(tenantId, conn);
    }
    return conn;
  }
}

@Injectable()
export class OrdersRepository {
  // request-scoped implicitly: it depends on a request-scoped provider
  constructor(@Inject(TENANT_CONNECTION) private readonly conn: TenantConnection) {}
  tenant() {
    return this.conn.tenantId;
  }
}

@Controller('orders')
export class OrdersController {
  // also rebuilt for every request, through OrdersRepository
  constructor(private readonly orders: OrdersRepository) {}
  @Get()
  list() {
    return { tenant: this.orders.tenant() };
  }
}

@Module({
  controllers: [OrdersController],
  providers: [
    TenantConnectionPool,
    {
      provide: TENANT_CONNECTION,
      scope: Scope.REQUEST,
      useFactory: (req: { headers: Record<string, unknown> }, pool: TenantConnectionPool) =>
        pool.forTenant(String(req.headers['x-tenant-id'])),
      inject: [REQUEST, TenantConnectionPool],
    },
    OrdersRepository,
  ],
})
export class OrdersModule {}

go deeper

for a junior

Know the three scopes, that singleton is the default, and that Scope.REQUEST gives each request a new instance.

for a middle

Explain that request scope bubbles up to the controller while transient scope does not, and why moduleRef.get() refuses scoped providers.

for a senior

Trace a latency regression to one request-scoped provider at the bottom of the graph and replace it with a durable strategy or a context store.

for a principal

Set a rule that request scope stays at the graph's edges, and weigh per-tenant durable sub-trees against tenant count and memory.

## The three injection scopes Every NestJS provider has a **scope**, set with `@Injectable({ scope })` or the `scope` key of a custom provider, using the `Scope` enum from `@nestjs/common`: | Scope | Lifetime | Bubbles to consumers? | |---|---|---| | `Scope.DEFAULT` | one instance for the whole app, created at bootstrap | n/a | | `Scope.REQUEST` | a new instance for each incoming request, garbage-collected afterwards | **yes** | | `Scope.TRANSIENT` | a new dedicated instance for each consumer that injects it | no | Singleton scope is the default and the documented recommendation for most providers. Because Node.js does not run one thread per request, sharing instances across requests is safe. ## Why request scope spreads The docs state it directly: request scope **bubbles up the injection chain**. If `OrdersController` injects `OrdersService`, which injects `OrdersRepository`, which injects the request-scoped tenant connection, then the repository, the service and the controller all become request-scoped. A provider that does not depend on the connection stays a singleton. So for each request Nest must: 1. Create a new DI sub-tree identified by a context id. 2. Instantiate the tenant connection provider and every provider that depends on it, up to the controller. 3. Let all of those objects be garbage-collected when the request ends. With one central data-source provider that most repositories use, nearly the whole application becomes per-request. Some providers must stay singletons and should not depend on request-scoped providers at all; the docs cite authentication strategies and scheduled-job classes as examples. Request scope also changes how code outside the injector reaches those providers. `ModuleRef.get()` cannot return a scoped provider, including one that is request-scoped only implicitly, and throws `InvalidClassScopeException`; `ModuleRef.resolve()` must be used, and without a context id each call builds a fresh sub-tree. `ContextIdFactory.getByRequest(request)` returns the context id of the current request. ## Transient scope is different A singleton that injects a `Scope.TRANSIENT` provider receives its own fresh instance, but the singleton itself does not change scope; injecting it elsewhere still returns the same instance. That is why transient scope suits per-consumer helpers such as a logger that names its host class (via the `INQUIRER` token), and is no answer to per-tenant state. ## Alternative 1: durable providers When requests can be grouped, for example by tenant, rebuilding the sub-tree per request is wasted work. **Durable providers** keep one sub-tree per group: - Implement a `ContextIdStrategy` whose `attach()` returns, per tenant id, a stored `ContextId` for durable trees (`info.isTreeDurable`) and the original context id otherwise; it can also return a `payload` that replaces the injected `REQUEST` object. - Register it once, before any request arrives, with `ContextIdFactory.apply(new AggregateByTenantContextIdStrategy())`. - Mark the provider with `scope: Scope.REQUEST, durable: true`. Durability bubbles too, as long as all of a consumer's request-scoped dependencies are durable. ```typescript import { ContextId, ContextIdFactory, ContextIdStrategy, HostComponentInfo } from '@nestjs/core'; const tenants = new Map<string, ContextId>(); export class AggregateByTenantContextIdStrategy implements ContextIdStrategy { attach(contextId: ContextId, request: { headers: Record<string, unknown> }) { const tenantId = String(request.headers['x-tenant-id']); const tenantTree = tenants.get(tenantId) ?? ContextIdFactory.create(); tenants.set(tenantId, tenantTree); return (info: HostComponentInfo) => (info.isTreeDurable ? tenantTree : contextId); } } ``` The docs warn that this strategy is not ideal for applications with a large number of tenants; each tenant's sub-tree stays cached in the map. ## Alternative 2: keep singletons and read context Most request-scoped providers exist only to read one value of the current request: the user, the tenant or a locale. The docs point to a per-request store based on Node's `AsyncLocalStorage` instead: middleware stores the tenant id when the request starts, every provider stays a singleton, and the repository asks a singleton connection pool for the current tenant's connection at call time. This works the same in HTTP handlers, message handlers and queue jobs, and nothing is rebuilt per request. ## Choosing - Keep the default singleton scope wherever the value can be looked up at call time. - Use durable providers when the grouping is small and stable and the tree genuinely holds per-tenant objects. - Reserve plain `Scope.REQUEST` for state truly unique to each request, and keep it at the edges of the graph so it bubbles through as few classes as possible. - Measure before and after: the docs expect a well-designed app with request-scoped providers to stay within roughly 5% extra latency, so a much larger regression is a reason to check how far request scope has spread.

  • A singleton service needs the tenant connection from inside a method. Why does moduleRef.get(TENANT_CONNECTION) throw, and what works instead?
    `ModuleRef.get()` cannot return scoped providers, including implicitly request-scoped ones, and throws `InvalidClassScopeException`. Use `await moduleRef.resolve(TOKEN, contextId)`, taking the context id from `ContextIdFactory.getByRequest(request)` so it joins the current request's sub-tree; without a context id every `resolve()` builds a separate sub-tree.
  • If a singleton DogsService injects a transient LoggerService, does DogsService become transient?
    No. Transient scope does not bubble: DogsService receives its own fresh LoggerService instance but remains a singleton, so injecting DogsService anywhere still yields one instance. To make DogsService itself per-consumer, mark it `Scope.TRANSIENT` explicitly.
  • When do durable providers stop being a good fit?
    When the grouping key has many values. Each tenant's durable sub-tree stays alive in the strategy's map, so memory grows with the tenant count, and the docs warn the approach is not ideal for a large number of tenants. A singleton reading the tenant from an `AsyncLocalStorage` store scales better.

  • Only the provider marked Scope.REQUEST is rebuilt; its consumers stay singletons.
  • A singleton holding a request-scoped dependency keeps the first request's instance.
  • Scope.TRANSIENT makes the consuming singleton transient as well.
  • moduleRef.get() returns the current request's instance of a scoped provider.
  • Durable providers create a new sub-tree for every request.