node:events

O módulo node:events no Azion Runtime: a classe EventEmitter, as APIs suportadas e exemplos de listeners, handlers assíncronos e subclasses.

Última atualização

Ver como Markdown Configurar agente

O módulo node:events fornece EventEmitter, a classe do Node.js para código orientado a eventos. Um event emitter é um objeto que emite eventos nomeados, e os listeners registrados nele são executados cada vez que ele emite um desses nomes. No Azion Runtime, as functions o usam para desacoplar a lógica: uma parte do código emite um evento e listeners dedicados reagem a ele.

Exemplos

Cada exemplo é uma function completa que importa EventEmitter de node:events. A resposta abaixo de cada exemplo é a que uma function com deploy feito retorna.

Emissão básica de eventos

Esta function registra um listener para um evento e depois emite esse evento com três argumentos:

JavaScript
01/**
02 * An example of using the Node.js `events` module in Azion Functions.
03 * Support:
04 * - Partial support
05 * - Extended by library `events`
06 * @example
07 * // Build and run with the Azion CLI:
08 * azion build
09 * azion dev
10 */
11import { EventEmitter } from "node:events";
12
13/**
14 * Emit an event and listen to it.
15 * @param {*} event
16 * @returns {Response} Response
17 */
18const main = async (event) => {
19 const emitter = new EventEmitter();
20
21 emitter.on("hello-event", (...args) => {
22 console.log("an event occurred!", ...args);
23 });
24
25 emitter.emit("hello-event", 1, 2, 3);
26 return new Response("Event emitted", { status: 200 });
27};
28
29export default main;

O listener registra an event occurred! 1 2 3 no log e a function responde com:

Event emitted

Eventos do ciclo de vida da requisição

Esta function emite um evento por etapa de processamento da requisição e registra o que cada listener recebeu:

JavaScript
01import { EventEmitter } from "node:events";
02
03const main = async (event) => {
04 const requestEmitter = new EventEmitter();
05 const results = [];
06
07 // Get request info with optional chaining for safety
08 const requestUrl = event.request?.url || "https://default.example.com";
09 const requestHeaders = event.request?.headers || {};
10
11 // Listen for request start
12 requestEmitter.on("start", (url) => {
13 console.log(`Processing request: ${url}`);
14 results.push(`Started: ${url}`);
15 });
16
17 // Listen for validation events
18 requestEmitter.on("validate", (data) => {
19 if (data.headers) {
20 console.log("Headers validated");
21 results.push("Headers validated");
22 }
23 });
24
25 // Listen for completion
26 requestEmitter.on("complete", (status) => {
27 console.log(`Request completed with status: ${status}`);
28 results.push(`Completed: ${status}`);
29 });
30
31 // Listen for errors
32 requestEmitter.on("error", (err) => {
33 console.error(`Error: ${err.message}`);
34 results.push(`Error: ${err.message}`);
35 });
36
37 // Emit events in sequence
38 requestEmitter.emit("start", requestUrl);
39 requestEmitter.emit("validate", { headers: requestHeaders });
40 requestEmitter.emit("complete", 200);
41
42 return new Response(JSON.stringify({ events: results }), {
43 headers: { "Content-Type": "application/json" }
44 });
45};
46
47export default main;

Para uma requisição a https://example.com/, a function responde com as três etapas na ordem em que as emitiu:

{"events":["Started: https://example.com/","Headers validated","Completed: 200"]}

Listeners de execução única e tratamento de erros

Esta function registra um listener que é executado uma única vez, dois listeners para o mesmo evento e um listener para o evento error:

