EventEmitter Node.js : on, emit, once et événements

EventEmitter est la classe du module events de Node qui permet à un objet d'annoncer des événements nommés. Vous enregistrez un listener avec emitter.on('name', fn) et vous le déclenchez avec emitter.emit('name', ...args) ; chaque listener de ce nom s'exécute, dans l'ordre où il a été ajouté, avec les arguments passés. Les serveurs HTTP, les streams et process sont tous des EventEmitters, donc les mêmes quelques méthodes marchent partout dans Node.

const EventEmitter = require('events');

const shop = new EventEmitter();

shop.on('order', (item, qty) => {
    console.log('order received:', qty, 'x', item);
});
shop.on('order', (item) => {
    console.log('update stock for', item);
});

console.log('before emit');
shop.emit('order', 'coffee', 2);
console.log('after emit');

Les deux listeners s'exécutent entre before emit et after emit : emit les appelle de façon synchrone et ne rend la main qu'une fois qu'ils ont fini. Inversez les deux appels à shop.on et les deux lignes du milieu s'inversent aussi.

on, once et off

on garde un listener jusqu'à ce que vous le retiriez, once le retire après le premier appel, et off (identique à removeListener) en retire un. Pour retirer un listener, il faut la même fonction que celle ajoutée, donc donnez-lui un nom au lieu de passer une fonction fléchée directement.

const EventEmitter = require('events');
const door = new EventEmitter();

function logOpen(who) {
    console.log('opened by', who);
}

door.on('open', logOpen);
door.once('open', () => console.log('first open ever'));

door.emit('open', 'Ada');
door.emit('open', 'Linus');

door.off('open', logOpen);
console.log('listeners left:', door.listenerCount('open'));
console.log('emit returned', door.emit('open', 'Grace'));

first open ever s'affiche une seule fois, après Ada. Une fois logOpen retiré, plus personne n'écoute, donc le dernier emit renvoie false ; door.removeAllListeners('open') aurait supprimé les deux listeners en un seul appel.

L'événement error

'error' est un cas à part. Si vous l'émettez et que personne n'écoute, emit lève l'erreur, et dans un vrai programme une exception non interceptée fait planter le processus. Ajoutez toujours un listener 'error' aux emitters qui peuvent échouer, comme les streams et les serveurs.

const EventEmitter = require('events');
const job = new EventEmitter();

try {
    job.emit('error', new Error('disk full'));
} catch (err) {
    console.log('emit threw:', err.message);
}

job.on('error', (err) => {
    console.log('handled:', err.message);
});
job.emit('error', new Error('disk full'));
console.log('still running');

Sans listener, emit lève l'erreur et le catch la récupère ; une fois le listener ajouté, le même emit se contente de l'appeler et le programme continue. Tout autre nom d'événement sans listener est ignoré sans bruit.

Étendre EventEmitter dans votre propre classe

La façon habituelle de l'utiliser est de faire hériter votre classe de EventEmitter, d'appeler super() dans le constructeur et this.emit quand quelque chose se produit. Les appelants s'abonnent ensuite à votre objet comme à n'importe quel objet Node.

const EventEmitter = require('events');

class Upload extends EventEmitter {
    constructor(name, chunks) {
        super();
        this.name = name;
        this.chunks = chunks;
    }

    start() {
        for (let i = 1; i <= this.chunks; i++) {
            this.emit('progress', Math.round((i / this.chunks) * 100));
        }
        this.emit('done', this.name);
    }
}

const up = new Upload('photo.png', 4);
up.on('progress', (pct) => console.log(pct + '%'));
up.once('done', (name) => console.log(name, 'uploaded'));
up.start();

Le programme affiche 25%, 50%, 75%, 100% puis photo.png uploaded. Placez up.start() au-dessus des deux lignes up.on et rien ne s'affiche : les événements sont émis avant que quiconque n'écoute.

Le même piège existe quand on émet depuis un constructeur. Les bibliothèques qui doivent émettre tout de suite enveloppent l'appel dans process.nextTick, qui s'exécute après les lignes on de l'appelant (voir la page sur l'event loop).

Attendre un événement avec events.once

events.once(emitter, name) renvoie une promesse qui se résout avec les arguments de l'événement, sous forme de tableau, la prochaine fois qu'il est émis. Un événement ponctuel devient ainsi quelque chose que vous pouvez await, et la promesse est rejetée si l'emitter émet 'error' d'abord.

import { EventEmitter, once } from 'events';

const db = new EventEmitter();

setTimeout(() => db.emit('ready', 'v1.4', 3), 100);

console.log('waiting for ready');
const [version, tables] = await once(db, 'ready');
console.log('ready:', version, 'with', tables, 'tables');

L'await met le code en pause jusqu'à ce que le timer émette ready, puis le tableau est déstructuré en deux arguments. Pour un événement émis de nombreuses fois, events.on(emitter, name) donne un itérateur asynchrone que vous pouvez parcourir avec for await.

Erreurs fréquentes

Ajouter un listener dans une fonction appelée souvent. Appeler on dans chaque handler de requête empile les listeners et la mémoire. Ajoutez-le une seule fois, ou utilisez once.

Retirer une fonction écrite en ligne. off('data', () => ...) ne retire rien, car cette fonction fléchée est une nouvelle fonction. Gardez une référence à la fonction ajoutée.

S'attendre à ce que les listeners s'exécutent plus tard. emit est synchrone, donc un listener lent retarde le code qui a émis. Marquer le listener async n'aide pas, car son code s'exécute toujours sur le même thread jusqu'au premier await. Découpez le travail lourd en morceaux séparés par des setImmediate, ou déplacez-le dans un worker thread.