Node.js EventEmitter: on, emit, once und eigene Events

EventEmitter ist die Klasse im events-Modul von Node, mit der ein Objekt benannte Events ankündigen kann. Du registrierst einen Listener mit emitter.on('name', fn) und löst ihn mit emitter.emit('name', ...args) aus; jeder Listener für diesen Namen läuft, in der Reihenfolge, in der er hinzugefügt wurde, mit den Argumenten, die du übergibst. HTTP-Server, Streams und process sind alle EventEmitter, deshalb funktionieren dieselben paar Methoden überall in 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');

Beide Listener laufen zwischen before emit und after emit: emit ruft sie synchron auf und kehrt erst zurück, wenn sie fertig sind. Vertausch die beiden shop.on-Aufrufe, und die beiden mittleren Zeilen tauschen ebenfalls die Plätze.

on, once und off

on behält einen Listener, bis du ihn entfernst, once entfernt ihn nach dem ersten Aufruf, und off (dasselbe wie removeListener) entfernt einen. Zum Entfernen brauchst du genau die Funktion, die du hinzugefügt hast, also gib ihr einen Namen, statt eine Arrow Function direkt zu übergeben.

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 erscheint einmal, nach Ada. Sobald logOpen entfernt ist, hört niemand mehr zu, deshalb gibt das letzte emit false zurück; door.removeAllListeners('open') hätte beide Listener mit einem Aufruf entfernt.

Das error-Event

'error' ist besonders. Wenn du es auslöst und niemand zuhört, wirft emit den Fehler, und in einem echten Programm bringt ein nicht abgefangener Fehler den Prozess zum Absturz. Häng an Emitter, die fehlschlagen können, etwa Streams und Server, immer einen 'error'-Listener.

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');

Ohne Listener wirft emit, und der catch fängt den Fehler; mit dem Listener ruft dasselbe emit ihn einfach auf, und das Programm läuft weiter. Jeder andere Event-Name ohne Listener wird stillschweigend ignoriert.

EventEmitter in einer eigenen Klasse erweitern

Üblich ist, dass deine Klasse EventEmitter erweitert, im Konstruktor super() aufruft und this.emit, wenn etwas passiert. Aufrufer abonnieren dein Objekt dann wie jedes Node-Objekt.

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();

Es gibt 25%, 50%, 75%, 100% und dann photo.png uploaded aus. Schieb up.start() über die beiden up.on-Zeilen, und nichts erscheint: Die Events feuern, bevor jemand zuhört.

Dieselbe Falle gibt es beim Auslösen von Events im Konstruktor. Bibliotheken, die sofort ein Event auslösen müssen, packen den Aufruf in process.nextTick, das nach den on-Zeilen des Aufrufers läuft (siehe die Seite zur Event Loop).

Mit events.once auf ein Event warten

events.once(emitter, name) gibt ein Promise zurück, das beim nächsten Auslösen mit den Argumenten des Events als Array aufgelöst wird. So wird aus einem einmaligen Event etwas, auf das du mit await warten kannst, und es wird abgelehnt, wenn der Emitter vorher 'error' auslöst.

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');

Das await pausiert, bis der Timer ready auslöst, dann wird das Array in die beiden Argumente zerlegt. Für ein Event, das oft feuert, liefert events.on(emitter, name) einen Async Iterator, den du mit for await durchlaufen kannst.

Häufige Fehler

Einen Listener in einer Funktion hinzufügen, die oft läuft. on in jedem Request-Handler aufzurufen, stapelt Listener und Speicher. Füg ihn einmal hinzu oder nimm once.

Eine Inline-Funktion entfernen. off('data', () => ...) entfernt nichts, weil diese Arrow Function eine neue ist. Behalte eine Referenz auf die Funktion, die du hinzugefügt hast.

Erwarten, dass Listener später laufen. emit ist synchron, ein langsamer Listener hält also den Code auf, der das Event ausgelöst hat. Den Listener als async zu markieren hilft nicht, denn sein Code läuft bis zum ersten await trotzdem im selben Thread. Teil schwere Arbeit in Stücke mit setImmediate dazwischen auf, oder verschieb sie in einen Worker-Thread.