Partilhar via

Twin class

  • Referência
Pacote:
azure-iot-device

Um Gêmeo de Dispositivo é um documento que descreve o estado de um dispositivo armazenado por um hub IoT do Azure e está disponível mesmo se o dispositivo estiver offline. É construído em torno de 3 seções:

  • Tags: pares chave/valor acessíveis apenas do lado do serviço
  • Propriedades desejadas: atualizadas por um serviço e recebidas pelo dispositivo
  • Propriedades relatadas: atualizadas pelo dispositivo e recebidas pelo serviço.

Observe que, embora seja uma possibilidade, as propriedades desejadas e relatadas não precisam corresponder e que a lógica para sincronizar essas duas coleções, se necessário, é deixada para o usuário do SDK.

Para obter mais informações, consulte Noções básicas sobre gêmeos de dispositivo.

Extends

EventEmitter

Propriedades

desiredPath
errorEvent
properties

Os dicionários de propriedades desejadas e relatadas (respectivamente em properties.desired e properties.reported).
userRegisteredDesiredPropertiesListener

Propriedades Herdadas

captureRejections

Valor: booleano

Altere a opção captureRejections padrão em todos os novos objetos EventEmitter.
captureRejectionSymbol

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

Veja como escrever um rejection handlerpersonalizado.
defaultMaxListeners

Por padrão, um máximo de 10 ouvintes podem ser registrados para qualquer evento. Esse limite pode ser alterado para instâncias EventEmitter individuais usando o método emitter.setMaxListeners(n). Para alterar o padrão para todas as instânciasEventEmitter, a propriedade events.defaultMaxListeners pode ser usada. Se esse valor não for um número positivo, uma RangeError será lançada.

Tenha cuidado ao definir o events.defaultMaxListeners porque a alteração afeta todas as instânciasEventEmitter, incluindo aquelas criadas antes de a alteração ser feita. No entanto, chamar emitter.setMaxListeners(n) ainda tem precedência sobre events.defaultMaxListeners.

Este não é um limite rígido. A instância EventEmitter permitirá que mais ouvintes sejam adicionados, mas enviará um aviso de rastreamento para stderr indicando que um "possível vazamento de memória EventEmitter" foi detetado. Para qualquer EventEmitter, os métodos emitter.getMaxListeners() e emitter.setMaxListeners() podem ser usados para evitar temporariamente este aviso:

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

O --trace-warnings sinalizador de linha de comando pode ser usado para exibir o rastreamento de pilha para esses avisos.

O aviso emitido pode ser inspecionado com process.on('warning') e terá as propriedades adicionais emitter, typee count, referentes à instância do emissor do evento, ao nome do evento e ao número de ouvintes anexados, respectivamente. Sua propriedade name está definida como 'MaxListenersExceededWarning'.
errorMonitor

Este símbolo deve ser utilizado para instalar um ouvinte apenas para monitorizar 'error' eventos. Os ouvintes instalados usando esse símbolo são chamados antes que os ouvintes 'error' regulares sejam chamados.

A instalação de um ouvinte usando esse símbolo não altera o comportamento quando um evento 'error' é emitido. Portanto, o processo ainda falhará se nenhum ouvinte de 'error' regular estiver instalado.

Métodos

get()
get(Callback<Twin>)

Obtém todo o gêmeo do serviço.

Métodos Herdados

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

Ouve uma vez o evento abort no signalfornecido.

Ouvir o evento abort em sinais de abortamento não é seguro e pode levar a vazamentos de recursos, uma vez que outro terceiro com o sinal pode ligar para e.stopImmediatePropagation(). Infelizmente, Node.js não pode mudar isso, pois violaria o padrão da web. Além disso, a API original facilita o esquecimento da remoção de ouvintes.

Essa API permite o uso seguro de AbortSignals em APIs Node.js, resolvendo esses dois problemas ouvindo o evento de modo que stopImmediatePropagation não impeça o ouvinte de executar.

Devolve um descartável para que possa ser retirado mais facilmente.

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)

Chama de forma síncrona cada um dos ouvintes registrados para o evento chamado eventName, na ordem em que foram registrados, passando os argumentos fornecidos para cada um.

Retorna true se o evento teve ouvintes false caso contrário.

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

Retorna uma matriz listando os eventos para os quais o emissor registrou ouvintes. Os valores na matriz são strings ou 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)

Retorna uma cópia da matriz de ouvintes para o evento chamado eventName.

Para EventEmitters, isto comporta-se exatamente da mesma forma que chamar .listeners ao emissor.

