node:events

The node:events module in Azion Runtime: the EventEmitter class, examples of listeners, async handlers, and subclasses, and the supported APIs.

Last updated

View as Markdown Agent setup

The node:events module provides EventEmitter, the Node.js class for event-driven code. An event emitter is an object that emits named events, and listeners registered on it run each time it emits one of those names. In Azion Runtime, functions use it to decouple logic: one part of the code emits an event, and dedicated listeners react to it.

Examples

Each example is a complete function that imports EventEmitter from node:events. The response below each example is the one a deployed function returns.

Basic event emission

This function registers a listener for one event, then emits that event with three arguments:

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;

The listener logs an event occurred! 1 2 3, and the function responds with:

Event emitted

Request lifecycle events

This function emits one event per processing stage of the request and records what each listener saw:

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;

For a request to https://example.com/, the function responds with the three stages in the order it emitted them:

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

One-time listeners and error handling

This function registers a listener that runs once, two listeners for the same event, and a listener for the error event:

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;

The function responds with one Initialized entry, both listeners’ entries for each chunk, and the error:

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

Async event handlers

This function emits an event from each of two parallel fetch calls and waits for both calls with Promise.all(). emit() does not wait for a Promise that a listener returns, so the function awaits the fetches themselves:

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;

The function responds with the results the listener collected and the results Promise.all() returned:

{"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}}]}

Custom EventEmitter class

This function extends EventEmitter into a class for one domain, processes two requests with it, and counts the listeners of one event:

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;

For a request to https://example.com/, the function responds with the log of both requests and the request count:

{"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}

Supported APIs

The table lists the status of each node:events API in Azion Runtime:

APIStatus
new EventEmitter()🟢 Supported
emitter.on()🟢 Supported
emitter.once()🟢 Supported
emitter.emit()🟢 Supported
emitter.off()🟢 Supported
emitter.removeListener()🟢 Supported
emitter.removeAllListeners()🟢 Supported
emitter.listenerCount()🟢 Supported
emitter.listeners()🟢 Supported
emitter.eventNames()🟢 Supported
emitter.prependListener()🟢 Supported
emitter.prependOnceListener()🟢 Supported
emitter.setMaxListeners()🟢 Supported
emitter.getMaxListeners()🟢 Supported
EventEmitter.listenerCount()🟢 Supported
EventEmitter.defaultMaxListeners🟢 Supported
events.once()🟢 Supported
captureRejections🟡 Partially supported

APIs marked 🟡 Partially supported have limited functionality compared to the full Node.js implementation. The captureRejections option is one of them, so handle Promise rejections explicitly in async listeners instead of relying on automatic capture.

In Azion Runtime, the module-level events.once() function returns a Promise that resolves with an array of the arguments the event carried. An error event emitted with no error listener throws the emitted error. When an event has more listeners than the limit set with emitter.setMaxListeners(), the runtime logs this warning:

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

The status of every Node.js module in Azion Runtime, events included.

Use Node.js APIs through polyfills

How the build turns node: imports into code that runs in Azion Runtime.

EventTarget

The Web API alternative for dispatching and listening to events.

Node.js events documentation

The full Node.js reference for every node:events API in the table.