EventEmitter in TypeScript - events, generics and decoupling

EventEmitter is one of those concepts that might initially seem simpler than they actually are.

TypeScript

JavaScript

EventDrivenArchitecture

Decoupling

SoftwareArchitecture

Frontend

EventEmitter in JavaScript and TypeScript

We have:

  • events,
  • channels,
  • listeners,
  • subscriptions,
  • emitting events,
  • unsubscribe.

But the core idea is very simple:

One part of an application says, "Something happened", and other parts can decide whether they want to know about it.

In TypeScript, we can also make sure that the data passed along with an event is properly typed.

Let's start with JavaScript

Imagine an e-commerce application.

After an order is created, we want to:

  • display a notification,
  • send an email,
  • update analytics.

Without an EventEmitter, we could do something like this:

function createOrder(order) {
  saveOrder(order);
  showNotification(order);
  sendEmail(order);
  updateAnalytics(order);
}

The problem is that createOrder() needs to know about everything that should happen after an order is created.

Instead, we can simply say:

ee.trigger("orderCreated", order);

And other parts of the application can subscribe to this event:

ee.on("orderCreated", showNotification);
ee.on("orderCreated", sendEmail);
ee.on("orderCreated", updateAnalytics);

This way, createOrder() doesn't need to know who is listening.

This is an example of decoupling, which means reducing dependencies between different parts of an application.

EventEmitter as a publish-subscribe pattern

We can think of an EventEmitter as a simple publish-subscribe mechanism.

We have:

Publisher
   │
   │ trigger("orderCreated", order)
   ↓
EventEmitter
   │
   ├──→ Listener 1
   ├──→ Listener 2
   └──→ Listener 3
  • One part of the system publishes information.
  • Other parts of the system can subscribe to it.

Basic operations

In our exercise, the API looks like this:

ee.on(CHANNEL, LISTENER);
ee.trigger(CHANNEL, ITEM);
ee.off(CHANNEL, LISTENER);

We can remember it this way:

on()      → subscribe
trigger() → emit
off()     → unsubscribe

What is a listener?

A listener is simply a function.

We can define its type:

type Listener<T = unknown> = (item: T) => void;

Let's break it down:

(item: T) => void

This means:

A function that takes one argument of type T and returns nothing.

For example:

const listener: Listener<string> = (message) => {
  console.log(message);
};

TypeScript knows that:

message

has the type:

string

So we can do this:

const listener: Listener<string> = (message) => {
  console.log(message.toUpperCase());
};

But:

message.toFixed();

will cause a TypeScript error because string doesn't have a toFixed() method.

Why do we use the generic T here?

This:

type Listener<T = unknown> = (item: T) => void;

is a generic function type.

This means we can have:

Listener<string>

or:

Listener<number>

or:

Listener<User>


For example:

type User = {
  id: number;
  name: string;
};

const listener: Listener<User> = (user) => {
  console.log(user.name);
};

TypeScript makes sure that the listener receives a User object.

How do we store listeners?

In our exercise, we have multiple channels:

"orderCreated"
"userLoggedIn"
"paymentCompleted"

Each channel can have multiple listeners.

So we need:

Map<string, Listener[]>

A good solution would be a Map.

We can think of it as:

A Map where the key is a string and the value is an array of listeners.

In other words:

"orderCreated" → [listener1, listener2]
"userLoggedIn" → [listener3]
"paymentComplete" → [listener4, listener5]

In code:

class EventEmitter {
  private channels = new Map<string, Listener[]>();
}

This is a very important part of the exercise.

Not:

Map<string, Listener>

because that would allow us to store only one listener per channel.

We need:

Map<string, Listener[]>

because:

One channel → multiple listeners.

Implementing on()

We want to be able to do this:

ee.on("orderCreated", listener);

First, we check whether the channel already exists.

on(channel: string, listener: Listener) {
  let listeners = this.channels.get(channel);

  if (!listeners) {
    listeners = [];
    this.channels.set(channel, listeners);
  }

  listeners.push(listener);
}

If "orderCreated" doesn't exist yet, we create an empty array:

[]

Then:

listeners.push(listener);
adds the function to the array.

After calling:

ee.on("orderCreated", listener1);
ee.on("orderCreated", listener2);

we have two listeners registered for the same channel.

"orderCreated"
       ↓
[listener1, listener2]

trigger() — emitting an event

Now:

ee.trigger("orderCreated", order);

should call all listeners registered for this channel.

trigger(channel: string, item: unknown) {
  const listeners = this.channels.get(channel);

  listeners?.forEach(listener => {
    listener(item);
  });
}

If we have:

"orderCreated"
       ↓
[listener1, listener2, listener3]

then:

trigger("orderCreated", order);

will execute:

listener1(order);
listener2(order);
listener3(order);

What does "synchronous" mean?

The exercise mentions:

Synchronous listener invoking.

This means that a listener should be called immediately.

Not: setTimeout(() => listener(item));

Not: Promise.resolve().then(() => listener(item));

Just a direct function call:

listener(item);

For example, if we write:

console.log("before");

ee.trigger("orderCreated", order);

console.log("after");


the output will be:

before
listener
after

off() — unsubscribe

Let's say we have:

ee.on("orderCreated", sendEmail);
ee.on("orderCreated", updateAnalytics);

Now we want to remove one listener.

"orderCreated"
       ↓
[sendEmail, updateAnalytics]

After calling:

ee.off("orderCreated", sendEmail);

only updateAnalytics should remain subscribed.

"orderCreated"
       ↓
[updateAnalytics]

We can use filter() to achieve this.