Por EventTargets, essa é a única maneira de obter os ouvintes do evento para o público-alvo. Isso é útil para fins de depuração e 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()

Retorna o valor máximo de ouvinte atual para o EventEmitter que é definido por emitter.setMaxListeners(n) ou padrão como defaultMaxListeners.
getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Retorna a quantidade máxima de ouvintes definida no momento.

Para EventEmitters, isto comporta-se exatamente da mesma forma que chamar .getMaxListeners ao emissor.

Por EventTargets, essa é a única maneira de obter o máximo de ouvintes de eventos para o destino do evento. Se o número de manipuladores de eventos em um único EventTarget exceder o conjunto máximo, o EventTarget imprimirá um aviso.

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)

Um método de classe que retorna o número de ouvintes para o determinado eventName registrado no emitterdeterminado.

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)

Retorna o número de ouvintes ouvindo o evento chamado eventName. Se listener for fornecido, ele retornará quantas vezes o ouvinte é encontrado na lista dos ouvintes do evento.
listeners<K>(string | symbol)

Retorna uma cópia da matriz de ouvintes para o evento chamado 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

Retorna um AsyncIterator que itera eventName eventos. Ele vai jogar se o EventEmitter emite 'error'. Ele remove todos os ouvintes ao sair do loop. O value retornado por cada iteração é uma matriz composta pelos argumentos de evento emitidos.

Um AbortSignal pode ser usado para cancelar a espera em 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 a opção close para especificar uma matriz de nomes de eventos que encerrará a iteração:

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)

Adiciona a função listener ao final da matriz de ouvintes do evento chamado eventName. Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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)

Cria um Promise que é cumprido quando o EventEmitter emite o evento dado ou que é rejeitado se o EventEmitter emite 'error' enquanto espera. O Promise será resolvido com uma matriz de todos os argumentos emitidos para o evento dado.

Este método é intencionalmente genérico e funciona com a plataforma web interface de EventTarget, que não tem semântica de evento'error' especial e não ouve o 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);
}

O tratamento especial do evento 'error' só é usado quando events.once() é usado para aguardar outro evento. Se events.once() é usado para esperar pelo evento 'error' em si, então ele é tratado como qualquer outro tipo de evento sem manipulação 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

Um AbortSignal pode ser usado para cancelar a espera pelo 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)

Adiciona uma funçãolistener única para o evento chamado eventName. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependOnceListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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)

Adiciona a função ao inicial da matriz listeners para o evento chamado . Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.
prependOnceListener<K>(string | symbol, (args: any[]) => void)

Adiciona uma função de única para o evento chamado ao inicial da matriz de ouvintes. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.
rawListeners<K>(string | symbol)

Retorna uma cópia da matriz de ouvintes para o evento chamado eventName, incluindo quaisquer wrappers (como os criados 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)

Remove todos os ouvintes ou os do eventNameespecificado.

É uma má prática remover ouvintes adicionados em outro lugar no código, particularmente quando a instância EventEmitter foi criada por algum outro componente ou módulo (por exemplo, soquetes ou fluxos de arquivos).

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.
removeListener<K>(string | symbol, (args: any[]) => void)

Remove o listener especificado da matriz de ouvinte do evento chamado eventName.

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

removeListener() removerá, no máximo, uma instância de um ouvinte da matriz do ouvinte. Se qualquer ouvinte tiver sido adicionado várias vezes à matriz de ouvinte para o eventNameespecificado, removeListener() deverá ser chamado várias vezes para remover cada instância.

Uma vez que um evento é emitido, todos os ouvintes ligados a ele no momento da emissão são chamados em ordem. Isso implica que qualquer removeListener() ou removeAllListeners() chamadas após emissão e antes de o último ouvinte terminar a execução não as removerá deemit() em andamento. Os acontecimentos subsequentes comportam-se como esperado.

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

Como os ouvintes são gerenciados usando uma matriz interna, chamar isso alterará os índices de posição de qualquer ouvinte registrado depois de o ouvinte ser removido. Isso não afetará a ordem na qual os ouvintes são chamados, mas significa que todas as cópias da matriz de ouvintes retornadas pelo método emitter.listeners() precisarão ser recriadas.

Quando uma única função tiver sido adicionada como manipulador várias vezes para um único evento (como no exemplo abaixo), removeListener() removerá a instância adicionada mais recentemente. No exemplo, o ouvinte once('ping') é removido:

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.
setMaxListeners(number)

