Injection scopes: singleton, request and transient

One provider marked request-scopedrequest scope: Scope.REQUEST: Nest builds one instance of the provider for each request that needs it and drops it after the response. Every class that injects such a provider becomes request-scoped too., RequestContext, holds the kitchen of the current request. After three requests, Nest had built OrdersService and OrdersController three times each as well, although neither asked for any scope: the service needs RequestContext and the controller needs the service, so the context’s scope became theirs.

Scopes decide when Nest builds a provider and who shares it. This lesson compares the three scopes, reproduces the way request scope spreads up a chain of dependencies, and counts what it costs; then it runs transienttransient scope: Scope.TRANSIENT: each class that injects the provider gets an instance of its own, built when that class is built, instead of sharing one instance with the rest of the app. providers and a way to carry request data that keeps every provider a singleton.

Three scopes decide when Nest builds a provider

A provider’s scope is set in its decorator, @Injectable({ scope: Scope.REQUEST }), or with a scope key in a custom provider. A controller takes one too, in @Controller({ path, scope }), and every route of the controller then shares it. There are three scopes:

Scope.DEFAULT, the singleton of the previous lessons, is what a provider gets when it asks for nothing. Request scope gives each request its own object, which may receive the request itself through the REQUEST token of @nestjs/core; Nest drops it once the response is sent. Transient scope gives each class that injects the provider a private instance, which suits helpers such as a logger that labels its lines with its owner.

A request-scoped or transient provider is also fetched differently. app.get() returns singletons only, and resolve() builds scoped instances on demand. The INQUIRER token tells a transient instance which class it was built for, and Node.js’s AsyncLocalStorageAsyncLocalStorage: A Node.js class that keeps a store for all the asynchronous work started inside its run() call, so code deep inside a request can read request data without receiving it as a parameter. can carry request data to singletons without any scope at all.

One request-scoped dependency makes its consumers request-scoped

Here is the app of the opening. Only RequestContext asks for request scope; it reads the kitchen from the request:

import { Controller, Get, Inject, Injectable, Module, Scope } from '@nestjs/common';
import { REQUEST } from '@nestjs/core';
import type { Request } from 'express';
import { count } from './counts.js';

/** Request-scoped: one per request, built from that request. */
@Injectable({ scope: Scope.REQUEST })
export class RequestContext {
  readonly kitchen: string;
  constructor(@Inject(REQUEST) req: Request) {
    count('RequestContext');
    // A real app takes the kitchen from the signed-in user; a header keeps the example short.
    this.kitchen = String(req.headers['x-kitchen'] ?? 'unknown');
  }
}

/** Declared with the default scope, but it needs RequestContext. */
@Injectable()
export class OrdersService {
  readonly n = count('OrdersService');
  constructor(private readonly ctx: RequestContext) {}
  list() {
    return `orders of ${this.ctx.kitchen}`;
  }
}

/** The default scope, and nothing request-scoped below it. */
@Injectable()
export class MenuService {
  readonly n = count('MenuService');
  today() {
    return 'poha, dal rice';
  }
}

@Controller('orders')
export class OrdersController {
  readonly n = count('OrdersController');
  constructor(
    private readonly orders: OrdersService,
    private readonly menu: MenuService,
  ) {}

  /** Answers with the instance numbers of the objects that served this request. */
  @Get()
  list() {
    return { orders: this.orders.list(), controller: this.n, service: this.orders.n, menuService: this.menu.n };
  }
}

@Module({ controllers: [OrdersController], providers: [RequestContext, OrdersService, MenuService] })
export class AppModule {}

OrdersService needs RequestContext, and a singleton cannot hold an object that exists once per request. So Nest makes OrdersService request-scoped as well, and then OrdersController, which needs OrdersService. The documentation calls this the scope bubbling upscope bubbling: The rule that a class which needs a request-scoped provider, directly or through other classes, becomes request-scoped itself. It spreads up a chain of dependencies, never down. the injection chain. Step through start-up and three requests:

import { session } from '../session.mjs';

// One request-scoped provider at the bottom of a chain: what Nest builds at start-up and for each of three requests.
session(`
npx tsc -p tsconfig.json
node dist/main.js
`);

$ npx tsc -p tsconfig.json
$ node dist/main.js
after start-up: MenuService 1
GET /orders (x-kitchen: pune-07) -> {"orders":"orders of pune-07","controller":1,"service":1,"menuService":1}
GET /orders (x-kitchen: pune-12) -> {"orders":"orders of pune-12","controller":2,"service":2,"menuService":1}
GET /orders (x-kitchen: pune-07) -> {"orders":"orders of pune-07","controller":3,"service":3,"menuService":1}
after three requests: MenuService 1, RequestContext 3, OrdersService 3, OrdersController 3