off(channel: string, listener: Listener) {
  const listeners = this.channels.get(channel);

  if (!listeners) return;

  const remainingListeners = listeners.filter(
    currentListener => currentListener !== listener
  );

  this.channels.set(channel, remainingListeners);
}

Now TypeScript gets really interesting

The previous version works, but:

trigger(channel: string, item: unknown)
doesn't give us much type safety.

TypeScript only knows that:

item is something unknown.

We can do better.

Imagine that we have specific event types:

type Order = {
  id: number;
  product: string;
};

type User = {
  id: number;
  name: string;
};

We want:

orderCreated → Order
userLoggedIn → User

We can define an event map:

type Events = {
  orderCreated: Order;
  userLoggedIn: User;
};

Now Events describes our event system:

event payload
────────────────────────────
orderCreated Order
userLoggedIn User

And we can create a typed EventEmitter.

A typed EventEmitter

type Listener<T> = (item: T) => void;
class TypedEventEmitter<Events extends Record<string, unknown>> {
  private channels = new Map<
    keyof Events,
    Listener<any>[]
  >();

  on<K extends keyof Events>(
    channel: K,
    listener: Listener<Events[K]>
  ) {
    let listeners = this.channels.get(channel);

    if (!listeners) {
      listeners = [];
      this.channels.set(channel, listeners);
    }

    listeners.push(listener);
  }

  trigger<K extends keyof Events>(
    channel: K,
    item: Events[K]
  ) {
    const listeners = this.channels.get(channel);

    listeners?.forEach(listener => {
      listener(item);
    });
  }

  off<K extends keyof Events>(
    channel: K,
    listener: Listener<Events[K]>
  ) {
    const listeners = this.channels.get(channel);

    if (!listeners) return;

    this.channels.set(
      channel,
      listeners.filter(
        currentListener => currentListener !== listener
      )
    );
  }
}

Now we can create:

const ee = new TypedEventEmitter<Events>();

TypeScript now knows which events are available and what data they carry.

TypeScript keeps track of the data

We can do::

ee.on("orderCreated", (order) => {
  console.log(order.id);
  console.log(order.product);
});

TypeScript knows that:

order: Order

because:

Events["orderCreated"]

is:

Order

So we can safely access:

order.id
order.product

Similarly:

ee.on("userLoggedIn", (user) => {
  console.log(user.name);
});

Here:

user: User

TypeScript catches mistakes

This is where things get really useful.

ee.trigger("orderCreated", {
  id: 123,
  product: "Beer"
});

This is valid.
But:

ee.trigger("orderCreated", {
  id: 123,
  name: "Agnieszka"
});

should produce a TypeScript error because orderCreated expects an Order, not a User.

Similarly:

ee.on("userLoggedIn", (user) => {
  console.log(user.product);
});


is an error because User doesn't have a product property.

This is the real power of TypeScript

An EventEmitter itself is a runtime mechanism.

JavaScript only knows:

event → dane → listener

TypeScript, however, can tell us:

"orderCreated" → Order
"userLoggedIn" → User
"paymentCompleted" → Payment

and enforce this relationship while we are writing code.

This is much safer than:

trigger(channel: string, item: unknown)

because with any, we could accidentally pass the wrong data without getting a TypeScript error.

Let's see it in the terminal

Example program:

type Order = {
  id: number;
  product: string;
};

type User = {
  id: number;
  name: string;
};

type Events = {
  orderCreated: Order;
  userLoggedIn: User;
};

const ee = new TypedEventEmitter<Events>();

ee.on("orderCreated", (order) => {
  console.log("🛒 Order created:", order.id);
  console.log("Product:", order.product);
});

ee.on("userLoggedIn", (user) => {
  console.log("👤 User logged in:", user.name);
});

ee.trigger("orderCreated", {
  id: 123,
  product: "Beer"
});

ee.trigger("userLoggedIn", {
  id: 1,
  name: "Agnieszka"
});

Terminal:

🛒 Order created: 123
Product: Beer

👤 User logged in: Agnieszka

And if we pass the wrong data:

ee.trigger("orderCreated", {
  id: 1,
  name: "Agnieszka"
});

TypeScript will report an error before we even run the program.

What should we remember from this exercise?

This exercise combines several important TypeScript concepts.

type Listener<T>

type Listener<T> = (item: T) => void;

A generic function type.

Map

Map<string, Listener[]>

This represents:

channel → listeners

Generics

Listener<T>
Generics allow us to specify the type of data passed to a listener.

keyof

In the typed version::

K extends keyof Events

means:

K can only be one of the keys defined in our event map.

For example, if we have:

type Events = {
orderCreated: Order;
userLoggedIn: User;
};

then:

keyof Events

then:

"orderCreated" | "userLoggedIn"

Indexed access type

This::

Events[K]

means:

"What data type is assigned to event K?"

For:

K = "orderCreated"

we get:

Events["orderCreated"] // Order

For:

K = "userLoggedIn"

we get:

Events["userLoggedIn"] // User

The big picture

EventEmitter without type safety
We can emit events, register listeners and pass data, but TypeScript doesn't know which data belongs to which event.

event name
    ↓
listeners
    ↓
some data

EventEmitter with TypeScript

We can define the relationship between events and their payloads, and TypeScript checks that everything matches.

"orderCreated"
      ↓
    Order
      ↓
Listener<Order>

"userLoggedIn"
      ↓
     User
      ↓
Listener<User>

In other words, TypeScript allows us to say:

"I don't just know that an event happened. I also know exactly what data this particular event carries."

And this is where a simple JavaScript pattern starts demonstrating the practical value of generics, keyof, and indexed access types.

With TypeScript, we can make sure that the data passed along with each event is correctly typed.