À propos de ce cours
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
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). EventEmitter2est 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: trueautorise les jokers :'inscription.*'reçoitinscription.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, commegenererPdf(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é ?
Merci pour votre avis sur cet article 🙏
Merci, votre message nous a bien été transmis 🙏
Cette leçon vous a été utile ? Partagez-la !