Build an event emitter

What you will build

An event is a message that says something happened, like "the cart changed". A listener is a function that waits for one kind of event. An event emitter is an object that keeps listeners and calls them when their event happens. In this lesson you build a real one, step by step, and test its tricky cases.

The observer & pub/sub lesson explains why this is useful: one part of an app announces a change, and other parts react without knowing about each other. The functors & monads lesson built a tiny Observable. Here you write the emitter itself.

The code uses ideas from other lessons. You don't need to reread them, but they help:

• Closures: a function remembers the variables around it. The cleanup functions use this.
• Events and custom events: the browser's own event system, which we compare with ours near the end.
• Cancellation: AbortSignal, a way to stop many things at once.
• Memory management: why listeners you forget to remove waste memory.
• Classic utilities: shows once as a helper on its own. Here once is a method of the emitter.

The table below lists what our emitter must do. Read each row as: "for this job, this is the rule our emitter follows." Each later section shows one row in code.

The emitter keeps its listeners in a Map. A Map is a lookup table: you give it a key, and it gives back a value. Here the key is an event name, like "save". The value is an array of the listener functions for that name.

Why an array, and not a Set? A Set keeps each value only once. An array lets you add the same function twice, and it keeps the order in which you added them. Both matter, as you'll see in the next section.

Node.js has its own built-in EventEmitter. Its on method returns the emitter itself, so you can chain calls like bus.on(...).on(...). Our on is different on purpose. It returns a cleanup function: a function that removes the listener when you call it. Web pages need to remove listeners often, so this makes cleanup easy. Other methods, like off, removeAllListeners, and setMaxListeners, still return the emitter, so you can chain them.

Here is the whole class. It is long, so the list after it walks through it in parts. Names that start with # are private: only code inside the class can use them.

