EventEmitter и события
Большая часть Node построена на событиях: сервер сообщает о новом соединении, сокет — о пришедших данных, поток — об окончании файла, а приложение — о том, что заказ оплачен. За всем этим стоит один механизм: объект-излучатель и подписанные на него функции. Разберём, как EventEmitter вызывает слушателей, почему событие error особенное, откуда берутся утечки и где заканчиваются границы этого паттерна.
Содержание
- Зачем серверу события
- Базовый API: on, once, off, emit
- Синхронность emit
- Событие error
- Утечки слушателей и maxListeners
- Асинхронные слушатели и captureRejections
- Промисы и итераторы поверх событий
- Паттерн observer в сервисе
- Границы применимости: очередь, стрим, брокер
- Отличия от браузерных событий
- Эксперименты
- Ключевые тезисы для интервью
- Заключение
- Полезные ссылки
Зачем серверу события
Почти все объекты, которые вы получаете от стандартной библиотеки, — это EventEmitter: http.Server сообщает о request и connection, net.Socket — о data и close, fs.ReadStream — о готовности данных, child_process — о завершении процесса. Даже process и worker работают по той же схеме. Поэтому понимание EventEmitter — это не отдельная библиотека, а ключ к стримам, HTTP и сетевому коду, которые разбираются в следующих статьях.
Идея проста: издатель не знает, кто на него подписан, а подписчик не управляет издателем. Издатель вызывает emit, подписчик получает аргументы и делает свою работу. Это удобно, когда у одного факта несколько независимых реакций: после оплаты заказа нужно отправить письмо, обновить метрику и сбросить кеш, и добавлять новую реакцию не хочется правкой основного сценария.
Обратная сторона — неявность. Из места emit не видно, что произойдёт дальше: какие слушатели висят на событии, сколько их, что они бросают и сколько времени занимают. Именно поэтому в сервисе важно понимать, какие гарантии EventEmitter даёт, а какие нет.
Базовый API: on, once, off, emit
Класс подключается из node:events, а собственный источник событий — это либо экземпляр, либо наследник:
import { EventEmitter } from 'node:events';
class OrderService extends EventEmitter {
async pay(order) {
// ... списание и запись в базу
this.emit('order:paid', { orderId: order.id, total: order.total });
}
}
const orders = new OrderService();
orders.on('order:paid', ({ orderId }) => {
console.log('подготовить чек для', orderId);
});
| Метод | Что делает |
|---|---|
on / addListener | добавляет слушателя в конец списка; повторный вызов с той же функцией добавит её ещё раз |
once | добавляет слушателя, который снимается после первого срабатывания |
off / removeListener | снимает один экземпляр слушателя |
removeAllListeners([event]) | снимает всех слушателей события или весь emitter |
emit(event, ...args) | синхронно вызывает слушателей и возвращает true, если они были |
listenerCount, listeners, rawListeners | инспекция подписок |
prependListener / prependOnceListener | добавляет в начало списка |
eventNames() | события, на которые есть слушатели |
Три детали, которые чаще всего путают.
emit возвращает не результат, а факт. true означает, что хотя бы один слушатель был; вернуть значение из слушателя наружу нельзя. Если вызывающему нужен ответ, EventEmitter — неподходящий инструмент.
off снимает один экземпляр, и это последний добавленный. Если одна и та же функция подписана дважды, понадобится два вызова. Проверка «подписан ли уже» не выполняется: дубликат молча добавится. Для once внутри хранится обёртка, но off с исходной функцией работает — Node сопоставляет её через свойство listener.
Снятие во время рассылки не отменяет текущий emit. Слушатели вызываются по снимку массива на момент вызова: если первый слушатель снял второго, второй всё равно будет вызван в этой же рассылке. То же и с добавлением — новый слушатель попадёт только в следующее событие.
const onPaid = ({ orderId }) => console.log('чек', orderId);
orders.on('order:paid', onPaid);
// ...
orders.off('order:paid', onPaid);
У emitter есть и служебные события newListener и removeListener. Они позволяют, например, вести учёт подписок, но злоупотреблять ими не стоит: подписка внутри newListener меняет порядок слушателей и легко превращается в рекурсию.
Синхронность emit
emit вызывает всех слушателей синхронно, в порядке регистрации, и только потом возвращает управление:
const emitter = new EventEmitter();
emitter.on('demo', () => console.log('первый'));
emitter.on('demo', () => console.log('второй'));
emitter.emit('demo');
console.log('после emit');
// первый
// второй
// после emit
Это не деталь реализации, а контракт с последствиями.
Слушатель блокирует event loop. Пока он работает, цикл не переходит к следующей фазе: не приходят новые запросы, не срабатывают таймеры, не отправляются ответы. Тяжёлая синхронная работа в слушателе — такая же проблема, как в обработчике запроса; порядок очередей разобран в статье «Event Loop в Node.js».
Исключение из слушателя уходит в emit. EventEmitter не ловит ошибки: throw внутри слушателя — обычное синхронное исключение в точке вызова. В HTTP-обработчике оно станет ошибкой запроса, а если emit вызван из таймера или колбэка — попадёт в uncaughtException. При этом оставшиеся слушатели уже не выполнятся.
Асинхронный слушатель никто не ждёт. async-функция возвращает промис, EventEmitter его игнорирует и сразу переходит к следующему слушателю. await внутри слушателя не делает emit асинхронным:
emitter.on('order:paid', async () => {
await sendEmail(); // началось, но emit уже вернулся
});
emitter.emit('order:paid');
console.log('emit вернулся'); // раньше, чем закончится письмо
Вложенный emit идёт в глубину. Если слушатель события A вызывает emit события B, слушатели B выполнятся полностью, прежде чем управление вернётся к оставшимся слушателям A. На маленьком графе это предсказуемо, на большом — превращается в неочевидный порядок инициализации.
Практический вывод: если вызывающему нужен результат или гарантия завершения, это не событие, а вызов функции. Когда нужно дождаться всех обработчиков, держат массив функций и ждут его явно:
const hooks = [sendReceipt, updateMetrics, invalidateCache];
await Promise.all(hooks.map((hook) => hook(order)));
Если же работа действительно побочная и её можно отложить, слушатель сам уводит её из синхронного пути — через setImmediate, очередь или фоновую задачу. Но это решение слушателя, а не свойство emit.
Событие error
У EventEmitter есть одно событие с особым поведением — error. Если на нём нет ни одного слушателя, emit('error', err) не просто ничего не делает, а бросает переданную ошибку, печатает стек и завершает процесс:
const emitter = new EventEmitter();
emitter.emit('error', new Error('boom'));
// Error: boom
// at ...
// процесс завершился с ненулевым кодом
Это осознанное решение: ошибка, о которой никто не подписан, не должна теряться. Слушатель нужен, чтобы взять ответственность на себя:
emitter.on('error', (err) => {
logger.error({ err }, 'сбой в emitter');
});
Тогда процесс продолжит работу, но решение, что делать дальше — деградировать, повторить, остановиться, — остаётся за обработчиком. Логировать и «жить дальше» без оценки последствий опасно: неизвестно, в каком состоянии остался emitter и связанные с ним ресурсы. Общая логика необработанных ошибок процесса разобрана в статье «Асинхронность в Node.js».
Ещё две детали:
emit('error', 'строка')без слушателя приводит кERR_UNHANDLED_ERROR; передавать нужно настоящую ошибку.events.errorMonitor— отдельный символ для мониторинга. Такой слушатель вызывается перед обычными и не отменяет падение. Его ставят, чтобы логировать и отправлять метрики, не перехватывая поведение:
import { EventEmitter, errorMonitor } from 'node:events';
emitter.on(errorMonitor, (err) => metrics.increment('emitter_error'));
emitter.emit('error', new Error('boom')); // всё ещё упадёт
И правило именования: error — не имя для прикладного события. Доменные сбои вроде «платёж отклонён» лучше отдавать обычным событием (payment:rejected), результатом вызова или исключением в вызывающем коде, иначе случайный emit('error') роняет сервис.
Утечки слушателей и maxListeners
По умолчанию EventEmitter предупреждает, если на одно событие добавлено больше десяти слушателей. Это не жёсткий лимит и не ошибка: добавлять можно и дальше, но в stderr печатается MaxListenersExceededWarning с текстом про возможную утечку памяти.
Порог меняют осознанно: emitter.setMaxListeners(20) для известного веера подписок или 0 (он же Infinity) — чтобы отключить предупреждение. 0 без понимания причины — способ спрятать проблему, а не решить её. Глобальный events.defaultMaxListeners меняет значение для всех emitter в процессе, включая созданные раньше.
Откуда берётся настоящая утечка: подписка живёт дольше, чем объект, ради которого её делали.
// плохо: каждый запрос добавляет ещё одного слушателя на общий emitter
app.get('/orders/:id', async (req, res) => {
metrics.on('flush', () => {
report(req.params.id); // замыкание держит req, res и всё окружение
});
res.json(await getOrder(req.params.id));
});
Слушатель не снимается, его замыкание держит запрос, а побочный эффект выполняется столько раз, сколько было запросов. Похожая история — process.on('SIGTERM') или emitter.on(...) внутри функции, которую вызывают в цикле.
Как искать:
emitter.listenerCount('event')до и после сценария — число должно возвращаться к исходному;--trace-warningsпоказывает стек, где слушатель был добавлен; то же доступно черезprocess.on('warning'), у предупреждения есть поляemitter,typeиcount;- diff двух heap snapshot показывает, кто держит подписку;
- в тестах полезно проверять
listenerCountвafterEach, иначе слушатели протекают между тестами и делают их порядко-зависимыми.
Два способа чинить: подписываться один раз на старте приложения либо возвращать из подписки функцию отписки и вызывать её гарантированно:
function subscribe(emitter, event, handler) {
emitter.on(event, handler);
return () => emitter.off(event, handler);
}
const unsubscribe = subscribe(emitter, 'tick', handler);
try {
await run();
} finally {
unsubscribe();
}
Важно: предупреждение считается на один emitter и одно событие. Если утечка создаёт по одному слушателю на много разных emitter — например, по emitter на каждый запрос, — предупреждения не будет. Поэтому maxListeners — подсказка, а не детектор утечек.
Асинхронные слушатели и captureRejections
async-слушатель возвращает промис, который EventEmitter не сохраняет. Если внутри случится throw, промис отклонится, и никто об этом не узнает: получится unhandledRejection, а с Node 15 это падение процесса. В стеке не будет ни имени события, ни подписчика — только функция слушателя.
const emitter = new EventEmitter();
emitter.on('order:paid', async () => {
throw new Error('письмо не отправилось'); // unhandledRejection
});
emitter.emit('order:paid');
Опция captureRejections меняет это поведение: emitter навешивает обработчик на возвращённый промис и превращает отклонение в событие error того же emitter.
const emitter = new EventEmitter({ captureRejections: true });
emitter.on('order:paid', async (order) => {
await sendEmail(order); // throw → 'error'
});
emitter.on('error', (err) => {
logger.error({ err }, 'слушатель упал');
});
Включается либо в конструкторе, либо глобально через events.captureRejections = true — но глобально лучше не менять поведение чужих emitter без необходимости.
Если нужна своя реакция, а не общий error, объявляют метод по символу:
import { EventEmitter, captureRejectionSymbol } from 'node:events';
class Mailer extends EventEmitter {
constructor() {
super({ captureRejections: true });
}
[captureRejectionSymbol](err, event, ...args) {
logger.error({ err, event, args }, 'сбой подписчика');
}
}
Ограничения, о которых стоит помнить:
captureRejectionsловит только промис, который вернул слушатель.setTimeout(async () => { throw ... })внутри слушателя останется необработанным;- у сгенерированных
error-событий нет собственного catch, поэтому асинхронный обработчикerrorможет зациклиться; дляerrorдержат синхронную функцию; - опция добавляет
try/catchи обработку промиса на каждый вызов, то есть это не бесплатная страховка; - порядок завершения асинхронных слушателей не определён — они идут параллельно. Если порядок важен, это признак, что нужен не emitter, а последовательный вызов.
Промисы и итераторы поверх событий
Событие удобно ждать как промис. Для этого в node:events есть once:
import { once } from 'node:events';
const server = app.listen(3000);
await once(server, 'listening');
Промис резолвится массивом аргументов события и отклоняется, если раньше придёт error. Опция signal позволяет отменить ожидание:
await once(emitter, 'job:done', { signal: AbortSignal.timeout(5_000) });
Для потока событий есть events.on — асинхронный итератор:
import { on } from 'node:events';
for await (const [job] of on(queueEvents, 'job')) {
await handle(job);
}
Он бросает исключение, если emitter emit-ит error, и снимает слушателей при выходе из цикла — в том числе по break или return. Это удобно для потребителя, который живёт ограниченное время: воркер, тест, подписка на время запроса.
Три ловушки.
events.once не подписывается заранее. Промис создаёт подписку только при вызове, поэтому последовательное ожидание нескольких событий теряет те, что пришли между await:
// 'bar' может прийти раньше, чем выполнится вторая строка
await once(emitter, 'foo');
await once(emitter, 'bar');
Если события могут прийти в одной фазе цикла, промисы создают заранее: await Promise.all([once(emitter, 'foo'), once(emitter, 'bar')]).
Итератор буферизует, а не тормозит издателя. У обычного EventEmitter нет pause()/resume(), поэтому backpressure не работает: пока потребитель обрабатывает одно событие, остальные складываются в очередь итератора, и память растёт. События, пришедшие после выхода из цикла, уже некому обработать. Для потока с управлением скоростью нужны стримы — им посвящена следующая статья «Стримы и backpressure».
events.once — не замена проверке состояния. Если сервер уже слушает, await once(server, 'listening') будет ждать вечно. Ожидание события имеет смысл только тогда, когда оно гарантированно ещё впереди.
Паттерн observer в сервисе
EventEmitter — готовая реализация observer: субъект хранит список наблюдателей и уведомляет их об изменении. В сервисе это выглядит так:
// orders/events.js — один экземпляр на процесс
export const orderEvents = new EventEmitter();
// orders/service.js — издатель
orderEvents.emit('order:paid', { orderId, total });
// notifications/listeners.js — подписчики
orderEvents.on('order:paid', sendReceipt);
orderEvents.on('order:paid', updateMetrics);
Что даёт такая схема:
- издатель не импортирует подписчиков и не знает их число;
- новую реакцию добавляют отдельным модулем, не трогая оплату;
- подписчики можно включать и выключать по конфигу;
- снимается циклическая зависимость между модулями.
Где observer уместен: доменные события внутри модуля (оплата → письмо, метрика, инвалидация кеша), аудит и логирование, адаптеры к библиотекам, которые сами работают на событиях, хуки жизненного цикла приложения. Именование в стиле order:paid снижает риск коллизий и делает лог читаемым.
Где он вредит:
- запрос-ответ. Если обработчику нужен результат или ошибка, событие их не вернёт:
emitничего не ждёт и не сообщает, что слушатель упал; - обязательная работа. Событие не гарантирует, что подписчик вообще есть:
emitбез слушателей молча вернётfalse. Обязательный шаг должен быть вызовом функции, а не надеждой на подписку; - межпроцессное взаимодействие. В
clusterкаждый воркер имеет свой экземпляр emitter, поэтому событие в одном процессе не увидят остальные; - транзакции и повторы. Нет доставки, подтверждений, ретраев и идемпотентности — всё это задачи очереди;
- поток данных. Нет backpressure и управления скоростью — это стримы.
Отдельная цена — неявность. Когда подписок много, а emit разбросан по коду, понять, что произойдёт после события, можно только поиском. Помогают: один модуль-реестр событий, логирование факта публикации, явные имена и запрет подписываться на лету в обработчиках запросов.
Границы применимости: очередь, стрим, брокер
EventEmitter часто пытаются использовать как замену инфраструктуре. Проще запомнить таблицу.
| Задача | Инструмент |
|---|---|
| уведомить подписчиков внутри процесса | EventEmitter |
| передать поток данных с управлением скоростью | стримы |
| доставить событие другому инстансу или сервису | брокер, Redis pub/sub |
| гарантировать обработку, ретраи и порядок | очередь задач |
| вернуть результат вызывающему | обычный вызов функции |
| отреагировать на завершение процесса | сигналы и process.on |
Чего у EventEmitter нет по определению:
- гарантии доставки. Слушателя может не быть, процесс может упасть между
emitи обработкой, событие нигде не сохраняется; - повторов и подтверждений. Упавший слушатель не будет вызван снова;
- изоляции. Слушатель живёт в том же процессе и делит с издателем память, event loop и последствия ошибок;
- обратного давления. Издатель не узнаёт, что подписчик не успевает;
- контракта. Имена событий и форма аргументов ничем не проверяются, если не добавить типы или схему вручную.
Отсюда правило: EventEmitter — механизм внутрипроцессного уведомления, а не шина сообщений. Всё, что требует надёжности, выходит за его границы.
Отличия от браузерных событий
API похож названиями, но модели разные. Подробно DOM-события разобраны в статье «Браузерные события: всплытие, погружение, делегирование».
| Аспект | DOM-события | EventEmitter |
|---|---|---|
| Модель | дерево с фазами погружения и всплытия | плоский список слушателей у объекта |
| Распространение | от window к цели и обратно | только прямые подписчики, всплытия нет |
| Отмена | preventDefault, stopPropagation | нет; управляют через emit и off |
| Ошибка в слушателе | уходит в window.onerror, страница живёт | throw из emit, следующие слушатели не вызываются |
| Один раз | { once: true } | emitter.once() |
this | currentTarget | сам emitter |
| Жизненный цикл | DOM-узел и страница | произвольный объект и процесс |
В Node есть и глобальный EventTarget с addEventListener и dispatchEvent, но идиоматичен именно EventEmitter: у него есть особое событие error, лимит слушателей, once-промисы и интеграция со стримами. EventTarget берут, когда нужен код, совместимый с браузерным API.
Эксперименты
Три запуска, которые показывают поведение, которое легко пропустить в документации.
1. Порядок и асинхронный слушатель
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.on('demo', () => console.log('слушатель 1'));
emitter.on('demo', async () => {
await new Promise((resolve) => setTimeout(resolve, 50));
console.log('асинхронный слушатель');
});
console.log(emitter.emit('demo')); // true
console.log('после emit');
// слушатель 1
// true
// после emit
// асинхронный слушатель ← через 50 мс
emit вернул true до того, как асинхронный слушатель закончил: true — это «слушатели были», а не «работа выполнена».
2. error без слушателя и с монитором
Запускать отдельным файлом: без обработчика процесс завершится.
import { EventEmitter, errorMonitor } from 'node:events';
const emitter = new EventEmitter();
emitter.on(errorMonitor, (err) => console.log('монитор:', err.message));
emitter.emit('error', new Error('boom'));
// монитор: boom
// Error: boom ... и процесс падает
Монитор увидел ошибку, но не перехватил её. Добавьте emitter.on('error', ...) — и тот же emit завершится без падения.
3. Утечка и предупреждение
import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
for (let i = 0; i < 12; i++) {
emitter.on('ping', () => {});
}
console.log(emitter.listenerCount('ping')); // 12
// MaxListenersExceededWarning: Possible EventEmitter memory leak detected.
// 11 ping listeners added to [EventEmitter]. MaxListeners is 10.
Запуск с node --trace-warnings file.js покажет стек, где добавлялся одиннадцатый слушатель, — это и есть точка, откуда растёт утечка.
Ключевые тезисы для интервью
emitсинхронный: слушатели выполняются по порядку регистрации до возврата,throwуходит вызывающему, а медленный слушатель блокирует event loop — то есть является частью обработчика запроса.error— единственное событие с поведением по умолчанию: без слушателяemit('error', err)бросает ошибку и роняет процесс, аerrorMonitorпозволяет логировать, не перехватывая её.- Асинхронный слушатель не удерживает
emit: его промис никто не ждёт, reject становитсяunhandledRejection, аcaptureRejectionsперенаправляет его вerrorтого же emitter. - Подписка без отписки — утечка: замыкание держит объект, побочный эффект дублируется, а
MaxListenersExceededWarning— только подсказка, которую ищут черезlistenerCount,--trace-warningsи heap snapshot. onceснимает себя перед первым вызовом,offудаляет один последний экземпляр, а снятие во времяemitне влияет на текущую рассылку — она идёт по снимку.events.onceиevents.onдают промис и асинхронный итератор, но не дают backpressure: медленный потребитель копит события или теряет их, поэтому поток данных — задача стримов.- EventEmitter — observer внутри процесса, а не брокер: нет доставки между инстансами, ретраев, подтверждений и обратной связи; для этого нужны очередь, pub/sub или стрим.
Заключение
EventEmitter — минималистичный механизм: список функций, синхронный вызов, одно особое событие. Этой простоты достаточно, чтобы строить на ней весь сетевой слой Node, но она же требует дисциплины. Публикуя событие, полезно ответить на три вопроса: ждёт ли вызывающий результат, что будет при ошибке слушателя и кто снимет подписку. Если ответы требуют гарантий — это уже не событие, а вызов функции, очередь или стрим. Дальше те же правила применяются к потокам данных, где к событиям добавляется управление скоростью и backpressure.
Полезные ссылки
- Events — полный API EventEmitter
- Error events — поведение
errorбез слушателя - Capture rejections of promises —
captureRejectionsи символ rejection - events.once — ожидание события как промиса
- events.on — асинхронный итератор по событиям
- —trace-warnings — стек для предупреждений о слушателях