Introduction

Event systems are callback-oriented, but application code often reads better when it can await a single event. The standard bridge is to wrap one event occurrence in a promise, then add cleanup, timeout, and cancellation so the waiting code does not leak listeners or hang forever.

Turn One Event Into a Promise

For one-shot waits, the simplest helper listens once, resolves the promise, and removes the listener immediately.

1function waitForEvent(target, eventName) {
2  return new Promise((resolve) => {
3    const handler = (event) => {
4      target.removeEventListener(eventName, handler);
5      resolve(event);
6    };
7
8    target.addEventListener(eventName, handler);
9  });
10}
11
12async function demo(button) {
13  console.log("waiting for click");
14  const event = await waitForEvent(button, "click");
15  console.log("clicked at", event.clientX, event.clientY);
16}

This gives you straight-line async code without nesting the next step inside the event callback.

Add Timeout and Cancellation for Real Workflows

Production code usually needs an escape hatch in case the event never arrives. Timeout and abort handling are the two most useful additions.

1function waitForEventWithTimeout(target, eventName, timeoutMs, signal) {
2  return new Promise((resolve, reject) => {
3    let done = false;
4
5    const cleanup = () => {
6      target.removeEventListener(eventName, onEvent);
7      if (signal) signal.removeEventListener("abort", onAbort);
8      clearTimeout(timer);
9    };
10
11    const finish = (fn) => {
12      if (done) return;
13      done = true;
14      cleanup();
15      fn();
16    };
17
18    const onEvent = (event) => finish(() => resolve(event));
19    const onAbort = () => finish(() => reject(new Error("aborted")));
20
21    const timer = setTimeout(() => {
22      finish(() => reject(new Error("timeout")));
23    }, timeoutMs);
24
25    target.addEventListener(eventName, onEvent);
26    if (signal) signal.addEventListener("abort", onAbort, { once: true });
27  });
28}

That pattern is useful for UI flows such as "wait for the user to click, unless the screen is closed first."

Use One-Shot Listener Options When Available

Browser event targets support { once: true }, which can reduce manual cleanup code for simple cases.

1function waitForEventOnce(target, eventName) {
2  return new Promise((resolve) => {
3    target.addEventListener(eventName, resolve, { once: true });
4  });
5}

This is fine for short, trusted workflows. As soon as failure or cancellation matters, go back to the more explicit helper.

Node.js Uses EventEmitter, Not DOM Events

On the server side, many event sources expose once and on instead of addEventListener. The idea is the same, but the API surface changes.

1const { EventEmitter } = require("events");
2
3function waitForEmitter(emitter, eventName) {
4  return new Promise((resolve) => {
5    emitter.once(eventName, (...args) => resolve(args));
6  });
7}
8
9async function run() {
10  const emitter = new EventEmitter();
11  setTimeout(() => emitter.emit("ready", "ok", 200), 100);
12
13  const [status, code] = await waitForEmitter(emitter, "ready");
14  console.log(status, code);
15}
16
17run();

Keeping separate helpers for DOM and EventEmitter sources is usually clearer than trying to force both APIs through one universal wrapper.

Waiting for More Than One Invocation

If you need a sequence of events, loop with a one-shot helper instead of registering many listeners at once.

1async function waitForNClicks(button, count) {
2  const events = [];
3
4  for (let i = 0; i < count; i++) {
5    events.push(await waitForEvent(button, "click"));
6  }
7
8  return events;
9}

This preserves ordering and keeps cleanup predictable. If you need a continuous stream of events instead of a fixed count, an async iterator or observable abstraction is usually a better fit than repeatedly allocating one promise per event.

Common Pitfalls

The most common mistake is resolving the promise without removing the listener. That creates leaks and duplicate behavior on later events.

Another common issue is waiting forever because the helper has no timeout or abort path. Developers also sometimes assume browser and Node event APIs are interchangeable, but DOM EventTarget and Node EventEmitter have different primitives and need slightly different wrappers.

Summary

• Wrap one event in a promise when you need await-style control flow.
• Remove listeners after resolution, or use one-shot listener options when appropriate.
• Add timeout and cancellation for production safety.
• Use source-specific helpers for DOM events and Node EventEmitter events.
• Switch to stream-oriented abstractions if the code needs an ongoing event sequence rather than a single occurrence.