Por padrãoEventEmitters imprimirá um aviso se mais de 10 ouvintes forem adicionados para um evento específico. Este é um padrão útil que ajuda a encontrar vazamentos de memória. O método emitter.setMaxListeners() permite que o limite seja modificado para esta instância EventEmitter específica. O valor pode ser definido como Infinity (ou 0) para indicar um número ilimitado de ouvintes.

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.
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)

Detalhes de Propriedade

desiredPath 

static desiredPath: string

Valor de Propriedade

string

errorEvent 

static errorEvent: string

Valor de Propriedade

string

properties

Os dicionários de propriedades desejadas e relatadas (respectivamente em properties.desired e properties.reported).

properties: TwinProperties

Valor de Propriedade

TwinProperties

userRegisteredDesiredPropertiesListener 

userRegisteredDesiredPropertiesListener: boolean

Valor de Propriedade

boolean

Detalhes da Propriedade Herdada

captureRejections

Valor: booleano

Altere a opção captureRejections padrão em todos os novos objetos EventEmitter.

static captureRejections: boolean

Valor de Propriedade

boolean

herdado de EventEmitter.captureRejections

captureRejectionSymbol

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

Veja como escrever um rejection handlerpersonalizado.

static captureRejectionSymbol: typeof captureRejectionSymbol

Valor de Propriedade

typeof captureRejectionSymbol

herdado de EventEmitter.captureRejectionSymbol

defaultMaxListeners

Por padrão, um máximo de 10 ouvintes podem ser registrados para qualquer evento. Esse limite pode ser alterado para instâncias EventEmitter individuais usando o método emitter.setMaxListeners(n). Para alterar o padrão para todas as instânciasEventEmitter, a propriedade events.defaultMaxListeners pode ser usada. Se esse valor não for um número positivo, uma RangeError será lançada.

Tenha cuidado ao definir o events.defaultMaxListeners porque a alteração afeta todas as instânciasEventEmitter, incluindo aquelas criadas antes de a alteração ser feita. No entanto, chamar emitter.setMaxListeners(n) ainda tem precedência sobre events.defaultMaxListeners.

Este não é um limite rígido. A instância EventEmitter permitirá que mais ouvintes sejam adicionados, mas enviará um aviso de rastreamento para stderr indicando que um "possível vazamento de memória EventEmitter" foi detetado. Para qualquer EventEmitter, os métodos emitter.getMaxListeners() e emitter.setMaxListeners() podem ser usados para evitar temporariamente este aviso:

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

O --trace-warnings sinalizador de linha de comando pode ser usado para exibir o rastreamento de pilha para esses avisos.

O aviso emitido pode ser inspecionado com process.on('warning') e terá as propriedades adicionais emitter, typee count, referentes à instância do emissor do evento, ao nome do evento e ao número de ouvintes anexados, respectivamente. Sua propriedade name está definida como 'MaxListenersExceededWarning'.

static defaultMaxListeners: number

Valor de Propriedade

number

herdado de EventEmitter.defaultMaxListeners

errorMonitor

Este símbolo deve ser utilizado para instalar um ouvinte apenas para monitorizar 'error' eventos. Os ouvintes instalados usando esse símbolo são chamados antes que os ouvintes 'error' regulares sejam chamados.

A instalação de um ouvinte usando esse símbolo não altera o comportamento quando um evento 'error' é emitido. Portanto, o processo ainda falhará se nenhum ouvinte de 'error' regular estiver instalado.

static errorMonitor: typeof errorMonitor

Valor de Propriedade

typeof errorMonitor

herdado de EventEmitter.errorMonitor

Detalhes de Método

get() 

function get(): Promise<Twin>

Devoluções

Promise<Twin>

get(Callback<Twin>)

Obtém todo o gêmeo do serviço.

function get(callback?: Callback<Twin>)

Parâmetros

callback

Callback<Twin>

função opcional que deve ser chamada de volta com o gémeo ou um erro se o transporte não conseguir recuperar o gémeo.

Detalhes do Método Herdado

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

Ouve uma vez o evento abort no signalfornecido.

Ouvir o evento abort em sinais de abortamento não é seguro e pode levar a vazamentos de recursos, uma vez que outro terceiro com o sinal pode ligar para e.stopImmediatePropagation(). Infelizmente, Node.js não pode mudar isso, pois violaria o padrão da web. Além disso, a API original facilita o esquecimento da remoção de ouvintes.

Essa API permite o uso seguro de AbortSignals em APIs Node.js, resolvendo esses dois problemas ouvindo o evento de modo que stopImmediatePropagation não impeça o ouvinte de executar.

