Compartir a través de

Twin class

  • Referencia
Paquete:
azure-iot-device

Un dispositivo gemelo está documentando el estado de un dispositivo almacenado por una instancia de Azure IoT Hub y está disponible incluso si el dispositivo está sin conexión. Se construye alrededor de 3 secciones:

  • Etiquetas: pares clave-valor solo accesibles desde el lado del servicio
  • Propiedades deseadas: actualizadas por un servicio y recibidas por el dispositivo
  • Propiedades notificadas: actualizadas por el dispositivo y recibidas por el servicio.

Tenga en cuenta que, aunque es una posibilidad, las propiedades deseadas y notificadas no tienen que coincidir y que la lógica para sincronizar estas dos colecciones, si es necesario, se deja al usuario del SDK.

Para obtener más información, consulte Understanding Device Twins.

Extends

EventEmitter

Propiedades

desiredPath
errorEvent
properties

Diccionarios de propiedades deseados y notificados (respectivamente en properties.desired y properties.reported).
userRegisteredDesiredPropertiesListener

Propiedades heredadas

captureRejections

Valor: booleano

Cambie la opción de captureRejections predeterminada en todos los objetos EventEmitter nuevos.
captureRejectionSymbol

Valor: Symbol.for('nodejs.rejection')

Vea cómo escribir un rejection handlerpersonalizado.
defaultMaxListeners

De forma predeterminada, se puede registrar un máximo de 10 agentes de escucha para cualquier evento único. Este límite se puede cambiar para instancias de EventEmitter individuales mediante el método emitter.setMaxListeners(n). Para cambiar el valor predeterminado de todas las instancias deEventEmitter, se puede usar la propiedad events.defaultMaxListeners. Si este valor no es un número positivo, se produce un RangeError.

Tenga cuidado al establecer el events.defaultMaxListeners porque el cambio afecta a todas las instancias deEventEmitter, incluidas las creadas antes de realizar el cambio. Sin embargo, llamar a emitter.setMaxListeners(n) todavía tiene prioridad sobre events.defaultMaxListeners.

Esto no es un límite estricto. La instancia de EventEmitter permitirá agregar más agentes de escucha, pero generará una advertencia de seguimiento en stderr que indica que se ha detectado una posible pérdida de memoria de EventEmitter. Para cualquier EventEmitterúnico , los métodos emitter.getMaxListeners() y emitter.setMaxListeners() se pueden usar para evitar temporalmente esta advertencia:

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

La marca de línea de comandos --trace-warnings se puede usar para mostrar el seguimiento de la pila para estas advertencias.

La advertencia emitida se puede inspeccionar con process.on('warning') y tendrá las propiedades adicionales de emitter, typey count, haciendo referencia a la instancia del emisor de eventos, el nombre del evento y el número de agentes de escucha adjuntos, respectivamente. Su propiedad name se establece en 'MaxListenersExceededWarning'.
errorMonitor

Este símbolo se usará para instalar un agente de escucha solo para supervisar eventos 'error'. Se llama a los agentes de escucha instalados mediante este símbolo antes de llamar a los agentes de escucha normales 'error'.

La instalación de un agente de escucha mediante este símbolo no cambia el comportamiento una vez que se emite un evento 'error'. Por lo tanto, el proceso se bloqueará si no hay ningún agente de escucha normal 'error' instalado.

Métodos

get()
get(Callback<Twin>)

Obtiene todo el gemelo del servicio.

Métodos heredados

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

Escucha una vez el evento abort en el signalproporcionado.

Escuchar el evento abort en las señales de anulación no es seguro y puede provocar pérdidas de recursos, ya que otro tercero con la señal puede llamar a e.stopImmediatePropagation(). Desafortunadamente, Node.js no puede cambiar esto, ya que infringiría el estándar web. Además, la API original facilita la eliminación de agentes de escucha.

Esta API permite usar AbortSignalde forma segura en Node.js API mediante la resolución de estos dos problemas escuchando el evento de modo que stopImmediatePropagation no impide que se ejecute el agente de escucha.

Devuelve un descartable para que se pueda cancelar la suscripción de más fácilmente.

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)

Alias para emitter.on(eventName, listener).
emit<K>(string | symbol, AnyRest)

Llama sincrónicamente a cada uno de los agentes de escucha registrados para el evento denominado eventName, en el orden en que se registraron, pasando los argumentos proporcionados a cada uno.

