Custom Event Emitters & Observer Pattern

Published by Brayan K

In real JavaScript apps, you often need different parts of your code to "react" when something happens somewhere else. A user clicks a button, data finishes loading, a WebSocket receives a message, a game character takes damage, a payment succeeds, a timer ends, or an AI response arrives. You don't want everything tightly glued together with messy function calls. Instead, you want a clean, decoupled system where one part emits events and other parts subscribe and react.

Part of the free JavaScript course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

Events are a calling contract, not automatic background work

A custom emitter stores subscriptions and calls them when a named event is emitted. You must choose what happens during additions, removals, recursive emission and failure. This lesson builds an ordinary synchronous broadcaster; it is not a replacement implementation of Node’s EventEmitter or the DOM EventTarget API.

const listeners = [];
const on = listener => listeners.push(listener);
const emit = value => {
  for (const listener of listeners) listener(value); // An ordinary synchronous call.
};
on(value => console.log("display", value));
on(value => console.log("audit", value));
console.log("before");
emit("saved");
console.log("after"); // Both subscribers have finished their synchronous work.

// ✅ Expected output:
// before
// display saved
// audit saved
// after

The emitter decouples the producer from a particular subscriber list, but the producer still waits for synchronous listeners. A direct function call is clearer when there is one required dependency and its result is needed. Callbacks & Callback Hell owns callback arguments and Events owns browser dispatch, propagation and default actions.

Name the subscription semantics before implementing them

Our on and once methods require a non-empty string event name and a function. Every call creates an independent registration, even for the same function. The returned unsubscribe handle is idempotent. Emit visits a snapshot in registration order, skips a registration removed before its turn, and defers additions until a later emit. Once registrations are removed before invocation. A thrown synchronous failure stops this first version and propagates unchanged. Returned values and promises are ignored.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const received = [];
const listener = value => received.push(value);
const removeFirst = bus.on("saved", listener);
bus.on("saved", listener);
console.log(bus.emit("saved", "A"), received.join(","));
removeFirst();
removeFirst();
received.length = 0;
console.log(bus.emit("saved", "B"), received.join(","));
console.log(bus.emit("missing", "C"));

// ✅ Expected output:
// 2 A,A
// 1 B
// 0

The Set contains registration records, not functions, so duplicate functions remain distinct. The handle closes over precisely one record and bucket. Empty buckets are removed from the map. Setting active before deleting makes the old snapshot aware of removal. Closures and Scope owns the retained-binding mechanism, and JavaScript Memory Management & Garbage Collection owns lifecycle and retention diagnosis.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
function prepare() { return undefined; }
bus.on("saved", prepare());

// ✅ Expected error:
// TypeError: listener must be a function

Mutation during delivery needs a deliberate rule

const listeners = [];
let added = false;
listeners.push(() => {
  console.log("first");
  if (!added) { added = true; listeners.push(() => console.log("late")); }
});
for (const listener of listeners) listener();

// ✅ Expected output:
// first
// late

That behaviour follows the collection being traversed; it is not a universal observer rule. An unbounded listener that keeps appending more listeners could prevent delivery from ending. A snapshot fixes the set of candidates, while the active check separately decides whether removals affect the current delivery.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const trace = [];
let added = false, removeSecond;
bus.on("tick", () => {
  trace.push("first");
  removeSecond();
  if (!added) { added = true; bus.on("tick", () => trace.push("late")); }
});
removeSecond = bus.on("tick", () => trace.push("second"));
console.log(bus.emit("tick"), trace.join(","));
trace.length = 0;
console.log(bus.emit("tick"), trace.join(","));

// ✅ Expected output:
// 1 first
// 2 first,late

The current snapshot excludes late. It includes second, but second is inactive by the time it would run. A snapshot-only emitter that ignores active flags would have a different, also possible contract. Do not assume a library uses this policy merely because its methods have the same names.

Once must unregister before calling user code

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const trace = [];
bus.once("ready", () => {
  trace.push("once");
  bus.emit("ready");
});
bus.on("ready", () => trace.push("regular"));
console.log(bus.emit("ready"), trace.join(","));

// ✅ Expected output:
// 2 once,regular,regular

The regular listener runs in the nested emission and again when the outer emission resumes. The outer count covers only its own delivery. Moving removal after the callback would let a recursive emit see the once registration still active. “Once” means at most one invocation of this registration, not successful completion or one invocation of every listener.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const failure = new Error("save failed");
bus.once("save", () => { throw failure; });
try { bus.emit("save"); } catch (error) { console.log(error === failure); }
console.log(bus.emit("save"));

