events

Уникальный asyncId, присвоенный ресурсу.

Возвращаемый объект AsyncResource имеет дополнительное свойство eventEmitter, предоставляющее ссылку на этот EventEmitterAsyncResource.

То же значение triggerAsyncId, которое передаётся конструктору AsyncResource.

Вызывает все хуки destroy. Этот метод следует вызывать только один раз. При повторном вызове будет выброшена ошибка. Его необходимо вызывать вручную. Если ресурс будет удалён сборщиком мусора, хуки destroy никогда не будут вызваны.

Значение: Symbol.for('nodejs.rejection')

См. инструкции по созданию пользовательского rejection handler.

Значение: логическое значение

Изменяет параметр captureRejections по умолчанию для всех новых объектов EventEmitter.

По умолчанию для любого отдельного события можно зарегистрировать не более 10 слушателей. Этот лимит можно изменить для отдельных экземпляров EventEmitter с помощью метода emitter.setMaxListeners(n). Чтобы изменить значение по умолчанию для всех экземпляров EventEmitter, можно использовать свойство events.defaultMaxListeners. Если это значение не является положительным числом, возникает исключение RangeError.

Будьте осторожны при изменении events.defaultMaxListeners, поскольку это изменение затрагивает все экземпляры EventEmitter, в том числе созданные до внесения изменения. Однако вызов emitter.setMaxListeners(n) по-прежнему имеет приоритет над events.defaultMaxListeners.

Это не жёсткий лимит. Экземпляр EventEmitter позволит добавить больше слушателей, но выведет в stderr предупреждение с трассировкой о том, что обнаружена «возможная утечка памяти EventEmitter». Для любого отдельного EventEmitter методы emitter.getMaxListeners() и emitter.setMaxListeners() можно использовать, чтобы временно избежать этого предупреждения:

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.setMaxListeners(emitter.getMaxListeners() + 1);
emitter.once('event', () => {
  // do stuff
  emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
});

Флаг командной строки --trace-warnings можно использовать для отображения трассировки стека таких предупреждений.

Сгенерированное предупреждение можно проверить с помощью process.on('warning'); оно будет содержать дополнительные свойства emitter, type и count, которые указывают соответственно на экземпляр эмиттера событий, имя события и количество подключённых слушателей. Свойству name присваивается значение 'MaxListenersExceededWarning'.

Этот символ следует использовать для установки слушателя, который только отслеживает события 'error'. Слушатели, установленные с помощью этого символа, вызываются до обычных слушателей 'error'.

Установка слушателя с помощью этого символа не меняет поведение при возникновении события 'error'. Поэтому процесс по-прежнему завершится аварийно, если обычный слушатель 'error' не установлен.

Однократно прослушивает событие abort у переданного объекта signal.

Прослушивание события abort у сигналов отмены небезопасно и может привести к утечкам ресурсов, поскольку другая сторона, использующая этот сигнал, может вызвать e.stopImmediatePropagation(). К сожалению, Node.js не может изменить это поведение, поскольку оно нарушило бы веб-стандарт. Кроме того, в исходном API легко забыть удалить слушатели.

Этот API позволяет безопасно использовать AbortSignals в API Node.js, решая обе эти проблемы: событие прослушивается так, что stopImmediatePropagation не препятствует вызову слушателя.

Возвращает объект с возможностью освобождения ресурсов, чтобы упростить отмену подписки.

import { addAbortListener } from 'node:events';

function example(signal) {
  let disposable;
  try {
    signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
    disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
    });
  } finally {
    disposable?.[Symbol.dispose]();
  }
}

Возвращает копию массива слушателей события с именем eventName.

Для EventEmitters это работает точно так же, как вызов .listeners у эмиттера.

Для EventTargets это единственный способ получить слушателей события для целевого объекта событий. Это полезно для отладки и диагностики.

import { getEventListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  const listener = () => console.log('Events are fun');
  ee.on('foo', listener);
  console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
}
{
  const et = new EventTarget();
  const listener = () => console.log('Events are fun');
  et.addEventListener('foo', listener);
  console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
}

Возвращает текущее максимальное количество слушателей.

Для EventEmitters это работает точно так же, как вызов .getMaxListeners у эмиттера.

Для EventTargets это единственный способ получить максимальное число слушателей событий для целевого объекта событий. Если количество обработчиков событий у одного EventTarget превышает установленный максимум, EventTarget выведет предупреждение.

import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

{
  const ee = new EventEmitter();
  console.log(getMaxListeners(ee)); // 10
  setMaxListeners(11, ee);
  console.log(getMaxListeners(ee)); // 11
}
{
  const et = new EventTarget();
  console.log(getMaxListeners(et)); // 10
  setMaxListeners(11, et);
  console.log(getMaxListeners(et)); // 11
}

Метод класса, возвращающий количество слушателей для указанного eventName, зарегистрированных у указанного emitter.

