Les événements du cycle de vie (OnModuleInit, OnApplicationShutdown…)

Deux événements au démarrage, trois à l'arrêt.

Les cinq événements

Ces méthodes peuvent être écrites dans les providers (services), les contrôleurs et les classes de module. Implémenter l'interface (implements OnModuleInit) n'est pas obligatoire mais fortement conseillé : TypeScript vérifie alors le nom et la signature de la méthode.

La démonstration

Un service de stagiaires charge ses données au démarrage (de façon asynchrone, pour simuler une lecture en base) ; un service de statistiques, dans un autre module, en dépend.

📄 src/stagiaires.module.ts

import {
  BeforeApplicationShutdown, Injectable, Module, OnApplicationBootstrap, OnApplicationShutdown,
  OnModuleDestroy, OnModuleInit,
} from '@nestjs/common';

const attendre = (ms: number) => new Promise((r) => setTimeout(r, ms));

@Injectable()
export class StagiairesService
  implements OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, BeforeApplicationShutdown, OnApplicationShutdown
{
  private stagiaires: string[] = [];

  async onModuleInit() {
    await attendre(50);                               // NestJS attend la fin de la promesse
    this.stagiaires = ['Ben Ali', 'Trabelsi', 'Gharbi'];
    console.log(`StagiairesService.onModuleInit : ${this.stagiaires.length} stagiaires chargés`);
  }
  onApplicationBootstrap() {
    console.log('StagiairesService.onApplicationBootstrap');
  }
  onModuleDestroy() {
    console.log('StagiairesService.onModuleDestroy');
  }
  beforeApplicationShutdown(signal?: string) {
    console.log(`StagiairesService.beforeApplicationShutdown (signal : ${signal ?? 'aucun'})`);
  }
  onApplicationShutdown(signal?: string) {
    console.log(`StagiairesService.onApplicationShutdown (signal : ${signal ?? 'aucun'})`);
  }
  compter() {
    return this.stagiaires.length;
  }
}

@Module({ providers: [StagiairesService], exports: [StagiairesService] })
export class StagiairesModule implements OnModuleInit {
  onModuleInit() {
    console.log('StagiairesModule.onModuleInit');
  }
}

📄 src/app.module.ts

import { Injectable, Module, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
import { StagiairesModule, StagiairesService } from './stagiaires.module';

@Injectable()
export class StatistiquesService implements OnModuleInit, OnApplicationBootstrap {
  constructor(private readonly stagiaires: StagiairesService) {}
  onModuleInit() {
    console.log(`StatistiquesService.onModuleInit : ${this.stagiaires.compter()} stagiaires visibles`);
  }
  onApplicationBootstrap() {
    console.log('StatistiquesService.onApplicationBootstrap');
  }
}

@Module({ imports: [StagiairesModule], providers: [StatistiquesService] })
export class AppModule {}

📄 src/main.ts

import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, { logger: false });
  app.enableShutdownHooks();
  console.log('--- app.listen()');
  await app.listen(0);
  console.log('--- application démarrée');
  console.log('--- app.close()');
  await app.close();
  console.log('--- terminé');
}
bootstrap();

Terminal :

--- app.listen()
StagiairesService.onModuleInit : 3 stagiaires chargés
StagiairesModule.onModuleInit
StatistiquesService.onModuleInit : 3 stagiaires visibles
StagiairesService.onApplicationBootstrap
StatistiquesService.onApplicationBootstrap
--- application démarrée
--- app.close()
StagiairesService.onModuleDestroy
StagiairesService.beforeApplicationShutdown (signal : aucun)
StagiairesService.onApplicationShutdown (signal : aucun)
--- terminé

Lecture de la trace

• Les événements de démarrage sont déclenchés par app.listen() (ou app.init()), pas par NestFactory.create().
• Les modules importés sont initialisés avant le module qui les importe : StatistiquesService trouve donc les 3 stagiaires déjà chargés. Dans un module, les providers passent avant la classe du module.
• onModuleInit est async: NestJS attend la fin de la promesse (50 ms ici) avant de continuer. L'application ne répond donc pas aux requêtes tant que les données ne sont pas chargées.
• onApplicationBootstrap n'est appelé qu'une fois tous les modules initialisés : c'est le bon moment pour une action qui suppose que tout est prêt.
• À l'arrêt avec app.close(), le paramètre signal est vide. Il vaut 'SIGTERM' ou 'SIGINT' quand l'arrêt vient du système.

enableShutdownHooks et les signaux

En production, l'application n'est pas arrêtée par app.close() mais par un signal du système : SIGTERM envoyé par PM2, Docker ou un redéploiement, SIGINT quand vous appuyez sur Ctrl+C. Par défaut, NestJS n'écoute pas ces signaux (cela consomme des ressources) : les trois événements d'arrêt ne seraient pas appelés. Il faut l'activer explicitement :

// main.ts
const app = await NestFactory.create(AppModule);
app.enableShutdownHooks();   // les événements d'arrêt sont déclenchés par SIGTERM, SIGINT…
await app.listen(3000);

Lancez npm run start:dev puis Ctrl+C : les méthodes d'arrêt s'exécutent et affichent signal : SIGINT.

Usages courants

Activités

import { readFile } from 'node:fs/promises';
import { join } from 'node:path';

@Injectable()
export class GroupesService implements OnModuleInit {
  private groupes: Groupe[] = [];

  async onModuleInit() {
    const chemin = join(process.cwd(), 'src', 'donnees', 'groupes.json');
    try {
      this.groupes = JSON.parse(await readFile(chemin, 'utf8'));
    } catch (e) {
      throw new Error(`Impossible de charger les groupes depuis ${chemin} : ${(e as Error).message}`);
    }
  }
}

onModuleInit() {
  const { etablissement, anneeScolaire } = this.options;
  if (!etablissement?.trim()) throw new Error('ParametresModule : etablissement est obligatoire');
  const m = /^(\d{4})-(\d{4})$/.exec(anneeScolaire);
  if (!m || Number(m[2]) !== Number(m[1]) + 1) {
    throw new Error(`ParametresModule : anneeScolaire invalide (« ${anneeScolaire} »), format attendu 2026-2027`);
  }
}