EventEmitter w Node.js: on, emit, once i własne zdarzenia

EventEmitter to klasa z modułu events w Node, która pozwala obiektowi ogłaszać nazwane zdarzenia. Listener rejestrujesz przez emitter.on('name', fn), a wywołujesz go przez emitter.emit('name', ...args); każdy listener dla tej nazwy się wykonuje, w kolejności dodania, z argumentami, które przekazałeś. Serwery HTTP, streamy i process to EventEmittery, więc te same kilka metod działa w całym 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');

Oba listenery wykonują się między before emit a after emit: emit wywołuje je synchronicznie i wraca dopiero, gdy skończą. Zamień kolejność dwóch wywołań shop.on, a dwie środkowe linie też zamienią się miejscami.

on, once i off

on trzyma listener, dopóki go nie usuniesz, once usuwa go po pierwszym wywołaniu, a off (to samo co removeListener) usuwa jeden. Żeby usunąć listener, potrzebujesz tej samej funkcji, którą dodałeś, więc nadaj jej nazwę zamiast przekazywać arrow function w miejscu.

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 wypisuje się raz, po Adzie. Gdy logOpen zostanie usunięty, nikt już nie nasłuchuje, więc ostatni emit zwraca false; door.removeAllListeners('open') usunąłby oba listenery jednym wywołaniem.

Zdarzenie error

'error' jest wyjątkowe. Jeśli je wyemitujesz i nikt nie nasłuchuje, emit rzuca błąd, a w prawdziwym programie nieprzechwycony wyjątek wywraca proces. Zawsze dodawaj listener 'error' do emiterów, które mogą zawieść, np. streamów i serwerów.

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

Bez listenera emit rzuca wyjątek i łapie go catch; po dodaniu listenera ten sam emit po prostu go wywołuje, a program działa dalej. Każda inna nazwa zdarzenia bez listenerów jest po cichu ignorowana.

Dziedziczenie po EventEmitter we własnej klasie

Zwykle twoja klasa rozszerza EventEmitter, wywołuje super() w konstruktorze i this.emit, gdy coś się dzieje. Wywołujący subskrybują wtedy twój obiekt jak każdy obiekt 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();

Wypisuje 25%, 50%, 75%, 100%, a potem photo.png uploaded. Przenieś up.start() nad dwie linie up.on i nic się nie wypisze: zdarzenia lecą, zanim ktokolwiek nasłuchuje.

Ta sama pułapka dotyczy emitowania w konstruktorze. Biblioteki, które muszą wyemitować zdarzenie od razu, opakowują wywołanie w process.nextTick, które wykonuje się po liniach on wywołującego (zobacz stronę o event loop).

Czekanie na zdarzenie z events.once

events.once(emitter, name) zwraca promise, który przy następnym wyemitowaniu rozwiązuje się z argumentami zdarzenia w postaci tablicy. Dzięki temu jednorazowe zdarzenie staje się czymś, na co możesz poczekać przez await, a promise zostaje odrzucony, jeśli emiter wcześniej wyemituje 'error'.

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

await czeka, aż timer wyemituje ready, a potem tablica rozkłada się na dwa argumenty. Dla zdarzenia, które pojawia się wiele razy, events.on(emitter, name) daje async iterator, po którym przejdziesz pętlą for await.

Częste błędy

Dodawanie listenera w funkcji, która wykonuje się często. Wywoływanie on w każdym handlerze żądania mnoży listenery i zużycie pamięci. Dodaj go raz albo użyj once.

Usuwanie funkcji zapisanej w miejscu. off('data', () => ...) nic nie usuwa, bo ta arrow function jest nowa. Trzymaj referencję do funkcji, którą dodałeś.

Oczekiwanie, że listenery wykonają się później. emit jest synchroniczny, więc wolny listener wstrzymuje kod, który wyemitował zdarzenie. Oznaczenie listenera jako async nie pomaga, bo jego kod i tak działa w tym samym wątku aż do pierwszego await. Podziel ciężką pracę na kawałki z setImmediate pomiędzy nimi albo przenieś ją do wątku roboczego (worker thread).