import { EventEmitter, listenerCount } from 'node:events';

const myEmitter = new EventEmitter();
myEmitter.on('event', () => {});
myEmitter.on('event', () => {});
console.log(listenerCount(myEmitter, 'event'));
// Prints: 2

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
});

for await (const event of on(ee, 'foo')) {
  // The execution of this inner block is synchronous and it
  // processes one event at a time (even with await). Do not use
  // if concurrent execution is required.
  console.log(event); // prints ['bar'] [42]
}
// Unreachable here

Возвращает AsyncIterator, который перебирает события eventName. Если EventEmitter генерирует событие 'error', возникает исключение. При выходе из цикла все слушатели удаляются. value, возвращаемый на каждой итерации, представляет собой массив, состоящий из аргументов сгенерированного события.

Для отмены ожидания событий можно использовать AbortSignal:

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ac = new AbortController();

(async () => {
  const ee = new EventEmitter();

  // Emit later on
  process.nextTick(() => {
    ee.emit('foo', 'bar');
    ee.emit('foo', 42);
  });

  for await (const event of on(ee, 'foo', { signal: ac.signal })) {
    // The execution of this inner block is synchronous and it
    // processes one event at a time (even with await). Do not use
    // if concurrent execution is required.
    console.log(event); // prints ['bar'] [42]
  }
  // Unreachable here
})();

process.nextTick(() => ac.abort());

Используйте параметр close, чтобы указать массив имён событий, при возникновении которых перебор завершится:

import { on, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

// Emit later on
process.nextTick(() => {
  ee.emit('foo', 'bar');
  ee.emit('foo', 42);
  ee.emit('close');
});

for await (const event of on(ee, 'foo', { close: ['close'] })) {
  console.log(event); // prints ['bar'] [42]
}
// the loop will exit after 'close' is emitted
console.log('done'); // prints 'done'

Создаёт Promise, который выполняется при возникновении указанного события у EventEmitter или отклоняется, если во время ожидания EventEmitter генерирует событие 'error'. Promise разрешается массивом всех аргументов, переданных указанному событию.

Этот метод намеренно универсален и работает с интерфейсом платформы веба EventTarget, у которого нет специальной семантики события 'error' и который не прослушивает событие 'error'.

import { once, EventEmitter } from 'node:events';
import process from 'node:process';

const ee = new EventEmitter();

process.nextTick(() => {
  ee.emit('myevent', 42);
});

const [value] = await once(ee, 'myevent');
console.log(value);

const err = new Error('kaboom');
process.nextTick(() => {
  ee.emit('error', err);
});

try {
  await once(ee, 'myevent');
} catch (err) {
  console.error('error happened', err);
}

Специальная обработка события 'error' применяется только при использовании events.once() для ожидания другого события. Если events.once() используется для ожидания самого события «error'», оно обрабатывается как любое другое событие, без специальной обработки:

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();

once(ee, 'error')
  .then(([err]) => console.log('ok', err.message))
  .catch((err) => console.error('error', err.message));

ee.emit('error', new Error('boom'));

// Prints: ok boom

Для отмены ожидания события можно использовать AbortSignal:

import { EventEmitter, once } from 'node:events';

const ee = new EventEmitter();
const ac = new AbortController();

async function foo(emitter, event, signal) {
  try {
    await once(emitter, event, { signal });
    console.log('event emitted!');
  } catch (error) {
    if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
    } else {
      console.error('There was an error', error.message);
    }
  }
}

foo(ee, 'foo', ac.signal);
ac.abort(); // Abort waiting for the event
ee.emit('foo'); // Prints: Waiting for the event was canceled!

Псевдоним для emitter.on(eventName, listener).

Добавляет функцию listener в конец массива слушателей события с именем eventName. Проверка на то, был ли уже добавлен listener, не выполняется. Несколько вызовов с одинаковым сочетанием eventName и listener приведут к многократному добавлению и вызову listener.

server.on('connection', (stream) => {
  console.log('someone connected!');
});

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

По умолчанию слушатели событий вызываются в порядке их добавления. В качестве альтернативы можно использовать метод emitter.prependListener(), чтобы добавить слушатель события в начало массива слушателей.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Добавляет функцию listener для события с именем eventName, которая срабатывает один раз. При следующем возникновении события eventName этот слушатель удаляется, а затем вызывается.