Devolve um descartável para que possa ser retirado mais facilmente.

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

Devoluções

Disposable

Descartável que remove o abort ouvinte.

herdado 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

Devoluções

Twin

herdado de EventEmitter.addListener

emit<K>(string | symbol, AnyRest)

Chama de forma síncrona cada um dos ouvintes registrados para o evento chamado eventName, na ordem em que foram registrados, passando os argumentos fornecidos para cada um.

Retorna true se o evento teve ouvintes false caso contrário.

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

Devoluções

boolean

herdado de EventEmitter.emit

eventNames()

Retorna uma matriz listando os eventos para os quais o emissor registrou ouvintes. Os valores na matriz são strings ou 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)[]

Devoluções

(string | symbol)[]

herdado de EventEmitter.eventNames

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

Retorna uma cópia da matriz de ouvintes para o evento chamado eventName.

Para EventEmitters, isto comporta-se exatamente da mesma forma que chamar .listeners ao emissor.

Por EventTargets, essa é a única maneira de obter os ouvintes do evento para o público-alvo. Isso é útil para fins de depuração e 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

Devoluções

Function[]

herdado de EventEmitter.getEventListeners

getMaxListeners()

Retorna o valor máximo de ouvinte atual para o EventEmitter que é definido por emitter.setMaxListeners(n) ou padrão como defaultMaxListeners.

function getMaxListeners(): number

Devoluções

number

herdado de EventEmitter.getMaxListeners

getMaxListeners(EventEmitter<DefaultEventMap> | EventTarget)

Retorna a quantidade máxima de ouvintes definida no momento.

Para EventEmitters, isto comporta-se exatamente da mesma forma que chamar .getMaxListeners ao emissor.

Por EventTargets, essa é a única maneira de obter o máximo de ouvintes de eventos para o destino do evento. Se o número de manipuladores de eventos em um único EventTarget exceder o conjunto máximo, o EventTarget imprimirá um aviso.

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

Devoluções

number

herdado de EventEmitter.getMaxListeners

listenerCount(EventEmitter<DefaultEventMap>, string | symbol)

Aviso

Esta API foi preterida.

Since v3.2.0 - Use listenerCount instead.

Um método de classe que retorna o número de ouvintes para o determinado eventName registrado no emitterdeterminado.

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>

O emissor a consultar

eventName

string | symbol

O nome do evento

Devoluções

number

herdado de EventEmitter.listenerCount

listenerCount<K>(string | symbol, Function)

Retorna o número de ouvintes ouvindo o evento chamado eventName. Se listener for fornecido, ele retornará quantas vezes o ouvinte é encontrado na lista dos ouvintes do evento.

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

Parâmetros

eventName

string | symbol

O nome do evento que está sendo escutado

listener

Function

A função de manipulador de eventos

Devoluções

number

herdado de EventEmitter.listenerCount

listeners<K>(string | symbol)

Retorna uma cópia da matriz de ouvintes para o evento chamado 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

Devoluções

Function[]

herdado 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

Devoluções

Twin

herdado 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

Retorna um AsyncIterator que itera eventName eventos. Ele vai jogar se o EventEmitter emite 'error'. Ele remove todos os ouvintes ao sair do loop. O value retornado por cada iteração é uma matriz composta pelos argumentos de evento emitidos.

Um AbortSignal pode ser usado para cancelar a espera em 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 a opção close para especificar uma matriz de nomes de eventos que encerrará a iteração:

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

Devoluções

AsyncIterator<any[], any, any>

Um AsyncIterator que itera eventName eventos emitidos pelo emitter

herdado 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

Devoluções

AsyncIterator<any[], any, any>

herdado de EventEmitter.on

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

Adiciona a função listener ao final da matriz de ouvintes do evento chamado eventName. Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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

O nome do evento.

listener

(args: any[]) => void

A função de retorno de chamada

Devoluções

Twin

herdado de EventEmitter.on

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

Cria um Promise que é cumprido quando o EventEmitter emite o evento dado ou que é rejeitado se o EventEmitter emite 'error' enquanto espera. O Promise será resolvido com uma matriz de todos os argumentos emitidos para o evento dado.

Este método é intencionalmente genérico e funciona com a plataforma web interface de EventTarget, que não tem semântica de evento'error' especial e não ouve o 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);
}

O tratamento especial do evento 'error' só é usado quando events.once() é usado para aguardar outro evento. Se events.once() é usado para esperar pelo evento 'error' em si, então ele é tratado como qualquer outro tipo de evento sem manipulação 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