JavaScript
01import { EventEmitter } from "node:events";
02
03const main = async (event) => {
04 const emitter = new EventEmitter();
05 const log = [];
06
07 // One-time listener - only executes once
08 emitter.once("init", () => {
09 console.log("Initialization complete");
10 log.push("Initialized");
11 });
12
13 // Multiple listeners for same event
14 emitter.on("data", (chunk) => {
15 console.log(`Processing chunk: ${chunk}`);
16 log.push(`Chunk: ${chunk}`);
17 });
18
19 emitter.on("data", (chunk) => {
20 console.log(`Logging chunk: ${chunk}`);
21 log.push(`Logged: ${chunk}`);
22 });
23
24 // Error handling - special 'error' event
25 emitter.on("error", (err) => {
26 console.error(`Error caught: ${err.message}`);
27 log.push(`Error: ${err.message}`);
28 });
29
30 // Emit events
31 emitter.emit("init");
32 emitter.emit("init"); // Does not trigger again - once() used
33 emitter.emit("data", "chunk-1");
34 emitter.emit("data", "chunk-2");
35 emitter.emit("error", new Error("Test error"));
36
37 return new Response(JSON.stringify({ log }), {
38 headers: { "Content-Type": "application/json" }
39 });
40};
41
42export default main;

A function responde com uma entrada Initialized, as entradas dos dois listeners para cada chunk e o erro:

{"log":["Initialized","Chunk: chunk-1","Logged: chunk-1","Chunk: chunk-2","Logged: chunk-2","Error: Test error"]}

Handlers de eventos assíncronos

Esta function emite um evento a partir de cada uma de duas chamadas fetch em paralelo e aguarda as duas chamadas com Promise.all(). emit() não aguarda uma Promise que um listener retorna, por isso a function aguarda as próprias chamadas fetch:

JavaScript
01import { EventEmitter } from "node:events";
02import { setTimeout } from "node:timers/promises";
03
04const main = async (event) => {
05 const emitter = new EventEmitter();
06 const results = [];
07
08 // EventEmitter does NOT await Promises returned by listeners.
09 // The emit() method returns immediately, without waiting for async operations.
10 // For async operations, use Promise-based patterns
11 // instead of relying on EventEmitter alone.
12
13 // Listen for fetch completion events
14 emitter.on("fetched", (result) => {
15 results.push(result);
16 console.log(`Fetched: ${result.url}`);
17 });
18
19 // Error handler
20 emitter.on("error", (err) => {
21 console.error(`Fetch error: ${err.message}`);
22 results.push({ error: err.message });
23 });
24
25 // Define async fetch function that emits events
26 const fetchData = async (url) => {
27 try {
28 const response = await fetch(url);
29 const data = await response.json();
30 const result = { url, status: response.status, data };
31 emitter.emit("fetched", result);
32 return result;
33 } catch (error) {
34 emitter.emit("error", error);
35 return { url, error: error.message };
36 }
37 };
38
39 // URLs to fetch
40 const urls = [
41 "https://jsonplaceholder.typicode.com/todos/1",
42 "https://jsonplaceholder.typicode.com/todos/2"
43 ];
44
45 // Execute fetches in parallel and wait for completion
46 const fetchResults = await Promise.all(urls.map(fetchData));
47
48 return new Response(JSON.stringify({
49 results,
50 fetchResults
51 }), {
52 headers: { "Content-Type": "application/json" }
53 });
54};
55
56export default main;

A function responde com os resultados que o listener coletou e os resultados que Promise.all() retornou:

{"results":[{"url":"https://jsonplaceholder.typicode.com/todos/1","status":200,"data":{"userId":1,"id":1,"title":"delectus aut autem","completed":false}},{"url":"https://jsonplaceholder.typicode.com/todos/2","status":200,"data":{"userId":1,"id":2,"title":"quis ut nam facilis et officia qui","completed":false}}],"fetchResults":[{"url":"https://jsonplaceholder.typicode.com/todos/1","status":200,"data":{"userId":1,"id":1,"title":"delectus aut autem","completed":false}},{"url":"https://jsonplaceholder.typicode.com/todos/2","status":200,"data":{"userId":1,"id":2,"title":"quis ut nam facilis et officia qui","completed":false}}]}

Classe EventEmitter personalizada

Esta function estende EventEmitter em uma classe para um domínio específico, processa duas requisições com ela e conta os listeners de um evento:

JavaScript
01import { EventEmitter } from "node:events";
02
03// Custom class extending EventEmitter
04class RequestHandler extends EventEmitter {
05 constructor() {
06 super();
07 this.requestCount = 0;
08 }
09
10 processRequest(request) {
11 this.requestCount++;
12 this.emit("request", { id: this.requestCount, url: request.url });
13
14 try {
15 // Simulate processing
16 const result = { processed: true, id: this.requestCount };
17 this.emit("success", result);
18 return result;
19 } catch (error) {
20 this.emit("error", error);
21 throw error;
22 }
23 }
24}
25
26const main = async (event) => {
27 const handler = new RequestHandler();
28 const logs = [];
29
30 // Attach listeners
31 handler.on("request", (data) => {
32 logs.push(`Request #${data.id}: ${data.url}`);
33 });
34
35 handler.on("success", (result) => {
36 logs.push(`Success: ${JSON.stringify(result)}`);
37 });
38
39 handler.on("error", (err) => {
40 logs.push(`Error: ${err.message}`);
41 });
42
43 // Process requests
44 handler.processRequest(event.request);
45 handler.processRequest({ url: "https://example.com/test" });
46
47 // Get listener counts
48 const listenerCount = handler.listenerCount("request");
49 logs.push(`Request listeners: ${listenerCount}`);
50
51 return new Response(JSON.stringify({ logs, totalRequests: handler.requestCount }), {
52 headers: { "Content-Type": "application/json" }
53 });
54};
55
56export default main;

Para uma requisição a https://example.com/, a function responde com o log das duas requisições e a contagem de requisições:

{"logs":["Request #1: https://example.com/","Success: {\"processed\":true,\"id\":1}","Request #2: https://example.com/test","Success: {\"processed\":true,\"id\":2}","Request listeners: 1"],"totalRequests":2}

APIs suportadas

A tabela lista o status de cada API de node:events no Azion Runtime:

APIStatus
new EventEmitter()🟢 Com suporte
emitter.on()🟢 Com suporte
emitter.once()🟢 Com suporte
emitter.emit()🟢 Com suporte
emitter.off()🟢 Com suporte
emitter.removeListener()🟢 Com suporte
emitter.removeAllListeners()🟢 Com suporte
emitter.listenerCount()🟢 Com suporte
emitter.listeners()🟢 Com suporte
emitter.eventNames()🟢 Com suporte
emitter.prependListener()🟢 Com suporte
emitter.prependOnceListener()🟢 Com suporte
emitter.setMaxListeners()🟢 Com suporte
emitter.getMaxListeners()🟢 Com suporte
EventEmitter.listenerCount()🟢 Com suporte
EventEmitter.defaultMaxListeners🟢 Com suporte
events.once()🟢 Com suporte
captureRejections🟡 Parcialmente suportado

As APIs marcadas como 🟡 Parcialmente suportado têm funcionalidade limitada em comparação com a implementação completa do Node.js. A opção captureRejections é uma delas; por isso, trate as rejeições de Promise explicitamente em listeners assíncronos em vez de depender da captura automática.

No Azion Runtime, a função de nível de módulo events.once() retorna uma Promise que é resolvida com um array dos argumentos que o evento carregou. Um evento error emitido sem um listener de error lança o erro emitido. Quando um evento tem mais listeners do que o limite definido com emitter.setMaxListeners(), o runtime registra este aviso no log:

Error: Possible EventEmitter memory leak detected. 2 x listeners added to [object Object]. MaxListeners is 1. Use emitter.setMaxListeners() to increase limit

Recursos relacionados

APIs do Node.js

O status de cada módulo do Node.js no Azion Runtime, incluindo events.

Use APIs do Node.js com polyfills

Como o build transforma imports node: em código que é executado no Azion Runtime.

EventTarget

A alternativa da Web API para disparar e ouvir eventos.

Documentação de events do Node.js

A referência completa do Node.js para cada API de node:events da tabela.