server.once('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

По умолчанию слушатели событий вызываются в порядке их добавления. В качестве альтернативы можно использовать метод emitter.prependOnceListener(), чтобы добавить слушатель события в начало массива слушателей.

import { EventEmitter } from 'node:events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a

Удаляет указанный listener из массива слушателей события с именем eventName.

const callback = (stream) => {
  console.log('someone connected!');
};
server.on('connection', callback);
// ...
server.removeListener('connection', callback);

removeListener() удаляет из массива слушателей не более одного экземпляра слушателя. Если один и тот же слушатель был добавлен в массив слушателей указанного eventName несколько раз, для удаления каждого экземпляра необходимо вызвать removeListener() несколько раз.

При возникновении события все прикреплённые к нему слушатели вызываются в порядке добавления. Это означает, что любые вызовы removeListener() или removeAllListeners(), выполненные после возникновения события и до завершения работы последнего слушателя, не удалят их из выполняющегося emit(). Последующие события обрабатываются ожидаемым образом.

import { EventEmitter } from 'node:events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A

Поскольку слушатели управляются с помощью внутреннего массива, вызов этого метода изменит индексы всех слушателей, зарегистрированных после удаляемого слушателя. Это не повлияет на порядок вызова слушателей, однако любые копии массива слушателей, возвращённые методом emitter.listeners(), потребуется создать заново.

Если одна функция была добавлена как обработчик одного события несколько раз (как в примере ниже), removeListener() удалит экземпляр, добавленный последним. В примере удаляется слушатель once('ping'):

import { EventEmitter } from 'node:events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

Псевдоним для emitter.removeListener().

Удаляет все слушатели или только слушателей указанного eventName.

Не рекомендуется удалять слушателей, добавленных в других частях кода, особенно если экземпляр EventEmitter был создан другим компонентом или модулем (например, сокетами или файловыми потоками).

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

По умолчанию EventEmitters выводят предупреждение, если для определённого события добавлено более 10 слушателей. Это полезное значение по умолчанию, помогающее обнаруживать утечки памяти. Метод emitter.setMaxListeners() позволяет изменить лимит для этого конкретного экземпляра EventEmitter. Значение можно установить равным Infinity (или 0), чтобы указать неограниченное количество слушателей.

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

Возвращает текущее максимальное количество слушателей для EventEmitter, заданное с помощью emitter.setMaxListeners(n) или равное значению по умолчанию EventEmitter.defaultMaxListeners.

Возвращает копию массива слушателей события с именем eventName.

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]

Возвращает копию массива слушателей события с именем eventName, включая обёртки (например, созданные методом .once()).

import { EventEmitter } from 'node:events';
const emitter = new EventEmitter();
emitter.once('log', () => console.log('log once'));

// Returns a new Array with a function `onceWrapper` which has a property
// `listener` which contains the original listener bound above
const listeners = emitter.rawListeners('log');
const logFnWrapper = listeners[0];

// Logs "log once" to the console and does not unbind the `once` event
logFnWrapper.listener();

// Logs "log once" to the console and removes the listener
logFnWrapper();

emitter.on('log', () => console.log('log persistently'));
// Will return a new Array with a single function bound by `.on()` above
const newListeners = emitter.rawListeners('log');

// Logs "log persistently" twice
newListeners[0]();
emitter.emit('log');

Синхронно вызывает каждый из слушателей, зарегистрированных для события с именем eventName, в порядке их регистрации, передавая каждому из них указанные аргументы.

Возвращает true, если у события есть слушатели, и false в противном случае.

import { EventEmitter } from 'node:events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

console.log(myEmitter.listeners('event'));

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// [
//   [Function: firstListener],
//   [Function: secondListener],
//   [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener

Возвращает количество слушателей события с именем eventName. Если указан listener, метод вернёт количество его вхождений в список слушателей события.

Добавляет функцию listener в начало массива слушателей события с именем eventName. Проверка на то, был ли уже добавлен listener, не выполняется. Несколько вызовов с одинаковым сочетанием eventName и listener приведут к многократному добавлению и вызову listener.

server.prependListener('connection', (stream) => {
  console.log('someone connected!');
});

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

Добавляет функцию listener для события с именем eventName в начало массива слушателей; функция срабатывает один раз. При следующем возникновении события eventName этот слушатель удаляется, а затем вызывается.

server.prependOnceListener('connection', (stream) => {
  console.log('Ah, we have our first user!');
});

Возвращает ссылку на EventEmitter, чтобы вызовы можно было объединять в цепочку.

Возвращает массив событий, для которых эмиттер зарегистрировал слушателей. Значения в массиве представлены строками или Symbols.

import { EventEmitter } from 'node:events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]

Если указан, соответствующий AbortController можно использовать для отмены асинхронного действия.

Тип асинхронного события; это свойство необходимо при непосредственном создании экземпляра EventEmitterAsyncResource, а не при создании экземпляра дочернего класса.

Включает автоматический перехват отклонения промиса.

Имена событий, которые завершат итерацию.

Верхний порог. Эмиттер приостанавливается каждый раз, когда размер буферизованных событий превышает это значение. Поддерживается только эмиттерами, реализующими методы pause() и resume().

Нижний порог. Эмиттер возобновляет работу каждый раз, когда размер буферизованных событий становится меньше этого значения. Поддерживается только эмиттерами, реализующими методы pause() и resume().

Можно использовать для отмены ожидания событий.