Devuelve true si el evento tenía agentes de escucha, false de lo contrario.

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

Devuelve una matriz que enumera los eventos para los que el emisor ha registrado agentes de escucha. Los valores de la matriz son cadenas o 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)

Devuelve una copia de la matriz de agentes de escucha del evento denominado eventName.

Para EventEmitterse comporta exactamente igual que llamar a .listeners en el emisor.

Para EventTargetes la única manera de obtener los agentes de escucha de eventos para el destino del evento. Esto es útil para fines de depuración y diagnóstico.

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

Devuelve el valor máximo actual del agente de escucha para el EventEmitter que se establece mediante emitter.setMaxListeners(n) o los valores predeterminados en defaultMaxListeners.
getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Devuelve la cantidad máxima establecida actualmente de agentes de escucha.

Para EventEmitterse comporta exactamente igual que llamar a .getMaxListeners en el emisor.

Para EventTargetes la única manera de obtener el número máximo de agentes de escucha de eventos para el destino del evento. Si el número de controladores de eventos de un único objeto EventTarget supera el conjunto máximo, EventTarget imprimirá una advertencia.

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)

Método de clase que devuelve el número de agentes de escucha para el eventName especificado registrado en el emitterespecificado.

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)

Devuelve el número de agentes de escucha que escuchan el evento denominado eventName. Si se proporciona listener, devolverá cuántas veces se encuentra el agente de escucha en la lista de agentes de escucha del evento.
listeners<K>(string | symbol)

Devuelve una copia de la matriz de agentes de escucha del evento denominado 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)

Alias para 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

Devuelve un AsyncIterator que recorre en iteración eventos eventName. Se producirá si el EventEmitter emite 'error'. Quita todos los agentes de escucha al salir del bucle. La value devuelta por cada iteración es una matriz compuesta por los argumentos de evento emitidos.

Se puede usar un AbortSignal para cancelar la espera de eventos:

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

Use la opción close para especificar una matriz de nombres de eventos que finalizarán la iteración:

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)

Agrega la función listener al final de la matriz de agentes de escucha para el evento denominado eventName. No se realizan comprobaciones para ver si ya se ha agregado el listener. Varias llamadas que pasan la misma combinación de eventName y listener darán lugar a que se agregue el listener y se llame varias veces.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

De forma predeterminada, los agentes de escucha de eventos se invocan en el orden en que se agregan. El método emitter.prependListener() se puede usar como alternativa para agregar el agente de escucha de eventos al principio de la matriz de agentes de escucha.

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)

Crea un Promise que se cumple cuando el EventEmitter emite el evento dado o que se rechaza si el EventEmitter emite 'error' mientras espera. El Promise se resolverá con una matriz de todos los argumentos emitidos al evento determinado.

Este método es intencionadamente genérico y funciona con la plataforma web interfaz eventTarget, que no tiene semántica de eventos'error' especial y no escucha el evento '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);
}

El control especial del evento 'error' solo se usa cuando se usa events.once() para esperar a otro evento. Si events.once() se usa para esperar al evento "error' en sí mismo, se trata como cualquier otro tipo de evento sin control especial:

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

Se puede usar un AbortSignal para cancelar la espera del evento:

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)

Agrega una función de única para el evento denominado . La próxima vez que se desencadene eventName, se quita este agente de escucha y, a continuación, se invoca.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

De forma predeterminada, los agentes de escucha de eventos se invocan en el orden en que se agregan. El método emitter.prependOnceListener() se puede usar como alternativa para agregar el agente de escucha de eventos al principio de la matriz de agentes de escucha.

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)

Agrega la función listener al que comienza de la matriz de agentes de escucha para el evento denominado eventName. No se realizan comprobaciones para ver si ya se ha agregado el listener. Varias llamadas que pasan la misma combinación de eventName y listener darán lugar a que se agregue el listener y se llame varias veces.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.
prependOnceListener<K>(string | symbol, (args: any[]) => void)

Agrega una función de de única para el evento denominado al principio de la matriz de agentes de escucha. La próxima vez que se desencadene eventName, se quita este agente de escucha y, a continuación, se invoca.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.
rawListeners<K>(string | symbol)

Devuelve una copia de la matriz de agentes de escucha para el evento denominado eventName, incluidos los contenedores (como los creados por .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)

Quita todos los agentes de escucha o los del eventNameespecificado.

