Gérer les dépendances circulaires (forwardRef)

Qu'est-ce qu'une dépendance circulaire ?

Il y a dépendance circulaire quand A a besoin de B et que B a besoin de A, directement ou par une chaîne (A → B → C → A). Pour créer A, il faut d'abord B ; pour créer B, il faut d'abord A… Le conteneur ne peut pas en sortir.

forwardRef contourne le cycle ; extraire un service le supprime.

Entre deux services

Le service des stagiaires veut connaître le groupe d'un stagiaire ; le service des groupes veut l'effectif d'un groupe, qu'il demande au service des stagiaires :

📄 src/stagiaires.service.ts

import { Injectable } from '@nestjs/common';
import { GroupesService } from './groupes.service';

@Injectable()
export class StagiairesService {
  constructor(private readonly groupesService: GroupesService) {}   // a besoin des groupes…

  stagiairesDu(code: string) {
    return ['Ben Ali', 'Trabelsi'].map((nom) => `${nom} (${code})`);
  }

  groupeDe(nom: string) {
    return this.groupesService.trouver('DEV101');
  }
}

📄 src/groupes.service.ts

import { Injectable } from '@nestjs/common';
import { StagiairesService } from './stagiaires.service';

@Injectable()
export class GroupesService {
  constructor(private readonly stagiairesService: StagiairesService) {}   // …et les groupes des stagiaires

  trouver(code: string) {
    return { code, effectif: this.stagiairesService.stagiairesDu(code).length };
  }
}

Erreur au démarrage :

Nest can't resolve dependencies of the StagiairesService (?). Please make sure that the argument at index [0] is available in the current module.

Potential solutions:
- The dependency at index [0] appears to be undefined at runtime
- This commonly occurs when using 'import type' instead of 'import' for injectable classes

Le message est trompeur: il ne parle pas de cycle mais d'un argument « undefined at runtime », et ne nomme même pas la dépendance. La cause est l'import circulaire entre les deux fichiers: quand Node.js charge stagiaires.service.ts, celui-ci importe groupes.service.ts, qui importe à son tour stagiaires.service.ts… encore en cours de chargement. À ce moment, la classe StagiairesService n'existe pas encore : elle vaut undefined dans les métadonnées. Retenez : « appears to be undefined at runtime » = cherchez un import circulaire (ou un import type sur une classe injectée).

Solution technique : forwardRef

forwardRef(() => Classe) remplace la référence directe par une fonction, appelée plus tard, quand toutes les classes existent. Il faut l'utiliser des deux côtés, avec @Inject:

📄 src/stagiaires.service.ts

import { forwardRef, Inject, Injectable } from '@nestjs/common';
import { GroupesService } from './groupes.service';

@Injectable()
export class StagiairesService {
  constructor(
    @Inject(forwardRef(() => GroupesService))
    private readonly groupesService: GroupesService,
  ) {}

  stagiairesDu(code: string) {
    return ['Ben Ali', 'Trabelsi'].map((nom) => `${nom} (${code})`);
  }

  groupeDe(nom: string) {
    return this.groupesService.trouver('DEV101');
  }
}

📄 src/groupes.service.ts

import { forwardRef, Inject, Injectable } from '@nestjs/common';
import { StagiairesService } from './stagiaires.service';

@Injectable()
export class GroupesService {
  constructor(
    @Inject(forwardRef(() => StagiairesService))
    private readonly stagiairesService: StagiairesService,
  ) {}

  trouver(code: string) {
    return { code, effectif: this.stagiairesService.stagiairesDu(code).length };
  }
}

Résultat réellement obtenu :

démarrage réussi
{ code: 'DEV101', effectif: 2 }
{ code: 'DEV101', effectif: 2 }

Entre deux modules

Le même problème survient quand deux modules s'importent mutuellement :

📄 src/stagiaires.module.ts