// ✅ Expected output:
// true
// 0

A shared payload and a returned promise have separate consequences

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
bus.on("item", item => { item.status = "seen"; });
bus.on("item", item => console.log(item.status));
const item = { status: "new" };
bus.emit("item", item);
console.log(item.status);

// ✅ Expected output:
// seen
// seen

Broadcasting does not clone or freeze the payload. Choose a read-only convention or an explicit copy boundary when listeners should not modify shared data. Pure Functions, Immutability & Side Effects and Deep Copy vs Shallow Copy & Data Structures own those boundaries.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const trace = [];
bus.on("task", async () => {
  trace.push("start");
  await Promise.resolve();
  trace.push("finish");
});
console.log(bus.emit("task"), trace.join(","));
await Promise.resolve();
console.log(trace.join(","));

// ✅ Expected output:
// 1 start
// start,finish

This example’s promise fulfills. A rejected returned promise needs a caller-chosen observation policy; a surrounding synchronous try/catch around emit does not catch a later rejection. Do not pass async listeners to a synchronous-only error-reporting contract unless those listeners handle their own asynchronous failures. Mastering Promises: Chaining, Error Flow & Patterns owns returned promise chains.

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const trace = [];
const failure = new Error("broken subscriber");
bus.on("job", () => { trace.push("A"); throw failure; });
bus.on("job", () => trace.push("B"));
try { bus.emit("job"); } catch (error) { console.log(error === failure); }
console.log(trace.join(","));

// ✅ Expected output:
// true
// A

The publisher may already have changed state before emission, and earlier subscribers may have performed effects. Propagating an error does not undo them. Priority lists, wildcard routing, persistence and transactions are additional designs, not properties supplied by an event name.

Avoid inheriting special meanings from a familiar name

function createEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        record.listener.apply(undefined, args);
      }
      return delivered;
    }
  };
}
const bus = createEmitter();
const trace = [];
bus.on("__proto__", value => trace.push(value));
bus.on("constructor", value => trace.push(value));
bus.emit("__proto__", "A");
bus.emit("constructor", "B");
console.log(trace.join(","), bus.emit("error", new Error("ordinary payload")));

// ✅ Expected output:
// A,B 0

Node EventEmitter gives an unhandled error event special behaviour; this custom emitter does not. Colon-separated names are a naming convention here, not a wildcard feature. DOM EventTarget has its own listener and exception rules. Read the specific API rather than transferring semantics between them.

Guided exercise: consume a one-time callback before recursion

Complete the literal hints. Make the callback inactive before invoking it, then check that a nested delivery cannot call it again.

let active = true;
let calls = 0;
function emitOnce() {
  if (!___) return; // 👉 replace ___ with active
  active = ___; // 👉 replace ___ with false
  listener();
}
function listener() { calls++; emitOnce(); }
emitOnce();
emitOnce();
console.log(___); // 👉 replace ___ with calls

// ✅ Expected output:
// 1

Independent brief: report every synchronous subscriber failure

Build createReportingEmitter with the same registration, duplicate, snapshot, removal and once rules as the earlier emitter. Change emit to continue after synchronous subscriber failures and return an object with delivered and errors. Count every attempted invocation, retain exact thrown values in order (including undefined or false), and let a once listener remain consumed when it throws. Do not interpret returned promises or aggregate nested emission counts into the outer result.

Check two independent duplicate registrations, repeated unsubscription, adding and removing during delivery, a recursively emitting once listener, multiple failures with an ordinary listener between them, exact reason identity and an empty event. This emitter is for trusted synchronous listener contracts; it cannot roll back effects or catch future asynchronous failures.