Es un procedimiento incorrecto quitar agentes de escucha agregados en otro lugar del código, especialmente cuando la instancia de EventEmitter se creó mediante algún otro componente o módulo (por ejemplo, sockets o flujos de archivos).

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.
removeListener<K>(string | symbol, (args: any[]) => void)

Quita el listener especificado de la matriz del agente de escucha para el evento denominado eventName.

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

removeListener() quitará, como máximo, una instancia de un agente de escucha de la matriz del agente de escucha. Si se ha agregado varias veces alguna escucha única a la matriz del agente de escucha para el eventNameespecificado, se debe llamar a removeListener() varias veces para quitar cada instancia.

Una vez emitido un evento, se llama a todos los agentes de escucha adjuntos en el momento de emitir en orden. Esto implica que cualquier removeListener() o removeAllListeners() llama después de emitir y antes de que el último agente de escucha finalice la ejecución no los quitará deemit() en curso. Los eventos posteriores se comportan según lo previsto.

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

Dado que los agentes de escucha se administran mediante una matriz interna, llamar a esto cambiará los índices de posición de cualquier agente de escucha registrado después de el agente de escucha que se va a quitar. Esto no afectará al orden en el que se llama a los agentes de escucha, pero significa que las copias de la matriz del agente de escucha tal y como devuelve el método emitter.listeners() deberán volver a crearse.

Cuando se ha agregado una sola función como controlador varias veces para un solo evento (como en el ejemplo siguiente), removeListener() quitará la instancia agregada más recientemente. En el ejemplo, se quita el agente de escucha 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');

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.
setMaxListeners(number)

De forma predeterminada, EventEmitters imprimirán una advertencia si se agregan más de 10 agentes de escucha para un evento determinado. Este es un valor predeterminado útil que ayuda a encontrar fugas de memoria. El método emitter.setMaxListeners() permite modificar el límite para esta instancia de EventEmitter específica. El valor se puede establecer en Infinity (o 0) para indicar un número ilimitado de agentes de escucha.

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.
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)

Detalles de las propiedades

desiredPath 

static desiredPath: string

Valor de propiedad

string

errorEvent 

static errorEvent: string

Valor de propiedad

string

properties

Diccionarios de propiedades deseados y notificados (respectivamente en properties.desired y properties.reported).

properties: TwinProperties

Valor de propiedad

TwinProperties

userRegisteredDesiredPropertiesListener 

userRegisteredDesiredPropertiesListener: boolean

Valor de propiedad

boolean

Detalles de las propiedades heredadas

captureRejections

Valor: booleano

Cambie la opción de captureRejections predeterminada en todos los objetos EventEmitter nuevos.

static captureRejections: boolean

Valor de propiedad

boolean

heredado de EventEmitter.captureRejections

captureRejectionSymbol

Valor: Symbol.for('nodejs.rejection')

Vea cómo escribir un rejection handlerpersonalizado.

static captureRejectionSymbol: typeof captureRejectionSymbol

Valor de propiedad

typeof captureRejectionSymbol

se hereda de EventEmitter.captureRejectionSymbol

defaultMaxListeners

De forma predeterminada, se puede registrar un máximo de 10 agentes de escucha para cualquier evento único. Este límite se puede cambiar para instancias de EventEmitter individuales mediante el método emitter.setMaxListeners(n). Para cambiar el valor predeterminado de todas las instancias deEventEmitter, se puede usar la propiedad events.defaultMaxListeners. Si este valor no es un número positivo, se produce un RangeError.

Tenga cuidado al establecer el events.defaultMaxListeners porque el cambio afecta a todas las instancias deEventEmitter, incluidas las creadas antes de realizar el cambio. Sin embargo, llamar a emitter.setMaxListeners(n) todavía tiene prioridad sobre events.defaultMaxListeners.

Esto no es un límite estricto. La instancia de EventEmitter permitirá agregar más agentes de escucha, pero generará una advertencia de seguimiento en stderr que indica que se ha detectado una posible pérdida de memoria de EventEmitter. Para cualquier EventEmitterúnico , los métodos emitter.getMaxListeners() y emitter.setMaxListeners() se pueden usar para evitar temporalmente esta advertencia:

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

La marca de línea de comandos --trace-warnings se puede usar para mostrar el seguimiento de la pila para estas advertencias.

La advertencia emitida se puede inspeccionar con process.on('warning') y tendrá las propiedades adicionales de emitter, typey count, haciendo referencia a la instancia del emisor de eventos, el nombre del evento y el número de agentes de escucha adjuntos, respectivamente. Su propiedad name se establece en 'MaxListenersExceededWarning'.

