Twin class

Пакет:
azure-iot-device

Двойник устройства — это документ, описывающий состояние устройства, хранящегося центром Интернета вещей Azure, и доступен, даже если устройство находится в автономном режиме. Он построен около 3 разделов:

  • Теги: пары "ключ-значение", доступные только со стороны службы
  • Требуемые свойства: обновлена службой и получена устройством
  • Сообщаемые свойства: обновлено устройством и получено службой.

Обратите внимание, что хотя это возможность, требуемые и сообщаемые свойства не должны соответствовать, и что логика синхронизации этих двух коллекций, при необходимости, остается пользователю пакета SDK.

Дополнительные сведения см. в разделе Основные сведения обдвойников устройств.

Extends

EventEmitter

Свойства

desiredPath
errorEvent
properties

Требуемые и сообщаемые словари свойств (соответственно, в properties.desired и properties.reported).
userRegisteredDesiredPropertiesListener

Унаследованные свойства

captureRejections

Значение: булево

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

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

Посмотрите, как написать кастомный rejection handler.
defaultMaxListeners

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

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

Это не жёсткое ограничение. Инстанс позволит добавить больше слушателей, но выдаст предупреждение о trace в stderr, EventEmitter указывающее на «возможную утечку памяти 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'.
errorMonitor

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

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

Методы

get()
get(Callback<Twin>)

Получает весь двойник из службы.

Наследуемые методы

addAbortListener(AbortSignal, (event: Event) => void)

Прослушал событие один abort раз на предоставленном signal.

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

Этот API позволяет безопасно использовать AbortSignals в Node.js API, решая эти две проблемы с помощью прослушивания события так 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]();
  }
}
addListener<K>(string | symbol, (args: any[]) => void)

Псевдоним для emitter.on(eventName, listener).
emit<K>(string | symbol, AnyRest)

Синхронно вызывает каждый из прослушивателей, зарегистрированных для события с именем 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
eventNames()

Возвращает массив, в котором перечислены события, для которых у поставщика зарегистрированы прослушиватели. Значения в массиве — это строки или 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) ]
getEventListeners(EventEmitter<DefaultEventMap> | EventTarget, string | symbol)

Возвращает копию массива прослушивателей для события с именем 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] ]
}
getMaxListeners()

Возвращает текущее значение максимального прослушивателя для EventEmitter, заданное emitter.setMaxListeners(n) или значением по умолчанию <xref:EventEmitter.defaultMaxListeners>.
getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

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

Для 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
}
listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

Метод класса, который возвращает количество слушателей для заданного 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
listenerCount<K>(string | symbol, Function)

Возвращает число прослушивателей, прослушивающих событие с именем eventName. Если указана listener, он возвращает количество раз, когда прослушиватель найден в списке прослушивателей события.
listeners<K>(string | symbol)

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

server.on('connection', (stream) => {
  console.log('someone connected!');
});
console.log(util.inspect(server.listeners('connection')));
// Prints: [ [Function] ]
off<K>(string | symbol, (args: any[]) => void)

Псевдоним для emitter.removeListener().
on(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterIteratorOptions) 
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 каждой итерацией — это массив, состоящий из выпущенных аргументов событий.

An 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'
on(EventTarget, string, StaticEventEmitterIteratorOptions)
on<K>(string | symbol, (args: any[]) => void)

Добавляет функцию 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
once(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterOptions)

Создаёт , 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

An 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!
once(EventTarget, string, StaticEventEmitterOptions)
once<K>(string | symbol, (args: any[]) => void)

Добавляет функцию однократного для события с именем . При следующем запуске 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
prependListener<K>(string | symbol, (args: any[]) => void)

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

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

Возвращает ссылку на EventEmitter, чтобы вызовы могли быть связаны.
prependOnceListener<K>(string | symbol, (args: any[]) => void)

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

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

Возвращает ссылку на EventEmitter, чтобы вызовы могли быть связаны.
rawListeners<K>(string | symbol)

Возвращает копию массива прослушивателей для события с именем 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');
removeAllListeners(string | symbol)

Удаляет все прослушиватели или те из указанных eventName.

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

Возвращает ссылку на EventEmitter, чтобы вызовы могли быть связаны.
removeListener<K>(string | symbol, (args: any[]) => void)

Удаляет указанный 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, чтобы вызовы могли быть связаны.
setMaxListeners(number)

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

Возвращает ссылку на EventEmitter, чтобы вызовы могли быть связаны.
setMaxListeners(number, (EventEmitter<DefaultEventMap> | EventTarget)[]) 
import { setMaxListeners, EventEmitter } from 'node:events';

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);
[captureRejectionSymbol]<K>(Error, string | symbol, AnyRest)

Сведения о свойстве

desiredPath 

static desiredPath: string

Значение свойства

string

errorEvent 

static errorEvent: string

Значение свойства

string

properties

