Avez-vous une question? (216) 97 656 803 hajjriadh@gmail.com
NestJS

Les événements internes (@nestjs/event-emitter)

Cette leçon découple les parties d'une application avec @nestjs/event-emitter. Un service annonce ce qui s'est passé, une inscription par exemple, avec emit, sans connaître ceux qui réagissent. Des au...

0 chapitres 0 QCM Accès gratuit
Les événements internes (@nestjs/event-emitter)

À propos de ce cours

Cette leçon découple les parties d'une application avec @nestjs/event-emitter. Un service annonce ce qui s'est passé, une inscription par exemple, avec emit, sans connaître ceux qui réagissent. Des auditeurs @OnEvent envoient un e-mail, tiennent un journal ou mettent à jour des statistiques. L'exécution montre l'ordre réel : les auditeurs synchrones avant la suite du service, les auditeurs asynchrones après la réponse au client. Elle montre aussi qu'une erreur dans un auditeur asynchrone est journalisée sans casser la requête, et quand emitAsync attend vraiment. Activités corrigées.

Objectifs de la leçon

  • Émettre un événement et l'écouter avec @OnEvent.
  • Distinguer auditeurs synchrones et asynchrones.
  • Comprendre ce que devient une erreur dans un auditeur.
  • Savoir quand emitAsync attend les auditeurs.
Le problème

Après une inscription, il faut envoyer un e-mail, écrire dans le journal, mettre à jour les statistiques, peut-être prévenir le formateur. Si InscriptionsService appelle lui-même MailService, JournalService, StatistiquesService…, il dépend de tout le monde, et chaque nouvelle réaction oblige à le modifier. Avec des événements, le service se contente d'annoncer « une inscription a été créée » ; chaque module intéressé l'écoute de son côté.

npm install @nestjs/event-emitter

Émission et écoute d'événements

Le service émet ; chaque auditeur réagit indépendamment.

📄 src/inscriptions/inscription-creee.event.ts

// L'événement : une classe simple qui transporte les données utiles
export class InscriptionCreeeEvent {
  static readonly NOM = 'inscription.creee';
  constructor(
    public readonly id: number,
    public readonly email: string,
    public readonly formation: string,
  ) {}
}

📄 src/inscriptions/inscriptions.service.ts

import { Injectable } from '@nestjs/common';
import { EventEmitter2 } from '@nestjs/event-emitter';
import { InscriptionCreeeEvent } from './inscription-creee.event';

@Injectable()
export class InscriptionsService {
  private dernierId = 0;
  constructor(private readonly evenements: EventEmitter2) {}

  inscrire(email: string, formation: string) {
    const id = ++this.dernierId;
    console.log(`[service] inscription ${id} enregistrée`);
    // Le service annonce ce qui s'est passé, sans savoir qui écoute
    this.evenements.emit(InscriptionCreeeEvent.NOM, new InscriptionCreeeEvent(id, email, formation));
    console.log(`[service] événement émis, on répond au client`);
    return { id, email, formation };
  }

  async inscrireEnAttendant(email: string, formation: string) {
    const id = ++this.dernierId;
    const resultats = await this.evenements.emitAsync(InscriptionCreeeEvent.NOM, new InscriptionCreeeEvent(id, email, formation));
    return { id, auditeurs: resultats.length };
  }

  async genererAttestation(id: number) {
    const [chemin] = await this.evenements.emitAsync('attestation.demandee', { id });
    return { id, chemin };
  }

  annuler(id: number) {
    this.evenements.emit('inscription.annulee', { id });
    return { id, annulee: true };
  }
}

📄 src/notifications/notifications.listener.ts

import { Injectable } from '@nestjs/common';
import { OnEvent } from '@nestjs/event-emitter';
import { InscriptionCreeeEvent } from '../inscriptions/inscription-creee.event';

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

@Injectable()
export class NotificationsListener {
  // Auditeur synchrone : exécuté pendant emit(), avant la suite du service
  @OnEvent(InscriptionCreeeEvent.NOM)
  journaliser(e: InscriptionCreeeEvent) {
    console.log(`[journal] ${e.email} inscrit à « ${e.formation} »`);
  }

  // Auditeur asynchrone : lancé au prochain tour de boucle, n'attend pas
  @OnEvent(InscriptionCreeeEvent.NOM, { async: true })
  async envoyerEmail(e: InscriptionCreeeEvent) {
    await pause(200);                     // simule l'envoi d'un e-mail
    console.log(`[e-mail] confirmation envoyée à ${e.email}`);
  }