static defaultMaxListeners: number

Valor de propiedad

number

Heredado de EventEmitter.defaultMaxListeners

errorMonitor

Este símbolo se usará para instalar un agente de escucha solo para supervisar eventos 'error'. Se llama a los agentes de escucha instalados mediante este símbolo antes de llamar a los agentes de escucha normales 'error'.

La instalación de un agente de escucha mediante este símbolo no cambia el comportamiento una vez que se emite un evento 'error'. Por lo tanto, el proceso se bloqueará si no hay ningún agente de escucha normal 'error' instalado.

static errorMonitor: typeof errorMonitor

Valor de propiedad

typeof errorMonitor

Heredado de EventEmitter.errorMonitor

Detalles del método

get() 

function get(): Promise<Twin>

Devoluciones

Promise<Twin>

get(Callback<Twin>)

Obtiene todo el gemelo del servicio.

function get(callback?: Callback<Twin>)

Parámetros

callback

Callback<Twin>

función opcional que se llamará de nuevo con el gemelo o un error si el transporte no puede recuperar el gemelo.

Detalles de los métodos heredados

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

Escucha una vez el evento abort en el signalproporcionado.

Escuchar el evento abort en las señales de anulación no es seguro y puede provocar pérdidas de recursos, ya que otro tercero con la señal puede llamar a e.stopImmediatePropagation(). Desafortunadamente, Node.js no puede cambiar esto, ya que infringiría el estándar web. Además, la API original facilita la eliminación de agentes de escucha.

Esta API permite usar AbortSignalde forma segura en Node.js API mediante la resolución de estos dos problemas escuchando el evento de modo que stopImmediatePropagation no impide que se ejecute el agente de escucha.

Devuelve un descartable para que se pueda cancelar la suscripción de más fácilmente.

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

Parámetros

signal

AbortSignal

resource

(event: Event) => void

Devoluciones

Disposable

Descartable que quita el agente de escucha de abort.

Heredado de EventEmitter.addAbortListener

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

Alias para emitter.on(eventName, listener).

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

Parámetros

eventName

string | symbol

listener

(args: any[]) => void

Devoluciones

Twin

Heredado de EventEmitter.addListener

emit<K>(string | symbol, AnyRest)

Llama sincrónicamente a cada uno de los agentes de escucha registrados para el evento denominado eventName, en el orden en que se registraron, pasando los argumentos proporcionados a cada uno.

Devuelve true si el evento tenía agentes de escucha, false de lo contrario.

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

Parámetros

eventName

string | symbol

args

AnyRest

Devoluciones

boolean

Heredado de EventEmitter.emit

eventNames()

Devuelve una matriz que enumera los eventos para los que el emisor ha registrado agentes de escucha. Los valores de la matriz son cadenas o 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)[]

Devoluciones

(string | symbol)[]

Heredado de EventEmitter.eventNames

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

Devuelve una copia de la matriz de agentes de escucha del evento denominado eventName.

Para EventEmitterse comporta exactamente igual que llamar a .listeners en el emisor.

Para EventTargetes la única manera de obtener los agentes de escucha de eventos para el destino del evento. Esto es útil para fines de depuración y diagnóstico.

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

Parámetros

emitter

EventEmitter<DefaultEventMap> | EventTarget

name

string | symbol

Devoluciones

Function[]

Heredado de EventEmitter.getEventListeners

getMaxListeners()

Devuelve el valor máximo actual del agente de escucha para el EventEmitter que se establece mediante emitter.setMaxListeners(n) o los valores predeterminados en defaultMaxListeners.

function getMaxListeners(): number

Devoluciones

number

se hereda de EventEmitter.getMaxListeners

getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Devuelve la cantidad máxima establecida actualmente de agentes de escucha.

Para EventEmitterse comporta exactamente igual que llamar a .getMaxListeners en el emisor.

Para EventTargetes la única manera de obtener el número máximo de agentes de escucha de eventos para el destino del evento. Si el número de controladores de eventos de un único objeto EventTarget supera el conjunto máximo, EventTarget imprimirá una advertencia.

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

Parámetros

emitter

EventEmitter<DefaultEventMap> | EventTarget

Devoluciones

number

se hereda de EventEmitter.getMaxListeners

listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

Advertencia

