Навигация

EventEmitter и события

Большая часть Node построена на событиях: сервер сообщает о новом соединении, сокет — о пришедших данных, поток — об окончании файла, а приложение — о том, что заказ оплачен. За всем этим стоит один механизм: объект-излучатель и подписанные на него функции. Разберём, как EventEmitter вызывает слушателей, почему событие error особенное, откуда берутся утечки и где заканчиваются границы этого паттерна.

Содержание

  1. Зачем серверу события
  2. Базовый API: on, once, off, emit
  3. Синхронность emit
  4. Событие error
  5. Утечки слушателей и maxListeners
  6. Асинхронные слушатели и captureRejections
  7. Промисы и итераторы поверх событий
  8. Паттерн observer в сервисе
  9. Границы применимости: очередь, стрим, брокер
  10. Отличия от браузерных событий
  11. Эксперименты
  12. Ключевые тезисы для интервью
  13. Заключение
  14. Полезные ссылки

Зачем серверу события

Почти все объекты, которые вы получаете от стандартной библиотеки, — это 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()
thiscurrentTargetсам 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 — стек для предупреждений о слушателях