Um AbortSignal pode ser usado para cancelar a espera pelo 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

Devoluções

Promise<any[]>

herdado 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

Devoluções

Promise<any[]>

herdado de EventEmitter.once

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

Adiciona uma funçãolistener única para o evento chamado eventName. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

Por padrão, os ouvintes de eventos são invocados na ordem em que são adicionados. O método emitter.prependOnceListener() pode ser usado como uma alternativa para adicionar o ouvinte de eventos ao início da matriz de ouvintes.

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

O nome do evento.

listener

(args: any[]) => void

A função de retorno de chamada

Devoluções

Twin

herdado de EventEmitter.once

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

Adiciona a função ao inicial da matriz listeners para o evento chamado . Nenhuma verificação é feita para ver se o listener já foi adicionado. Várias chamadas que passam a mesma combinação de eventName e listener resultarão no listener sendo adicionado e chamado várias vezes.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName

string | symbol

O nome do evento.

listener

(args: any[]) => void

A função de retorno de chamada

Devoluções

Twin

herdado de EventEmitter.prependListener

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

Adiciona uma função de única para o evento chamado ao inicial da matriz de ouvintes. Na próxima vez que eventName for acionado, esse ouvinte será removido e, em seguida, invocado.

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName

string | symbol

O nome do evento.

listener

(args: any[]) => void

A função de retorno de chamada

Devoluções

Twin

herdado de EventEmitter.prependOnceListener

rawListeners<K>(string | symbol)

Retorna uma cópia da matriz de ouvintes para o evento chamado eventName, incluindo quaisquer wrappers (como os criados 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

Devoluções

Function[]

herdado de EventEmitter.rawListeners

removeAllListeners(string | symbol)

Remove todos os ouvintes ou os do eventNameespecificado.

É uma má prática remover ouvintes adicionados em outro lugar no código, particularmente quando a instância EventEmitter foi criada por algum outro componente ou módulo (por exemplo, soquetes ou fluxos de arquivos).

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName

string | symbol

Devoluções

Twin

herdado de EventEmitter.removeAllListeners

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

Remove o listener especificado da matriz de ouvinte do evento chamado eventName.

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

removeListener() removerá, no máximo, uma instância de um ouvinte da matriz do ouvinte. Se qualquer ouvinte tiver sido adicionado várias vezes à matriz de ouvinte para o eventNameespecificado, removeListener() deverá ser chamado várias vezes para remover cada instância.

Uma vez que um evento é emitido, todos os ouvintes ligados a ele no momento da emissão são chamados em ordem. Isso implica que qualquer removeListener() ou removeAllListeners() chamadas após emissão e antes de o último ouvinte terminar a execução não as removerá deemit() em andamento. Os acontecimentos subsequentes comportam-se como esperado.

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

Como os ouvintes são gerenciados usando uma matriz interna, chamar isso alterará os índices de posição de qualquer ouvinte registrado depois de o ouvinte ser removido. Isso não afetará a ordem na qual os ouvintes são chamados, mas significa que todas as cópias da matriz de ouvintes retornadas pelo método emitter.listeners() precisarão ser recriadas.

Quando uma única função tiver sido adicionada como manipulador várias vezes para um único evento (como no exemplo abaixo), removeListener() removerá a instância adicionada mais recentemente. No exemplo, o ouvinte once('ping') é removido:

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

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

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

Parâmetros

eventName

string | symbol

listener

(args: any[]) => void

Devoluções

Twin

herdado de EventEmitter.removeListener

setMaxListeners(number)

Por padrãoEventEmitters imprimirá um aviso se mais de 10 ouvintes forem adicionados para um evento específico. Este é um padrão útil que ajuda a encontrar vazamentos de memória. O método emitter.setMaxListeners() permite que o limite seja modificado para esta instância EventEmitter específica. O valor pode ser definido como Infinity (ou 0) para indicar um número ilimitado de ouvintes.

Retorna uma referência ao EventEmitter, para que as chamadas possam ser encadeadas.

function setMaxListeners(n: number): Twin

Parâmetros

n

number

Devoluções

Twin

herdado 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

Um número não negativo. O número máximo de ouvintes por EventTarget evento.

eventTargets

(EventEmitter<DefaultEventMap> | EventTarget)[]

Zero ou mais instâncias {EventTarget} ou {EventEmitter}. Se nenhum for especificado, n será definido como o máximo padrão para todos os objetos {EventTarget} e {EventEmitter} recém-criados.

herdado 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

herdada de EventEmitter.__@captureRejectionSymbol@141