Esta API ya está en desuso.

Since v3.2.0 - Use listenerCount instead.

Método de clase que devuelve el número de agentes de escucha para el eventName especificado registrado en el emitterespecificado.

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

Parámetros

emitter

EventEmitter<DefaultEventMap>

Emisor al que se va a consultar

eventName

string | symbol

Nombre del evento

Devoluciones

number

Heredado de EventEmitter.listenerCount

listenerCount<K>(string | symbol, Function)

Devuelve el número de agentes de escucha que escuchan el evento denominado eventName. Si se proporciona listener, devolverá cuántas veces se encuentra el agente de escucha en la lista de agentes de escucha del evento.

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

Parámetros

eventName

string | symbol

Nombre del evento que se está escuchando

listener

Function

Función del controlador de eventos

Devoluciones

number

Heredado de EventEmitter.listenerCount

listeners<K>(string | symbol)

Devuelve una copia de la matriz de agentes de escucha del evento denominado 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[]

Parámetros

eventName

string | symbol

Devoluciones

Function[]

Heredado de EventEmitter.listeners

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

Alias para emitter.removeListener().

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

Parámetros

eventName

string | symbol

listener

(args: any[]) => void

Devoluciones

Twin

Heredado de 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

Devuelve un AsyncIterator que recorre en iteración eventos eventName. Se producirá si el EventEmitter emite 'error'. Quita todos los agentes de escucha al salir del bucle. La value devuelta por cada iteración es una matriz compuesta por los argumentos de evento emitidos.

Se puede usar un AbortSignal para cancelar la espera de eventos:

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

Use la opción close para especificar una matriz de nombres de eventos que finalizarán la iteración:

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>

Parámetros

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterIteratorOptions

Devoluciones

AsyncIterator<any[], any, any>

Un AsyncIterator que recorre en iteración los eventos de eventName emitidos por el emitter

heredado de EventEmitter.on

on(EventTarget, string, StaticEventEmitterIteratorOptions) 

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

Parámetros

emitter

EventTarget

eventName

string

options

StaticEventEmitterIteratorOptions

Devoluciones

AsyncIterator<any[], any, any>

heredado de EventEmitter.on

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

Agrega la función listener al final de la matriz de agentes de escucha para el evento denominado eventName. No se realizan comprobaciones para ver si ya se ha agregado el listener. Varias llamadas que pasan la misma combinación de eventName y listener darán lugar a que se agregue el listener y se llame varias veces.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

De forma predeterminada, los agentes de escucha de eventos se invocan en el orden en que se agregan. El método emitter.prependListener() se puede usar como alternativa para agregar el agente de escucha de eventos al principio de la matriz de agentes de escucha.

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

Parámetros

eventName

string | symbol

Nombre del evento.

listener

(args: any[]) => void

Función de devolución de llamada

Devoluciones

Twin

heredado de EventEmitter.on

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

Crea un Promise que se cumple cuando el EventEmitter emite el evento dado o que se rechaza si el EventEmitter emite 'error' mientras espera. El Promise se resolverá con una matriz de todos los argumentos emitidos al evento determinado.

Este método es intencionadamente genérico y funciona con la plataforma web interfaz eventTarget, que no tiene semántica de eventos'error' especial y no escucha el evento '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);
}

El control especial del evento 'error' solo se usa cuando se usa events.once() para esperar a otro evento. Si events.once() se usa para esperar al evento "error' en sí mismo, se trata como cualquier otro tipo de evento sin control especial:

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

Se puede usar un AbortSignal para cancelar la espera del evento:

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

Parámetros

emitter

EventEmitter<DefaultEventMap>

eventName

string | symbol

options

StaticEventEmitterOptions

Devoluciones

Promise<any[]>

heredado de EventEmitter.once

once(EventTarget, string, StaticEventEmitterOptions) 

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

Parámetros

emitter

EventTarget

eventName

string

options

StaticEventEmitterOptions

Devoluciones

Promise<any[]>

heredado de EventEmitter.once

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

Agrega una función de única para el evento denominado . La próxima vez que se desencadene eventName, se quita este agente de escucha y, a continuación, se invoca.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

De forma predeterminada, los agentes de escucha de eventos se invocan en el orden en que se agregan. El método emitter.prependOnceListener() se puede usar como alternativa para agregar el agente de escucha de eventos al principio de la matriz de agentes de escucha.

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

Parámetros

eventName

string | symbol