The run confirms each step. After start-up only MenuService existed. Every request then received a fresh RequestContext, OrdersService and OrdersController, numbered 1, 2 and 3 in the answers, while MenuService stayed #1. Scope bubbles up, never down: MenuService is needed by a request-scoped controller and stays a singleton, because it needs nothing request-scoped itself.

That is the cost to watch. This small chain builds 3 objects per request; at 2,000 requests a second that is 6,000 objects a second for the garbage collector, plus the work of every constructor. The documentation’s advice is to prefer singletons and use request scope only where it is truly needed. Nest gives no warning when a scope spreads: the only signs are constructors that run on every request and instance numbers that keep rising, which is why the run counts them.

Transient providers, INQUIRER and resolve(), run and counted Pro: opens with a Pro, Premium or Ultimate pass

Request context without request scope: AsyncLocalStorage, counted Pro: opens with a Pro, Premium or Ultimate pass

Practise: count what Nest builds

Write the prediction the bubbling run checked: given an app’s classes and their declared scopes, count the instances after a number of requests. The sample tests run in your browser and start from the lesson’s own app:

/**
 * The number of instances of each class after start-up and `requests` requests. graph: { [name]: { scope, deps } },
 * scope 'default' or 'request'. Returns { [name]: count }.
 */
export function countInstances(graph, requests) {
  const counts = {};
  for (const name of Object.keys(graph)) {
    // Is it request-scoped, declared or because of what it needs?
    counts[name] = 1;
  }
  return counts;
}

import { assert, test } from 'mysmartcopilot:test';
import { countInstances } from './count_instances.mjs';

/** The lesson's app: RequestContext is request-scoped, the other three are declared with the default scope. */
const lessonApp = {
  OrdersController: { scope: 'default', deps: ['OrdersService', 'MenuService'] },
  OrdersService: { scope: 'default', deps: ['RequestContext'] },
  MenuService: { scope: 'default', deps: [] },
  RequestContext: { scope: 'request', deps: [] },
};

test('the lesson app after three requests, as the run counted', () => {
  assert.deepEqual(countInstances(lessonApp, 3), { OrdersController: 3, OrdersService: 3, MenuService: 1, RequestContext: 3 });
});

test('after start-up only, request-scoped classes have no instance', () => {
  assert.deepEqual(countInstances(lessonApp, 0), { OrdersController: 0, OrdersService: 0, MenuService: 1, RequestContext: 0 });
});

test('the scope bubbles up through several levels', () => {
  const chain = { A: { scope: 'default', deps: ['B'] }, B: { scope: 'default', deps: ['C'] }, C: { scope: 'default', deps: ['D'] }, D: { scope: 'request', deps: [] } };
  assert.deepEqual(countInstances(chain, 5), { A: 5, B: 5, C: 5, D: 5 });
});

test('the scope never bubbles down to what a request-scoped class needs', () => {
  const graph = { Ctx: { scope: 'request', deps: ['Clock'] }, Clock: { scope: 'default', deps: [] } };
  assert.deepEqual(countInstances(graph, 4), { Ctx: 4, Clock: 1 });
});

test('a class with one request-scoped branch is request-scoped; the other branch is not', () => {
  const graph = {
    Top: { scope: 'default', deps: ['Left', 'Right'] },
    Left: { scope: 'default', deps: ['Ctx'] },
    Right: { scope: 'default', deps: ['Menu'] },
    Ctx: { scope: 'request', deps: [] },
    Menu: { scope: 'default', deps: [] },
  };
  assert.deepEqual(countInstances(graph, 2), { Top: 2, Left: 2, Right: 1, Ctx: 2, Menu: 1 });
});

test('a graph without request scope builds one of each, however many requests', () => {
  const graph = { Wallet: { scope: 'default', deps: ['Repo'] }, Repo: { scope: 'default', deps: [] } };
  assert.deepEqual(countInstances(graph, 1000), { Wallet: 1, Repo: 1 });
});

test('a thousand requests build a thousand of each request-scoped class', () => {
  const counts = countInstances(lessonApp, 1000);
  assert.equal(counts.OrdersService, 1000);
  assert.equal(counts.MenuService, 1);
});

Then the questions on the three scopes and on bubbling:

Interview questions

Key takeaways

• The default scope builds one instance at start-up for everyone, request scope one per request, and transient scope one per consumer.
• A class that needs a request-scoped provider becomes request-scoped itself, and so does everything above it; scope bubbles up, never down.
• A request-scoped chain rebuilds every object in it on each request, so a deep chain under heavy traffic creates many objects for nothing more than one value of the request.
• Scoped providers are fetched with resolve(), not get(), and INQUIRER tells a transient instance which class it was built for.