Twin class

  • Ссылка
Пакет:
azure-iot-device

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

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

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

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

Extends

EventEmitter

Свойства

desiredPath
errorEvent
properties

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

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

captureRejections

Значение: boolean

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

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

Узнайте, как написать пользовательский rejection handler.
defaultMaxListeners

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

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

Это не жесткое ограничение. Экземпляр EventEmitter позволит добавить больше прослушивателей, но выдаст в stderr предупреждение трассировки, указывающее, что обнаружена "возможная утечка памяти EventEmitter". Для любого отдельного EventEmitteremitter.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 позволяет безопасно использовать AbortSignalинтерфейсы в 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> | _DOMEventTarget, 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) значение defaultMaxListeners или по умолчанию.
getMaxListeners(EventEmitter<DefaultEventMap> | _DOMEventTarget)

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

Для 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, StaticEventEmitterOptions) 
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());
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

Можно 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(_DOMEventTarget, string, StaticEventEmitterOptions)
once<K>(string | symbol, (args: any[]) => void)

Добавляет одноразовую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
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)

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

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

Возвращает ссылку на EventEmitter, чтобы вызовы можно было связать в цепочку.
setMaxListeners(number, (EventEmitter<DefaultEventMap> | _DOMEventTarget)[]) 
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

Значение: boolean

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

static captureRejections: boolean

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

boolean

Наследуется от EventEmitter.captureRejections

captureRejectionSymbol

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

Узнайте, как написать пользовательский rejection handler.

static captureRejectionSymbol: typeof captureRejectionSymbol

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

typeof captureRejectionSymbol

Наследуется от EventEmitter.captureRejectionSymbol

defaultMaxListeners

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

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

Это не жесткое ограничение. Экземпляр EventEmitter позволит добавить больше прослушивателей, но выдаст в stderr предупреждение трассировки, указывающее, что обнаружена "возможная утечка памяти EventEmitter". Для любого отдельного EventEmitteremitter.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 позволяет безопасно использовать AbortSignalинтерфейсы в 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> | _DOMEventTarget, 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> | _DOMEventTarget, name: string | symbol): Function[]

Параметры

emitter

EventEmitter<DefaultEventMap> | _DOMEventTarget

name

string | symbol

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

Function[]

Наследуется от EventEmitter.getEventListeners

getMaxListeners()

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

function getMaxListeners(): number

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

number

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

getMaxListeners(EventEmitter<DefaultEventMap> | _DOMEventTarget)

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

Для 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> | _DOMEventTarget): number

Параметры

emitter

EventEmitter<DefaultEventMap> | _DOMEventTarget

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

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, StaticEventEmitterOptions) 

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

static function on(emitter: EventEmitter<DefaultEventMap>, eventName: string, options?: StaticEventEmitterOptions): AsyncIterableIterator<any>

Параметры

emitter

EventEmitter<DefaultEventMap>

eventName

string

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

options

StaticEventEmitterOptions

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

AsyncIterableIterator<any>

Объект AsyncIterator , который выполняет итерацию eventName событий, создаваемых emitter

Наследуется от 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

Можно 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

once(_DOMEventTarget, string, StaticEventEmitterOptions) 

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

Параметры

emitter

_DOMEventTarget

eventName

string

options

StaticEventEmitterOptions

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

Promise<any[]>

Наследуется от EventEmitter.once

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

Добавляет одноразовую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

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

Параметры

eventName

string | symbol

Имя события.

listener

(args: any[]) => void

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

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

Twin

Наследуется от EventEmitter.once

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)

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

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

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

function setMaxListeners(n: number): Twin

Параметры

n

number

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

Twin

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

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

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> | _DOMEventTarget)[])

Параметры

n

number

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

eventTargets

(EventEmitter<DefaultEventMap> | _DOMEventTarget)[]

Наследуется от 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@138