Nombre del evento.

listener

(args: any[]) => void

Función de devolución de llamada

Devoluciones

Twin

heredado de EventEmitter.once

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

Agrega la función listener al que comienza de la matriz de agentes de escucha para el evento denominado eventName. No se realizan comprobaciones para ver si ya se ha agregado el listener. Varias llamadas que pasan la misma combinación de eventName y listener darán lugar a que se agregue el listener y se llame varias veces.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

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

Parámetros

eventName

string | symbol

Nombre del evento.

listener

(args: any[]) => void

Función de devolución de llamada

Devoluciones

Twin

heredado de EventEmitter.prependListener

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

Agrega una función de de única para el evento denominado al principio de la matriz de agentes de escucha. La próxima vez que se desencadene eventName, se quita este agente de escucha y, a continuación, se invoca.

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

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

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

Parámetros

eventName

string | symbol

Nombre del evento.

listener

(args: any[]) => void

Función de devolución de llamada

Devoluciones

Twin

heredado de EventEmitter.prependOnceListener

rawListeners<K>(string | symbol)

Devuelve una copia de la matriz de agentes de escucha para el evento denominado eventName, incluidos los contenedores (como los creados por .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[]

Parámetros

eventName

string | symbol

Devoluciones

Function[]

heredado de EventEmitter.rawListeners

removeAllListeners(string | symbol)

Quita todos los agentes de escucha o los del eventNameespecificado.

Es un procedimiento incorrecto quitar agentes de escucha agregados en otro lugar del código, especialmente cuando la instancia de EventEmitter se creó mediante algún otro componente o módulo (por ejemplo, sockets o flujos de archivos).

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

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

Parámetros

eventName

string | symbol

Devoluciones

Twin

Heredado de EventEmitter.removeAllListeners

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

Quita el listener especificado de la matriz del agente de escucha para el evento denominado eventName.

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

removeListener() quitará, como máximo, una instancia de un agente de escucha de la matriz del agente de escucha. Si se ha agregado varias veces alguna escucha única a la matriz del agente de escucha para el eventNameespecificado, se debe llamar a removeListener() varias veces para quitar cada instancia.

Una vez emitido un evento, se llama a todos los agentes de escucha adjuntos en el momento de emitir en orden. Esto implica que cualquier removeListener() o removeAllListeners() llama después de emitir y antes de que el último agente de escucha finalice la ejecución no los quitará deemit() en curso. Los eventos posteriores se comportan según lo previsto.

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

Dado que los agentes de escucha se administran mediante una matriz interna, llamar a esto cambiará los índices de posición de cualquier agente de escucha registrado después de el agente de escucha que se va a quitar. Esto no afectará al orden en el que se llama a los agentes de escucha, pero significa que las copias de la matriz del agente de escucha tal y como devuelve el método emitter.listeners() deberán volver a crearse.

Cuando se ha agregado una sola función como controlador varias veces para un solo evento (como en el ejemplo siguiente), removeListener() quitará la instancia agregada más recientemente. En el ejemplo, se quita el agente de escucha 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');

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

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

Parámetros

eventName

string | symbol

listener

(args: any[]) => void

Devoluciones

Twin

Heredado de EventEmitter.removeListener

setMaxListeners(number)

De forma predeterminada, EventEmitters imprimirán una advertencia si se agregan más de 10 agentes de escucha para un evento determinado. Este es un valor predeterminado útil que ayuda a encontrar fugas de memoria. El método emitter.setMaxListeners() permite modificar el límite para esta instancia de EventEmitter específica. El valor se puede establecer en Infinity (o 0) para indicar un número ilimitado de agentes de escucha.

Devuelve una referencia al EventEmitter, para que las llamadas se puedan encadenar.

function setMaxListeners(n: number): Twin

Parámetros

n

number

Devoluciones

Twin

Heredado de 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)[])

Parámetros

n

number

Número no negativo. Número máximo de agentes de escucha por evento EventTarget.

eventTargets

(EventEmitter<DefaultEventMap> | EventTarget)[]

Cero o más instancias de {EventTarget} o {EventEmitter}. Si no se especifica ninguno, n se establece como máximo predeterminado para todos los objetos {EventTarget} y {EventEmitter} recién creados.

Heredado de EventEmitter.setMaxListeners

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

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

Parámetros

error

Error

event

string | symbol

args

AnyRest

heredado de EventEmitter.__@captureRejectionSymbol@141