Требуемые и сообщаемые словари свойств (соответственно, в properties.desired и properties.reported).

properties: TwinProperties

Значение свойства

TwinProperties

userRegisteredDesiredPropertiesListener 

userRegisteredDesiredPropertiesListener: boolean

Значение свойства

boolean

Сведения об унаследованном свойстве

captureRejections

Значение: булево

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

static captureRejections: boolean

Значение свойства

boolean

Унаследовано от EventEmitter.captureОтклонения

captureRejectionSymbol

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

Посмотрите, как написать кастомный rejection handler.

static captureRejectionSymbol: typeof captureRejectionSymbol

Значение свойства

typeof captureRejectionSymbol

Унаследовано от EventEmitter.captureRejectionSymbol

defaultMaxListeners

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

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

Это не жёсткое ограничение. Инстанс позволит добавить больше слушателей, но выдаст предупреждение о trace в stderr, EventEmitter указывающее на «возможную утечку памяти 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'.

static defaultMaxListeners: number

Значение свойства

number

наследуется от EventEmitter.defaultMaxListeners

errorMonitor

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

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

static errorMonitor: typeof errorMonitor

Значение свойства

typeof errorMonitor

Унаследовано от EventEmitter.errorMonitor

Сведения о методе

get() 

function get(): Promise<Twin>

Возвращаемое значение

Promise<Twin>

get(Callback<Twin>)

Получает весь двойник из службы.

function get(callback?: Callback<Twin>)

Параметры

callback

Callback<Twin>

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

Сведения о наследуемом методе

addAbortListener(AbortSignal, (event: Event) => void)

Прослушал событие один abort раз на предоставленном signal.

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

Этот API позволяет безопасно использовать AbortSignals в Node.js API, решая эти две проблемы с помощью прослушивания события так 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]();
  }
}

static function addAbortListener(signal: AbortSignal, resource: (event: Event) => void): Disposable

Параметры

signal

AbortSignal

resource

(event: Event) => void

Возвращаемое значение

Disposable

Одноразовый вариант, который удаляет abort слушателя.

Унаследовано от EventEmitter.addAbortListener

addListener<K>(string | symbol, (args: any[]) => void)

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

function addListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

listener

(args: any[]) => void

Возвращаемое значение

Twin

наследуется от EventEmitter.addListener

emit<K>(string | symbol, AnyRest)

Синхронно вызывает каждый из прослушивателей, зарегистрированных для события с именем 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

function emit<K>(eventName: string | symbol, args: AnyRest): boolean

Параметры

eventName

string | symbol

args

AnyRest

Возвращаемое значение

boolean

наследуется от EventEmitter.emit

eventNames()

Возвращает массив, в котором перечислены события, для которых у поставщика зарегистрированы прослушиватели. Значения в массиве — это строки или 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) ]

function eventNames(): (string | symbol)[]

Возвращаемое значение

(string | symbol)[]

наследуется от EventEmitter.eventNames

getEventListeners(EventEmitter<DefaultEventMap> | EventTarget, string | symbol)

Возвращает копию массива прослушивателей для события с именем 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] ]
}

static function getEventListeners(emitter: EventEmitter<DefaultEventMap> | EventTarget, name: string | symbol): Function[]

Параметры

emitter

EventEmitter<DefaultEventMap> | EventTarget

name

string | symbol

Возвращаемое значение

Function[]

Унаследовано от EventEmitter.getEventListeners

getMaxListeners()

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

function getMaxListeners(): number

Возвращаемое значение

number

наследуется от EventEmitter.getMaxListeners

getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

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

Для 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
}

static function getMaxListeners(emitter: EventEmitter<DefaultEventMap> | EventTarget): number

Параметры

emitter

EventEmitter<DefaultEventMap> | EventTarget

Возвращаемое значение

number

наследуется от EventEmitter.getMaxListeners

listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

Предупреждение

Теперь этот API является нерекомендуемым.

Since v3.2.0 - Use listenerCount instead.

Метод класса, который возвращает количество слушателей для заданного 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

static function listenerCount(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol): number

Параметры

emitter

EventEmitter<DefaultEventMap>

Эмиттер в запрос

eventName

string | symbol

Имя события

Возвращаемое значение

number

наследуется от EventEmitter.listenerCount

listenerCount<K>(string | symbol, Function)

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

function listenerCount<K>(eventName: string | symbol, listener?: Function): number

Параметры

eventName

string | symbol

Имя прослушиваемого события

listener

Function

Функция обработчика событий

Возвращаемое значение

number

наследуется от EventEmitter.listenerCount

listeners<K>(string | symbol)

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

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

function listeners<K>(eventName: string | symbol): Function[]

Параметры

eventName

string | symbol

Возвращаемое значение

Function[]

наследуется от EventEmitter.listeners

off<K>(string | symbol, (args: any[]) => void)

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

function off<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

listener

(args: any[]) => void

Возвращаемое значение

Twin

