La portée des providers (singleton, request, transient)

Singleton : une instance ; requête : une par requête ; transitoire : une par consommateur.

Les trois portées

La démonstration

Chaque provider reçoit un numéro d'instance au moment de sa création. Le contrôleur injecte un provider de chaque portée :

📄 src/portees.ts

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

let numero = 0;
const suivant = () => ++numero;

// 1. Portée par défaut : une seule instance pour toute l'application
@Injectable()
export class CompteurGlobal {
  readonly instance = suivant();
  private total = 0;
  incrementer() {
    return ++this.total;
  }
}

// 2. Portée « requête » : une nouvelle instance pour chaque requête HTTP
@Injectable({ scope: Scope.REQUEST })
export class ContexteRequete {
  readonly instance = suivant();
  readonly utilisateur: string;
  constructor(@Inject(REQUEST) requete: Request) {
    this.utilisateur = String(requete.headers['x-utilisateur'] ?? 'anonyme');
  }
}

// 3. Portée « transitoire » : une nouvelle instance pour chaque classe qui l'injecte
@Injectable({ scope: Scope.TRANSIENT })
export class Journal {
  readonly instance = suivant();
  private contexte = '?';
  definirContexte(c: string) {
    this.contexte = c;
  }
  ecrire(m: string) {
    return `[${this.contexte}#${this.instance}] ${m}`;
  }
}

@Injectable()
export class GroupesService {
  constructor(private readonly journal: Journal) {
    this.journal.definirContexte('Groupes');
  }
  info() {
    return this.journal.ecrire('liste demandée');
  }
}

@Injectable()
export class NotesService {
  constructor(private readonly journal: Journal) {
    this.journal.definirContexte('Notes');
  }
  info() {
    return this.journal.ecrire('bulletin demandé');
  }
}

📄 src/demo.controller.ts

import { Controller, Get } from '@nestjs/common';
import { CompteurGlobal, ContexteRequete, GroupesService, NotesService } from './portees';

let controleursCrees = 0;

@Controller('demo')
export class DemoController {
  constructor(
    private readonly compteur: CompteurGlobal,
    private readonly contexte: ContexteRequete,        // portée requête → le contrôleur le devient aussi
    private readonly groupes: GroupesService,
    private readonly notes: NotesService,
  ) {
    controleursCrees++;
  }

  @Get()
  demo() {
    return {
      compteurGlobal: `instance ${this.compteur.instance}, appel n° ${this.compteur.incrementer()}`,
      contexteRequete: `instance ${this.contexte.instance}, utilisateur ${this.contexte.utilisateur}`,
      journaux: [this.groupes.info(), this.notes.info()],
      controleursCrees,
    };
  }
}

Trois requêtes (utilisateurs sami, ines, puis sans en-tête) :

GET /api/demo → 200 {"compteurGlobal":"instance 1, appel n° 1","contexteRequete":"instance 4, utilisateur sami","journaux":["[Groupes#2] liste demandée","[Notes#3] bulletin demandé"],"controleursCrees":1}
GET /api/demo → 200 {"compteurGlobal":"instance 1, appel n° 2","contexteRequete":"instance 5, utilisateur ines","journaux":["[Groupes#2] liste demandée","[Notes#3] bulletin demandé"],"controleursCrees":2}
GET /api/demo → 200 {"compteurGlobal":"instance 1, appel n° 3","contexteRequete":"instance 6, utilisateur anonyme","journaux":["[Groupes#2] liste demandée","[Notes#3] bulletin demandé"],"controleursCrees":3}

Lecture du résultat

• CompteurGlobal (par défaut) : toujours l'instance 1, et le compteur continue d'une requête à l'autre (1, 2, 3). Toute l'application partage le même objet.
• ContexteRequete (requête) : une nouvelle instance à chaque requête (4, 5, 6), qui lit l'en-tête X-Utilisateur de sa requête grâce au jeton REQUEST. Les données d'un utilisateur ne peuvent pas « déborder » sur la requête d'un autre.
• Journal (transitoire) : deux instances différentes, une pour GroupesService (#2) et une pour NotesService (#3), chacune avec son propre contexte. Comme ces deux services sont des singletons, leurs journaux sont créés une seule fois, au démarrage.
• controleursCrees passe à 1, 2, 3 : le contrôleur est recréé à chaque requête!

La propagation de la portée requête

Le dernier point est essentiel : un provider de portée requête contamine tout ce qui l'injecte. Le contrôleur dépend de ContexteRequete: pour lui fournir le bon contexte à chaque requête, NestJS doit recréer le contrôleur à chaque requête. Si un service de portée par défaut injectait ContexteRequete, il deviendrait lui aussi « par requête », ainsi que tous ceux qui l'injectent, et ainsi de suite.

Quand utiliser quelle portée ?

Pour l'utilisateur connecté, NestJS propose aussi une alternative sans portée requête : le lire dans la requête avec un décorateur de paramètre personnalisé (leçon 5.4) et le passer en paramètre au service. C'est l'approche du chapitre 13.

Activités

@Injectable({ scope: Scope.REQUEST })
export class Correlation {
  readonly id: string;
  constructor(@Inject(REQUEST) req: Request) {
    const recu = req.headers['x-correlation-id'];
    this.id = typeof recu === 'string' && recu ? recu : randomUUID();
  }
}