1class EventEmitter {2  #events = new Map();3  #maxListeners = 10;4  #cleanup = new WeakMap();5  #warned = new Set();6 7  on(event, listener, options = {}) {8    const stored = (...args) => listener(...args);9    stored.listener = listener;10    return this.#subscribe(event, stored, options);11  }12 13  once(event, listener, options = {}) {14    const wrapper = (...args) => {15      this.#removeStored(event, wrapper, true);16      listener(...args);17    };18    wrapper.listener = listener;19    return this.#subscribe(event, wrapper, options);20  }21 22  off(event, listener) {23    this.#removeStored(event, listener, false);24    return this;25  }26 27  emit(event, ...args) {28    const listeners = this.#events.get(event);29    if ((!listeners || listeners.length === 0) && event === "error") {30      const error = args[0];31      throw error instanceof Error ? error : new Error(32        "Unhandled error event: " + String(error),33      );34    }35    if (!listeners || listeners.length === 0) return false;36    const snapshot = [...listeners];37    for (const listener of snapshot) {38      listener(...args);39    }40    return true;41  }42 43  listenerCount(event) {44    return this.#events.get(event)?.length ?? 0;45  }46 47  removeAllListeners(event) {48    const events = event === undefined ? [...this.#events.keys()] : [event];49    for (const name of events) {50      const listeners = this.#events.get(name) ?? [];51      for (const listener of listeners) this.#cleanup.get(listener)?.();52      this.#events.delete(name);53      this.#warned.delete(name);54    }55    return this;56  }57 58  setMaxListeners(count) {59    if (!Number.isInteger(count) || count < 0) {60      throw new RangeError("count must be a non-negative integer");61    }62    this.#maxListeners = count;63    return this;64  }65 66  #subscribe(event, stored, options) {67    if (options.signal?.aborted) return () => false;68    let removed = false;69    const unsubscribe = () => {70      if (removed) return false;71      removed = this.#removeStored(event, stored, true);72      return removed;73    };74    if (options.signal) {75      const abort = () => unsubscribe();76      this.#cleanup.set(stored, () => options.signal?.removeEventListener("abort", abort));77      options.signal.addEventListener("abort", abort, { once: true });78    }79    const listeners = this.#events.get(event) ?? [];80    listeners.push(stored);81    this.#events.set(event, listeners);82    if (this.#maxListeners > 0 && listeners.length > this.#maxListeners && !this.#warned.has(event)) {83      this.#warned.add(event);84      console.warn("Possible EventEmitter memory leak detected. " + listeners.length + " " + event + " listeners added.");85    }86    return unsubscribe;87  }88 89  #removeStored(event, listener, exact) {90    const listeners = this.#events.get(event);91    if (!listeners) return false;92    for (let index = listeners.length - 1; index >= 0; index -= 1) {93      const candidate = listeners[index];94      if (candidate === listener || (!exact && candidate.listener === listener)) {95        listeners.splice(index, 1);96        this.#cleanup.get(candidate)?.();97        this.#cleanup.delete(candidate);98        if (listeners.length === 0) this.#events.delete(event);99        return true;100      }101    }102    return false;103  }104}

Read the class in parts:

• Lines 2 to 5 hold private data. #events is the Map of listener arrays.
• Lines 7 to 11 are on. It wraps your function in a new one, then hands it to #subscribe, which adds it to the list and returns the cleanup function.
• Lines 13 to 20 are once, and lines 22 to 25 are off. The next section explains both.
• Lines 27 to 41 are emit. It copies the list, then calls each listener in the copy.
• Lines 66 to 87 are #subscribe. It adds the listener, builds the cleanup function, and handles the signal option you'll meet later.
• Lines 89 to 103 are #removeStored. It finds one listener and takes it out of the list.

1const bus = new EventEmitter();2bus.on("tea:ready", (drink) => console.log("ready " + drink));3console.log(bus.emit("tea:ready", "tea"));

Line 2 adds a listener for the event name tea:ready. Line 3 sends that event with the value "tea". The listener gets "tea" as drink and prints ready tea. Then emit returns true, because a listener ran, and line 3 prints it.

All of this happens before the next line of code runs. We call this synchronous: emit finishes calling every listener before it returns.

1const bus = new EventEmitter();2const unsubscribeHeader = bus.on("cart:changed", (item, count) => {3  console.log(`header ${count} ${item}`);4});5bus.once("cart:changed", (item) => {6  console.log(`analytics first ${item}`);7});8console.log(bus.emit("cart:changed", "book", 1));9unsubscribeHeader();10console.log(bus.emit("cart:changed", "pen", 2));

Line 2 adds a normal listener with on and keeps its cleanup function as unsubscribeHeader. Line 5 adds a one-time listener with once: it runs on the next event only. Line 8 sends cart:changed with "book" and 1. It prints header 1 book, then analytics first book, then true.

Line 9 calls the cleanup function, which removes the header listener. The one-time listener is already gone. So the second emit, on line 10, finds no listeners and prints false. Node's emit returns the same thing: true if any listener ran, false if none did.

1const bus = new EventEmitter();2const stop = bus.on("save", () => console.log("saved"));3console.log(stop());4console.log(stop());5console.log(bus.emit("save"));

Line 2 adds a listener and keeps its cleanup function as stop. Line 3 calls stop(). It removes the listener and returns true. Line 4 calls it again. There is nothing left to remove, so it returns false and does no harm. Line 5 sends save, but no listener is left, so it prints false.

Call the cleanup function in the place where the listener's job ends, such as when a part of the page is removed.

1const bus = new EventEmitter();2function shared() { console.log("shared"); }3const stopFirst = bus.on("ping", shared);4bus.on("ping", () => console.log("middle"));5bus.on("ping", shared);6stopFirst();7bus.emit("ping");

Lines 3 and 5 add the same function, shared, two times. Line 4 adds a middle listener between them. Each call to on stores its own wrapper, so each one has its own cleanup function. Line 6 calls stopFirst, which removes only the first shared. So line 7 prints middle, then shared.

off works differently: it removes the newest match. The next section shows how.

Removing a listener sounds easy. It gets harder when the same function is in the list two times. Which one should go? Node's emitter removes one of them: the one added most recently. It searches the list from the end. Our off does the same.

1const bus = new EventEmitter();2function handler() {3  console.log("handler");4}5bus.on("ping", handler);6bus.on("ping", () => console.log("middle"));7bus.on("ping", handler);8bus.off("ping", handler);9bus.emit("ping");

Line 5 adds handler. Line 6 adds a middle listener. Line 7 adds handler again. Line 8 calls off, which removes the newest handler, the one from line 7. So line 9 prints handler, then middle.

once has its own puzzle. It does not store your function directly. It stores a wrapper: a small function that calls yours. But you still want off(event, original) to work with your own function. So the wrapper keeps your function in a property, wrapper.listener. Node uses the same trick.

When off looks through the list, it asks two questions about each stored function:

• Is it the function you passed? (candidate === listener)
• Does its .listener property point to the function you passed? (candidate.listener === listener)

1const bus = new EventEmitter();2function original() {3  console.log("should not run");4}5bus.once("ready", original);6bus.off("ready", original);7console.log(bus.listenerCount("ready"));8console.log(bus.emit("ready"));

Line 5 adds original with once, so the list holds a wrapper. Line 6 calls off with original. The wrapper's .listener matches, so the wrapper is removed before the event ever happens. Line 7 prints 0, the number of listeners left, and line 8 prints false.

1const bus = new EventEmitter();2bus.once("ready", () => {3  console.log("ready");4  bus.emit("ready");5});6console.log(bus.emit("ready"));

Line 2 adds a one-time listener. When it runs, line 4 sends ready again, from inside the listener. The wrapper removed itself before it called your function, so this inner emit finds no listener and does nothing. The output is ready, then true from line 6. There is no second ready.

That is why the wrapper removes itself before it calls your function. If it waited until after, the inner emit on line 4 would still find it in the list and call it again.

A listener can add or remove listeners while emit is still running. What should happen to the event that is being sent right now? Node's rule has two parts:

• A listener removed during an emit still runs in that emit.
• A listener added during an emit waits for the next emit.

Our emit follows the same rule with one line of the class, line 36: const snapshot = [...listeners]. The spread [...listeners] makes a copy of the array. We call this copy a snapshot. The loop calls the functions in the copy, so changes to the stored list don't affect it.

1const bus = new EventEmitter();2const log = [];3function first() {4  log.push("first");5  bus.off("work", second);6  bus.on("work", () => log.push("third"));7}8function second() {9  log.push("second");10}11bus.on("work", first);12bus.on("work", second);13bus.emit("work");14bus.emit("work");15console.log(log.join(", "));

Lines 11 and 12 add first and second. Line 13 sends work, and the copy holds first and second. While first runs, line 5 removes second and line 6 adds a new third listener. Both changes go to the stored list, not to the copy. So second still runs in this emit.

Line 14 sends work again. Now the copy holds first and third. Line 15 prints first, second, first, third.

Now step through a longer run. One listener removes itself during the emit, and a once listener removes itself before it runs. Watch two things: how many save listeners are stored, and what the copy holds.

1class EventEmitter {2  #events = new Map();3  #maxListeners = 10;4  #cleanup = new WeakMap();5  #warned = new Set();6 7  on(event, listener, options = {}) {8    const stored = (...args) => listener(...args);9    stored.listener = listener;10    return this.#subscribe(event, stored, options);11  }12 13  once(event, listener, options = {}) {14    const wrapper = (...args) => {15      this.#removeStored(event, wrapper, true);16      listener(...args);17    };18    wrapper.listener = listener;19    return this.#subscribe(event, wrapper, options);20  }21 22  off(event, listener) {23    this.#removeStored(event, listener, false);24    return this;25  }26 27  emit(event, ...args) {28    const listeners = this.#events.get(event);29    if ((!listeners || listeners.length === 0) && event === "error") {30      const error = args[0];31      throw error instanceof Error ? error : new Error(32        "Unhandled error event: " + String(error),33      );34    }35    if (!listeners || listeners.length === 0) return false;36    const snapshot = [...listeners];37    for (const listener of snapshot) {38      listener(...args);39    }40    return true;41  }42 43  listenerCount(event) {44    return this.#events.get(event)?.length ?? 0;45  }46 47  removeAllListeners(event) {48    const events = event === undefined ? [...this.#events.keys()] : [event];49    for (const name of events) {50      const listeners = this.#events.get(name) ?? [];51      for (const listener of listeners) this.#cleanup.get(listener)?.();52      this.#events.delete(name);53      this.#warned.delete(name);54    }55    return this;56  }57 58  setMaxListeners(count) {59    if (!Number.isInteger(count) || count < 0) {60      throw new RangeError("count must be a non-negative integer");61    }62    this.#maxListeners = count;63    return this;64  }65 66  #subscribe(event, stored, options) {67    if (options.signal?.aborted) return () => false;68    let removed = false;69    const unsubscribe = () => {70      if (removed) return false;71      removed = this.#removeStored(event, stored, true);72      return removed;73    };74    if (options.signal) {75      const abort = () => unsubscribe();76      this.#cleanup.set(stored, () => options.signal?.removeEventListener("abort", abort));77      options.signal.addEventListener("abort", abort, { once: true });78    }79    const listeners = this.#events.get(event) ?? [];80    listeners.push(stored);81    this.#events.set(event, listeners);82    if (this.#maxListeners > 0 && listeners.length > this.#maxListeners && !this.#warned.has(event)) {83      this.#warned.add(event);84      console.warn("Possible EventEmitter memory leak detected. " + listeners.length + " " + event + " listeners added.");85    }86    return unsubscribe;87  }88 89  #removeStored(event, listener, exact) {90    const listeners = this.#events.get(event);91    if (!listeners) return false;92    for (let index = listeners.length - 1; index >= 0; index -= 1) {93      const candidate = listeners[index];94      if (candidate === listener || (!exact && candidate.listener === listener)) {95        listeners.splice(index, 1);96        this.#cleanup.get(candidate)?.();97        this.#cleanup.delete(candidate);98        if (listeners.length === 0) this.#events.delete(event);99        return true;100      }101    }102    return false;103  }104}105 106const bus = new EventEmitter();Run107const stopLogger = bus.on("save", (value) => {108  console.log("logger " + value);109  stopLogger();110});111bus.once("save", (value) => console.log("once " + value));112bus.on("save", (value) => console.log("tail " + value));113bus.emit("save", "draft");114bus.emit("save", "final");

The lesson's tests run the same cases on Node's built-in emitter. Read each row of the table below as: "for this case, does our emitter act like Node's, and how do we know?"

Node treats the event name error as special. If you send error and no listener is waiting for it, emit throws the error. An error that nobody handles should not disappear quietly, so our emitter does the same. When an error listener exists, error is a normal event.

1const bus = new EventEmitter();2bus.on("error", (error) => console.log("handled " + error.message));3console.log(bus.emit("error", new Error("offline")));

Line 2 adds an error listener. Line 3 sends an Error with the message offline. The listener prints handled offline, and line 3 prints true.

1const bus = new EventEmitter();2bus.emit("error", new Error("boom"));

Here no one listens for error, so line 2 throws Error: boom. This is on purpose.

A listener that throws is a different case. An error event is a message you send on purpose. A throw is a crash inside a listener. Our emit does not catch it. The error leaves emit right away, and the listeners after it don't run. Node does the same. This keeps the error easy to see, with its real stack trace: the list of function calls that led to it.

1const bus = new EventEmitter();2const log = [];3bus.on("save", () => {4  log.push("first");5  throw new Error("boom");6});7bus.on("save", () => log.push("second"));8try {9  bus.emit("save");10} catch (error) {11  log.push("caught " + error.message);12}13console.log(log.join(", "));

Line 3 adds a listener that saves first and then throws, on line 5. Line 7 adds a second listener. Line 9 sends save inside a try block. The first listener throws, so the second never runs. Line 11, inside catch, saves the message. Line 13 prints first, caught boom.

An async function runs until its first await. Then it pauses and returns a promise. The next example shows what emit does with that promise.

1const bus = new EventEmitter();2bus.on("save", async () => {3  console.log("listener starts");4  await Promise.resolve();5  console.log("listener resumes");6});7console.log(bus.emit("save"));8console.log("caller continues");

Line 3 prints listener starts. Line 4 pauses the listener. emit does not wait for the promise, so it returns true right away, and line 7 prints it. Line 8 prints caller continues. Only after that does the listener go on and print listener resumes on line 5.

Our emitter also ignores that promise if it fails. Node's emitter has an option, captureRejections, that sends such failures to the error event.

Listeners that are never removed waste memory. This is called a memory leak. It happens when code adds a listener again and again and never removes it. Each listener stays in the list, and so does everything the listener uses.

Node warns when one event has more than 10 listeners, and our class does too. You can change that limit with setMaxListeners. But the warning is a hint, not a fix. Before you raise the limit, check that each listener gets removed.

The next example uses two words from page frameworks. To mount a part means to put it on the page. To unmount it means to take it off.

1const bus = new EventEmitter();2function mountCartHeader(emitter, cart) {3  return emitter.on("cart:changed", () => console.log(cart.owner + " cart updated"));4}5const cart = { owner: "Asha" };6const unmount = mountCartHeader(bus, cart);7bus.emit("cart:changed");8unmount();9console.log(bus.emit("cart:changed"));

Lines 2 to 4 define mountCartHeader. Line 3 adds a listener that uses cart and returns its cleanup function. Because the listener uses cart, the emitter keeps cart in memory for as long as the listener is in the list.

Line 6 mounts the header and keeps the cleanup function as unmount. Line 7 prints Asha cart updated. Line 8 calls unmount(), which removes the listener. Line 9 prints false: no listener is left. In a page framework, return this cleanup function from the code that added the listener, so it runs when the part is unmounted.

The next two examples use Node's own emitter. They only run in Node.js, so they have no Edit & run button.

1import { spawnSync } from "node:child_process";2 3const env = Object.fromEntries(4  Object.entries(process.env).filter(([key]) => !key.startsWith("NODE_TEST_")),5);6const child = spawnSync(process.execPath, [7  "-e",8  "const { EventEmitter } = require('node:events'); new EventEmitter().emit('error', new Error('boom'));",9], { env, encoding: "utf8" });10 11console.log(child.status);12console.log(child.stderr.includes("Unhandled 'error' event"));

Line 6 starts a second Node process, called a child process. That process sends an error event with no listener. Line 11 prints the process's exit code, which is not 0 because it crashed. Line 12 prints true, because the error message says Unhandled 'error' event.

1import { EventEmitter } from "node:events";2 3const bus = new EventEmitter();4bus.setMaxListeners(1);5bus.on("data", () => {});6bus.on("data", () => {}); // Node prints MaxListenersExceededWarning to stderr.7console.log(bus.listenerCount("data"));

Line 4 sets the limit to 1. Line 6 adds a second listener, so Node prints a MaxListenersExceededWarning. Both listeners are still added, so line 7 prints 2.

An Observable is an object with a subscribe method. You pass it a function, or an object with a next method, and it calls that function with each new value. subscribe returns a subscription: an object with an unsubscribe() method that stops the values. You built a tiny one in the functors & monads lesson.

The fromEvent function below makes one event of our emitter look like an Observable:

• subscribe calls emitter.on and keeps the cleanup function it gets back.
• unsubscribe() is that cleanup function, so it removes the emitter's listener.

1function fromEvent(emitter, name) {2  return {3    subscribe(observer) {4      const next = typeof observer === "function" ? observer : observer.next?.bind(observer);5      if (!next) return { unsubscribe() {} };6      const unsubscribe = emitter.on(name, (...args) => {7        next(args.length > 1 ? args : args[0]);8      });9      return { unsubscribe };10    },11  };12}13 14const bus = new EventEmitter();15const clicks = fromEvent(bus, "click");16const subscription = clicks.subscribe({17  next([x, y]) {18    console.log(`click at ${x},${y}`);19  },20});21bus.emit("click", 10, 20);22subscription.unsubscribe();23bus.emit("click", 30, 40);

Line 4 accepts either a plain function or an object with next. For an object, .bind(observer) makes sure this inside next is still that object. Line 6 adds the emitter listener. Line 7 passes one value on: the only argument, or an array when there are several.

Line 21 sends a click with 10 and 20, so the observer prints click at 10,20. Line 22 unsubscribes. Line 23 sends another click, but no listener is left, so nothing prints.

1class EventEmitter {2  #events = new Map();3  #maxListeners = 10;4  #cleanup = new WeakMap();5  #warned = new Set();6 7  on(event, listener, options = {}) {8    const stored = (...args) => listener(...args);9    stored.listener = listener;10    return this.#subscribe(event, stored, options);11  }12 13  once(event, listener, options = {}) {14    const wrapper = (...args) => {15      this.#removeStored(event, wrapper, true);16      listener(...args);17    };18    wrapper.listener = listener;19    return this.#subscribe(event, wrapper, options);20  }21 22  off(event, listener) {23    this.#removeStored(event, listener, false);24    return this;25  }26 27  emit(event, ...args) {28    const listeners = this.#events.get(event);29    if ((!listeners || listeners.length === 0) && event === "error") {30      const error = args[0];31      throw error instanceof Error ? error : new Error(32        "Unhandled error event: " + String(error),33      );34    }35    if (!listeners || listeners.length === 0) return false;36    const snapshot = [...listeners];37    for (const listener of snapshot) {38      listener(...args);39    }40    return true;41  }42 43  listenerCount(event) {44    return this.#events.get(event)?.length ?? 0;45  }46 47  removeAllListeners(event) {48    const events = event === undefined ? [...this.#events.keys()] : [event];49    for (const name of events) {50      const listeners = this.#events.get(name) ?? [];51      for (const listener of listeners) this.#cleanup.get(listener)?.();52      this.#events.delete(name);53      this.#warned.delete(name);54    }55    return this;56  }57 58  setMaxListeners(count) {59    if (!Number.isInteger(count) || count < 0) {60      throw new RangeError("count must be a non-negative integer");61    }62    this.#maxListeners = count;63    return this;64  }65 66  #subscribe(event, stored, options) {67    if (options.signal?.aborted) return () => false;68    let removed = false;69    const unsubscribe = () => {70      if (removed) return false;71      removed = this.#removeStored(event, stored, true);72      return removed;73    };74    if (options.signal) {75      const abort = () => unsubscribe();76      this.#cleanup.set(stored, () => options.signal?.removeEventListener("abort", abort));77      options.signal.addEventListener("abort", abort, { once: true });78    }79    const listeners = this.#events.get(event) ?? [];80    listeners.push(stored);81    this.#events.set(event, listeners);82    if (this.#maxListeners > 0 && listeners.length > this.#maxListeners && !this.#warned.has(event)) {83      this.#warned.add(event);84      console.warn("Possible EventEmitter memory leak detected. " + listeners.length + " " + event + " listeners added.");85    }86    return unsubscribe;87  }88 89  #removeStored(event, listener, exact) {90    const listeners = this.#events.get(event);91    if (!listeners) return false;92    for (let index = listeners.length - 1; index >= 0; index -= 1) {93      const candidate = listeners[index];94      if (candidate === listener || (!exact && candidate.listener === listener)) {95        listeners.splice(index, 1);96        this.#cleanup.get(candidate)?.();97        this.#cleanup.delete(candidate);98        if (listeners.length === 0) this.#events.delete(event);99        return true;100      }101    }102    return false;103  }104}105 106function fromEvent(emitter, name) {107  return {108    subscribe(observer) {109      const next = typeof observer === "function" ? observer : observer.next?.bind(observer);110      if (!next) return { unsubscribe() {} };111      const unsubscribe = emitter.on(name, (...args) => {112        next(args.length > 1 ? args : args[0]);113      });114      return { unsubscribe };115    },116  };117}118 119const bus = new EventEmitter();Run120const clicks = fromEvent(bus, "click");121const subscription = clicks.subscribe({122  next([x, y]) {123    console.log(`click at ${x},${y}`);124  },125});126bus.emit("click", 10, 20);127subscription.unsubscribe();128bus.emit("click", 30, 40);

Browser tools often use an AbortSignal to stop things. You get one from an AbortController: calling controller.abort() tells everyone using its signal to stop. Our on accepts { signal } as a third argument, like the browser's addEventListener. When the signal aborts, the listener is removed. One controller can remove many listeners at once.

1const bus = new EventEmitter();2const group = new AbortController();3bus.on("message", (text) => console.log("message " + text), {4  signal: group.signal,5});6bus.emit("message", "before abort");7group.abort();8console.log(bus.listenerCount("message"));9console.log(bus.emit("message", "after abort"));

Line 2 makes a controller called group. Lines 3 to 5 add a listener with its signal. Line 6 prints message before abort. Line 7 aborts, which removes the listener. Line 8 prints 0, and line 9 prints false.

You don't need your own emitter everywhere. The platforms already have one:

• In the browser, EventTarget is the built-in event system. Page elements use it, and browser tools understand it. It has options such as once and signal.
• In Node.js, EventEmitter from node:events is the standard. Streams, servers, and many packages use it.
• Your own emitter is a good fit when you control the code and want a small event system inside your app.

1const target = new EventTarget();2target.addEventListener("cart:changed", (event) => {3  console.log("header " + event.detail.count);4}, { once: true });5target.dispatchEvent(new CustomEvent("cart:changed", {6  detail: { count: 1 },7}));8target.dispatchEvent(new CustomEvent("cart:changed", {9  detail: { count: 2 },10}));

An EventTarget listener gets one Event object. To send your own data, use a CustomEvent and put the data in its detail property. Line 4 passes { once: true }, so the listener runs one time only. Line 5 sends a count of 1, and the listener prints header 1. Line 8 sends a count of 2, but the listener is gone, so nothing prints.

1const target = new EventTarget();2target.addEventListener("save", () => {3  console.log("first");4  throw new Error("boom");5});6target.addEventListener("save", () => console.log("second"));7console.log(target.dispatchEvent(new Event("save")));

In the browser, dispatchEvent does not throw a listener's error back to your code. It reports the error as uncaught and moves on to the next listener. So this code prints first, second, then true. Our emitter and Node's emitter work differently: a throw stops the emit, and later listeners don't run.

1const bus = new EventEmitter();2function checkReceiver() {3  console.log(this === bus);4}5bus.on("save", checkReceiver);6bus.emit("save");

Line 5 adds a regular function, not an arrow function. Line 6 sends the event. Our emit calls the listener on its own, not as a method of bus, so this is not bus. Line 3 prints false.

Node's emitter sets this to the emitter for regular functions. Arrow functions don't get their own this in either one. Keep this difference in mind if you reuse code written for Node.

The table below puts the three side by side. Read each row as a question, then read across to see each one's answer.

The playground shows the listener list that is normally hidden. Try this:

1. Press Emit cart:changed. The header and the one-time analytics listener both run. Then analytics is removed.
2. Press Toggle logger to add a logger, then emit again.
3. Press Remove header, press Toggle logger again to remove the logger, then emit. No listener is left, so emit returns false.

1const bus = new EventEmitter();2const stopHeader = bus.on("cart:changed", (item) => {3  console.log("Header saw " + item);4});5bus.once("cart:changed", (item) => {6  console.log("Analytics only tracks first " + item);7});8bus.emit("cart:changed", "book");9stopHeader();

Common misconceptions

• "Emitters wait and run listeners later." Our emitter and Node's EventEmitter call listeners right away. If a listener is slow, emit is slow too.
• "A Set is always better for listeners." A Set can't hold the same function twice. An array keeps the order and lets off remove one copy at a time.
• "once can remove itself after it runs." It must remove itself first. Otherwise, if the listener sends the same event again, it gets called a second time.
• "Catching every listener error is safer." It can hide bugs. Our emitter acts like Node: a thrown error leaves emit and stops the listeners after it.
• "A too-many-listeners warning means raise the limit." First look for listeners that are never removed, such as a page part that adds a listener every time it appears.
• "Observables replace emitters." An Observable can sit on top of an emitter. What matters is that unsubscribe() removes the emitter's listener.

Before other people use your emitter, write down its rules. Read each row of the table below as a question about the emitter and our answer.

Key takeaways

• Keep listeners in an array for each event name. The array keeps their order and allows the same function twice.
• Have on return a cleanup function, so removing one listener is a single call.
• For once, store a wrapper, keep your function on wrapper.listener, and remove the wrapper before calling your function.
• Copy the listener array before calling anyone, so changes during an emit only affect the next emit.
• Follow Node's rules for errors: an error event with no listener throws, and a listener that throws stops the listeners after it.
• Connect to Observables and AbortSignal by having them call the cleanup function.

Up next: build a small library. There, an event system like this one can let other code plug into the library.