  @OnEvent(InscriptionCreeeEvent.NOM, { async: true })
  async mettreAJourStatistiques(e: InscriptionCreeeEvent) {
    if (e.formation === 'Inconnue') throw new Error('formation inconnue dans les statistiques');
    console.log(`[stats] +1 pour « ${e.formation} »`);
  }

  // Sans { async: true } : la promesse renvoyée est attendue par emitAsync()
  @OnEvent('attestation.demandee')
  async genererPdf(charge: { id: number }) {
    await pause(200);                     // simule la génération d'un PDF
    console.log(`[pdf] attestation ${charge.id} générée`);
    return `attestations/${charge.id}.pdf`;
  }

  // Joker : tous les événements « inscription.* » (wildcard: true dans forRoot)
  @OnEvent('inscription.*')
  audit(charge: { id: number }) {
    console.log(`[audit] événement inscription.* reçu (id ${charge.id})`);
  }
}

📄 src/app.module.ts

import { Module } from '@nestjs/common';
import { EventEmitterModule } from '@nestjs/event-emitter';
import { InscriptionsController } from './inscriptions/inscriptions.controller';
import { InscriptionsService } from './inscriptions/inscriptions.service';
import { NotificationsListener } from './notifications/notifications.listener';

@Module({
  imports: [EventEmitterModule.forRoot({ wildcard: true, delimiter: '.' })],
  controllers: [InscriptionsController],
  providers: [InscriptionsService, NotificationsListener],
})
export class AppModule {}
  • L'événement est une classe: les données transportées sont typées et le nom est défini à un seul endroit (InscriptionCreeeEvent.NOM).
  • EventEmitter2 est injecté comme n'importe quel provider ; emit(nom, charge) déclenche les auditeurs.
  • @OnEvent(nom) sur une méthode d'un provider. { async: true }: l'auditeur est lancé plus tard, sans retarder la suite.
  • wildcard: true autorise les jokers : 'inscription.*' reçoit inscription.creee, inscription.annulee…

Résultat réellement obtenu :

— emit() : la réponse part avant la fin des auditeurs asynchrones
[service] inscription 1 enregistrée
[journal] sami@exemple.tn inscrit à « NestJS »
[audit] événement inscription.* reçu (id 1)
[service] événement émis, on répond au client
[stats] +1 pour « NestJS »
POST /api/inscriptions → 201 {"id":1,"email":"sami@exemple.tn","formation":"NestJS"}  [durée: 47 ms]
[e-mail] confirmation envoyée à sami@exemple.tn