function createReportingEmitter() {
  const events = new Map();
  function add(name, listener, once) {
    if (typeof name !== "string" || name === "") throw new TypeError("event name must be a non-empty string");
    if (typeof listener !== "function") throw new TypeError("listener must be a function");
    const record = { listener, once, active: true, remove: null };
    let bucket = events.get(name);
    if (!bucket) { bucket = new Set(); events.set(name, bucket); }
    function remove() {
      if (!record.active) return;
      record.active = false;
      bucket.delete(record);
      if (bucket.size === 0 && events.get(name) === bucket) events.delete(name);
    }
    record.remove = remove;
    bucket.add(record);
    return remove;
  }
  return {
    on(name, listener) { return add(name, listener, false); },
    once(name, listener) { return add(name, listener, true); },
    emit(name, ...args) {
      const snapshot = [...(events.get(name) ?? [])];
      let delivered = 0;
      const errors = [];
      for (const record of snapshot) {
        if (!record.active) continue;
        if (record.once) record.remove();
        delivered++;
        try { record.listener.apply(undefined, args); } catch (error) { errors.push(error); }
      }
      return { delivered, errors };
    }
  };
}
const bus = createReportingEmitter();
const trace = [];
const failure = { message: "first failure" };
bus.on("job", () => { trace.push("A"); throw failure; });
const remove = bus.on("job", () => trace.push("B"));
bus.once("job", () => { trace.push("C"); throw undefined; });
bus.on("job", () => trace.push("D"));
const first = bus.emit("job");
console.log(first.delivered, first.errors.length, first.errors[0] === failure, first.errors[1] === undefined);
console.log(trace.join(","));
remove(); remove(); trace.length = 0;
const second = bus.emit("job");
console.log(second.delivered, second.errors.length, trace.join(","));
console.log(bus.emit("missing").delivered);
const recursive = createReportingEmitter();
let onceCalls = 0;
recursive.once("ready", () => { onceCalls++; recursive.emit("ready"); });
recursive.emit("ready");
console.log(onceCalls);
const mutation = createReportingEmitter();
const visits = [];
let removeLater, added = false;
mutation.on("tick", () => {
  visits.push("first");
  removeLater();
  if (!added) { added = true; mutation.on("tick", () => visits.push("new")); }
});
removeLater = mutation.on("tick", () => visits.push("removed"));
mutation.emit("tick"); mutation.emit("tick");
console.log(visits.join(","));
const duplicates = createReportingEmitter();
let count = 0;
const callback = () => count++;
const off = duplicates.on("x", callback);
duplicates.on("x", callback);
duplicates.emit("x"); off(); duplicates.emit("x");
console.log(count);

// ✅ Expected output:
// 4 2 true true
// A,B,C,D
// 2 1 A,D
// 0
// 1
// first,first,new
// 3

Reference notes

The official Node events documentation explains that its listeners run synchronously and documents its own error-event and removal rules. This lesson’s explicitly stated custom contract is intentionally checked on its own terms. It introduces no automatic scheduling, security boundary or delivery guarantee across processes.

Practice quiz

What does this complete program print? const listeners=[()=>console.log("listener")];console.log("before");for(const listener of listeners)listener();console.log("after");

  • before listener after
  • before after listener
  • listener before after
  • before after

Answer: before listener after. Ordinary listener calls finish synchronously before the loop continues.

What does this complete program print? let active=true,calls=0;function emit(){if(!active)return;active=false;calls++;emit()}emit();emit();console.log(calls);

  • 0
  • 1
  • 2
  • 3

Answer: 1. Deactivation occurs before recursive delivery.

What does this complete program print? const f=()=>{};const registrations=new Set([{listener:f},{listener:f}]);console.log(registrations.size);

  • 0
  • 1
  • 2
  • TypeError

Answer: 2. Distinct registration records allow the same function twice.

What does this complete program print? const list=[()=>console.log("A")];const snapshot=[...list];list.push(()=>console.log("B"));for(const fn of snapshot)fn();

  • A B
  • B
  • B A
  • A

Answer: A. The previously copied list contains only its original candidate.

What does this complete program print? const payload={value:1};const listeners=[x=>{x.value=2},x=>console.log(x.value)];for(const fn of listeners)fn(payload);console.log(payload.value);

  • 2 2
  • 1 1
  • 2 1
  • 1 2

Answer: 2 2. Both callbacks and the caller share one payload object.

What does this complete program print? const errors=[];for(const fn of [()=>{throw false},()=>{throw undefined}]){try{fn()}catch(error){errors.push(error)}}console.log(errors.length,errors[0]===false,errors[1]===undefined);

  • 0 false false
  • 2 true true
  • 1 true false
  • 2 false false

Answer: 2 true true. Thrown values do not have to be Error objects or truthy.

What does this complete program print? const listeners=[()=>{throw new Error("stop")},()=>console.log("later")];try{for(const fn of listeners)fn()}catch(error){console.log(error.message)}

  • later stop
  • later
  • stop
  • undefined

Answer: stop. Without a per-listener catch, the first throw exits delivery.

What does this complete program print? const records=[{active:true},{active:true}];const snapshot=[...records];records[1].active=false;console.log(snapshot.filter(record=>record.active).length);

  • 0
  • 2
  • undefined
  • 1

Answer: 1. The snapshot copies the array while retaining each registration record reference.

Continue this course

Related lessons