наследуется от EventEmitter.off

on(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterIteratorOptions) 

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 каждой итерацией — это массив, состоящий из выпущенных аргументов событий.

An 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'

static function on(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: StaticEventEmitterIteratorOptions): AsyncIterator<any[], any, any>

Параметры

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterIteratorOptions

Возвращаемое значение

AsyncIterator<any[], any, any>

T, AsyncIterator который повторяет eventName события, исходящие от emitter

наследуется от EventEmitter.on

on(EventTarget, string, StaticEventEmitterIteratorOptions) 

static function on(emitter: EventTarget, eventName: string, options?: StaticEventEmitterIteratorOptions): AsyncIterator<any[], any, any>

Параметры

emitter

EventTarget

eventName

string

options

StaticEventEmitterIteratorOptions

Возвращаемое значение

AsyncIterator<any[], any, any>

наследуется от EventEmitter.on

on<K>(string | symbol, (args: any[]) => void)

Добавляет функцию 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

function on<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

Имя события.

listener

(args: any[]) => void

Функция обратного вызова

Возвращаемое значение

Twin

наследуется от EventEmitter.on

once(EventEmitter<DefaultEventMap>, string | symbol, StaticEventEmitterOptions)

Создаёт , 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

An 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!

static function once(emitter: EventEmitter<DefaultEventMap>, eventName: string | symbol, options?: StaticEventEmitterOptions): Promise<any[]>

Параметры

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterOptions

Возвращаемое значение

Promise<any[]>

наследуется от EventEmitter.один раз

once(EventTarget, string, StaticEventEmitterOptions) 

static function once(emitter: EventTarget, eventName: string, options?: StaticEventEmitterOptions): Promise<any[]>

Параметры

emitter

EventTarget

eventName

string

options

StaticEventEmitterOptions

Возвращаемое значение

Promise<any[]>

наследуется от EventEmitter.один раз

once<K>(string | symbol, (args: any[]) => void)

Добавляет функцию однократного для события с именем . При следующем запуске 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

function once<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

Имя события.

listener

(args: any[]) => void

Функция обратного вызова

Возвращаемое значение

Twin

наследуется от EventEmitter.один раз

prependListener<K>(string | symbol, (args: any[]) => void)

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

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

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

function prependListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

Имя события.

listener

(args: any[]) => void

Функция обратного вызова

Возвращаемое значение

Twin

унаследован от EventEmitter.prependListener

prependOnceListener<K>(string | symbol, (args: any[]) => void)

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

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

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

function prependOnceListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

Имя события.

listener

(args: any[]) => void

Функция обратного вызова

Возвращаемое значение

Twin

наследуется от EventEmitter.prependOnceListener

rawListeners<K>(string | symbol)

Возвращает копию массива прослушивателей для события с именем 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');

function rawListeners<K>(eventName: string | symbol): Function[]

Параметры

eventName

string | symbol

Возвращаемое значение

Function[]

наследуется от EventEmitter.rawListeners

removeAllListeners(string | symbol)

Удаляет все прослушиватели или те из указанных eventName.

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

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

function removeAllListeners(eventName?: string | symbol): Twin

Параметры

eventName

string | symbol

Возвращаемое значение

Twin

наследуется от EventEmitter.removeAllListeners

removeListener<K>(string | symbol, (args: any[]) => void)

Удаляет указанный 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, чтобы вызовы могли быть связаны.

function removeListener<K>(eventName: string | symbol, listener: (args: any[]) => void): Twin

Параметры

eventName

string | symbol

listener

(args: any[]) => void

Возвращаемое значение

Twin

наследуется от EventEmitter.removeListener

setMaxListeners(number)

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

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

function setMaxListeners(n: number): Twin

Параметры

n

number

Возвращаемое значение

Twin

наследуется от EventEmitter.setMaxListeners

setMaxListeners(number, (EventEmitter<DefaultEventMap> | EventTarget)[]) 

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

const target = new EventTarget();
const emitter = new EventEmitter();

setMaxListeners(5, target, emitter);

static function setMaxListeners(n?: number, eventTargets: (EventEmitter<DefaultEventMap> | EventTarget)[])

Параметры

n

number

Неотрицательное число. Максимальное количество слушателей на EventTarget мероприятие.

eventTargets

(EventEmitter<DefaultEventMap> | EventTarget)[]

Ноль или более экземпляров {EventTarget} или {EventEmitter}. Если их не указано, n устанавливается как максимальный максимум по умолчанию для всех вновь созданных объектов {EventTarget} и {EventEmitter}.

наследуется от EventEmitter.setMaxListeners

[captureRejectionSymbol]<K>(Error, string | symbol, AnyRest) 

function [captureRejectionSymbol]<K>(error: Error, event: string | symbol, args: AnyRest)

Параметры

error

Error

event

string | symbol

args

AnyRest

Унаследованный от EventEmitter.__@captureRejectionSymbol@141