— Un auditeur asynchrone échoue
[service] inscription 2 enregistrée
[journal] ines@exemple.tn inscrit à « Inconnue »
[audit] événement inscription.* reçu (id 2)
[service] événement émis, on répond au client
[Nest] ERROR [Event] formation inconnue dans les statistiques
Error: formation inconnue dans les statistiques
    at …  (pile d\'appels)
POST /api/inscriptions → 201 {"id":2,"email":"ines@exemple.tn","formation":"Inconnue"}
[e-mail] confirmation envoyée à ines@exemple.tn
   l'application répond toujours :
[audit] événement inscription.* reçu (id 1)
DELETE /api/inscriptions/1 → 200 {"id":1,"annulee":true}

— emitAsync() : attendre tous les auditeurs
[journal] omar@exemple.tn inscrit à « SQL »
[audit] événement inscription.* reçu (id 3)
[stats] +1 pour « SQL »
POST /api/inscriptions/attendre → 201 {"id":3,"auditeurs":4}  [durée: 4 ms]
[e-mail] confirmation envoyée à omar@exemple.tn
[pdf] attestation 3 générée
POST /api/inscriptions/3/attestation → 201 {"id":3,"chemin":"attestations/3.pdf"}  [durée: 204 ms]
Lecture
  • Ordre: les auditeurs synchrones (journal, audit) s'exécutent pendant emit(), avant « on répond au client ». Les auditeurs asynchrones s'exécutent ensuite ; l'e-mail (200 ms) se termine après la réponse : le client n'attend pas.
  • Erreur dans un auditeur asynchrone : elle est journalisée par NestJS (ERROR [Event]), la requête réussit (201), les autres auditeurs s'exécutent, l'application continue. C'est pratique, mais l'erreur passe inaperçue si personne ne lit les journaux : gérez-la dans l'auditeur (TP 9).
  • emitAsync() renvoie le résultat des auditeurs, mais n'attend pas ceux déclarés { async: true }: l'e-mail d'Omar part après la réponse (4 ms). Pour attendre un auditeur, il ne faut pas lui donner cette option : il renvoie simplement une promesse, comme genererPdf (204 ms, chemin renvoyé).

Limites: les événements restent dans le processus. Si l'application s'arrête pendant l'envoi d'un e-mail, il est perdu ; une autre instance ne le reçoit pas. Pour un traitement garanti (nouvelles tentatives, reprise après redémarrage), on passe à une file de messages (BullMQ avec Redis, RabbitMQ). Les événements internes conviennent aux réactions secondaires : notification, journal, cache à invalider.

Activités

Activité 1 Un nouvel auditeur

Ajoutez, sans modifier InscriptionsService, un auditeur qui invalide le cache des statistiques (leçon 15.5) à chaque inscription et à chaque annulation. Pourquoi est-ce l'intérêt principal des événements ?

Voir le corrigé
@Injectable()
export class CacheListener {
  constructor(@Inject(CACHE_MANAGER) private readonly cache: Cache) {}

  @OnEvent('inscription.*', { async: true })
  async invalider() {
    await this.cache.del('statistiques');
  }
}

Le service émetteur n'a pas changé et ne connaît pas le cache. On ajoute ou retire une réaction en ajoutant ou retirant un provider : le principe ouvert/fermé appliqué à l'architecture.

Activité 2 Synchrone ou asynchrone ?

Pour chaque auditeur de document.depose, choisissez synchrone ou { async: true }: (a) envoyer un e-mail au formateur ; (b) refuser le dépôt si le stagiaire a atteint son quota de 20 documents ; (c) écrire une ligne dans le journal d'audit ; (d) générer une miniature de l'image (2 secondes).

Voir le corrigé

(a) Asynchrone : le stagiaire n'a pas à attendre le serveur SMTP. (b) Ce n'est pas un auditeur : une règle qui peut refuser l'action doit être vérifiée dans le service, avant l'enregistrement. Un événement annonce ce qui s'est déjà passé. (c) Synchrone si l'écriture est rapide et doit précéder la réponse ; sinon asynchrone. (d) Asynchrone, et même plutôt une file de tâches (BullMQ), car c'est long et doit survivre à un redémarrage.

Activité 3 Trouver le bug

Ce code doit renvoyer au client le chemin du PDF généré par un auditeur. Il renvoie { chemin: undefined }. Pourquoi ? Corrigez.

// service
const [chemin] = await this.evenements.emitAsync('attestation.demandee', { id });
return { chemin };

// auditeur
@OnEvent('attestation.demandee', { async: true })
async generer(c: { id: number }) { await creerPdf(c.id); return `attestations/${c.id}.pdf`; }
Voir le corrigé

Avec { async: true }, l'auditeur est lancé plus tard : emitAsync n'obtient pas sa valeur de retour (constaté dans la leçon). Correction : retirer { async: true }. L'auditeur renvoie alors sa promesse, que emitAsync attend. Mais si le service a besoin du résultat, un appel direct à un AttestationsService est plus clair qu'un événement.

Activité 4 Journal d'audit

Créez un module AuditModule avec une entité Evenement (nom, charge en JSON, date) et un auditeur @OnEvent('**') qui enregistre tous les événements de l'application. Quelle option de forRoot est nécessaire pour **?

Voir le corrigé

wildcard: true (avec le délimiteur .) : * remplace un segment, ** un nombre quelconque de segments. Pour que le journal connaisse le nom de chaque événement, le plus simple est de le mettre dans la charge : chaque classe d'événement porte une propriété nom (en plus de static NOM), que l'auditeur enregistre avec le reste de la charge en JSON. Déclarez l'auditeur { async: true }: l'écriture en base ne doit pas retarder les requêtes.

À retenir

  • EventEmitterModule.forRoot() ; EventEmitter2.emit(nom, charge) ; @OnEvent(nom) dans un provider.
  • Le service annonce ce qui s'est passé ; les auditeurs réagissent sans que le service les connaisse.
  • Synchrone : avant la suite ; { async: true } : après, sans retarder la réponse.
  • Une erreur d'auditeur asynchrone est journalisée et ne casse pas la requête : la gérer dans l'auditeur.
  • emitAsync attend les auditeurs qui renvoient une promesse, pas ceux déclarés { async: true }.

Cet article vous a-t-il aidé ?