import { Module } from '@nestjs/common';
import { GroupesModule } from './groupes.module';

@Module({ imports: [GroupesModule] })
export class StagiairesModule {}

📄 src/groupes.module.ts

import { Module } from '@nestjs/common';
import { StagiairesModule } from './stagiaires.module';

@Module({ imports: [StagiairesModule] })
export class GroupesModule {}

Erreur au démarrage :

Nest cannot create the StagiairesModule instance.
The module at index [0] of the StagiairesModule "imports" array is undefined.

Potential causes:
- A circular dependency between modules. Use forwardRef() to avoid it. Read more: https://docs.nestjs.com/fundamentals/circular-dependency

Ici, NestJS identifie clairement la cause probable. La correction utilise forwardRef dans les imports, des deux côtés :

📄 src/stagiaires.module.ts

import { forwardRef, Module } from '@nestjs/common';
import { GroupesModule } from './groupes.module';

@Module({ imports: [forwardRef(() => GroupesModule)] })
export class StagiairesModule {}

📄 src/groupes.module.ts

import { forwardRef, Module } from '@nestjs/common';
import { StagiairesModule } from './stagiaires.module';

@Module({ imports: [forwardRef(() => StagiairesModule)] })
export class GroupesModule {}

Résultat réellement obtenu :

démarrage réussi

La meilleure solution : supprimer le cycle

forwardRef fait disparaître l'erreur, mais pas le problème de conception : deux classes qui dépendent l'une de l'autre sont fortement couplées et difficiles à tester séparément. Un cycle signale souvent qu'une responsabilité est mal placée. Trois façons de le supprimer :

1. Extraire un service commun: ce dont les deux ont besoin (ici, la relation « quel stagiaire est dans quel groupe ») va dans un troisième service, dont les deux dépendent.
2. Inverser une dépendance: se demander lequel des deux a vraiment besoin de l'autre ; souvent, une seule direction suffit, l'autre méthode étant déplacée.
3. Communiquer par événements: au lieu d'appeler directement l'autre service, on émet un événement (« stagiaire inscrit ») que l'autre écoute (@nestjs/event-emitter, chapitre 15).

Version avec un service extrait, sans aucun forwardRef :

📄 src/inscriptions.service.ts

import { Injectable } from '@nestjs/common';

// Les données partagées sont extraites dans un troisième service, dont les deux autres dépendent
@Injectable()
export class InscriptionsService {
  private readonly inscriptions = [
    { stagiaire: 'Ben Ali', groupe: 'DEV101' },
    { stagiaire: 'Trabelsi', groupe: 'DEV101' },
    { stagiaire: 'Gharbi', groupe: 'DEV102' },
  ];
  stagiairesDu(code: string) {
    return this.inscriptions.filter((i) => i.groupe === code).map((i) => i.stagiaire);
  }
  groupeDe(nom: string) {
    return this.inscriptions.find((i) => i.stagiaire === nom)?.groupe;
  }
}

📄 src/stagiaires.service.ts

import { Injectable } from '@nestjs/common';
import { InscriptionsService } from './inscriptions.service';

@Injectable()
export class StagiairesService {
  constructor(private readonly inscriptions: InscriptionsService) {}
  groupeDe(nom: string) {
    return this.inscriptions.groupeDe(nom);
  }
}

📄 src/groupes.service.ts

import { Injectable } from '@nestjs/common';
import { InscriptionsService } from './inscriptions.service';

@Injectable()
export class GroupesService {
  constructor(private readonly inscriptions: InscriptionsService) {}
  trouver(code: string) {
    return { code, effectif: this.inscriptions.stagiairesDu(code).length };
  }
}

Résultat réellement obtenu :

démarrage réussi
{ code: 'DEV101', effectif: 2 }
DEV101

Les dépendances vont désormais toutes dans le même sens (vers InscriptionsService) : chaque service est testable seul, en fournissant un faux InscriptionsService.

Activités