Event Emitter middleware for Hono

Minimal, lightweight and edge compatible Event Emitter middleware for Hono.

Table of Contents

1. Introduction
2. Installation
3. Usage Examples
   • 1. As Hono middleware
   • 2. Standalone
4. API Reference
   • emitter
   • createEmitter
   • defineHandler
   • defineHandlers
   • Emitter API Documentation
5. Types

Introduction

This library provides an event emitter middleware for Hono, allowing you to easily implement and manage event-driven architectures in your Hono applications. It enables event driven logic flow, allowing you to decouple your code and make it more modular and maintainable.

Inspired by event emitter concept in other frameworks such as Adonis.js, Nest.js, Hapi.js, Meteor and others.

See FAQ bellow for some common questions.

For more usage examples, see the tests or my Hono REST API starter kit

Installation

npm install @hono/event-emitter
# or
yarn add @hono/event-emitter
# or
pnpm add @hono/event-emitter
# or
bun install @hono/event-emitter

Usage

There are 2 ways you can use this with Hono:

1. As Hono middleware

// event-handlers.js

// Define event handlers
export const handlers = {
  'user:created': [
    (c, payload) => {} // c is current Context, payload is whatever the emit method passes
  ],
  'user:deleted': [
    async (c, payload) => {} // c is current Context, payload is whatever the emit method passes
  ],
  'foo': [
    (c, payload) => {} // c is current Context, payload is whatever the emit method passes
  ],
}

// You can also define single event handler as named function
// export const fooHandler = (c, payload) => {
//   // c is current Context, payload is whatever the emit method passes
//   // ...
//   console.log('New foo created:', payload)
// }

// app.js

import { emitter } from '@hono/event-emitter'
import { handlers, fooHandler } from './event-handlers'
import { Hono } from 'hono'

// Initialize the app with emitter type
const app = new Hono()

// Register the emitter middleware and provide it with the handlers
app.use(emitter(handlers))

// You can also add event listener inside middleware or route handler, but please only use named functions to prevent duplicates and memory leaks!
// app.use((c, next) => {
//   c.get('emitter').on('foo', fooHandler)
//   return next()
// })

// Routes
app.post('/users', (c) => {
  // ...
  // Emit event and pass current context plus the payload
  c.get('emitter').emit(c, 'user:created', user)
  // ...
})

app.delete('/users/:id', async (c) => {
  // ...
  // Emit event asynchronpusly and pass current context plus the payload
  await c.get('emitter').emitAsync(c, 'user:deleted', id)
  // ...
})

export default app

The emitter is available in the context as emitter key.

As seen above (commented out) you can also subscribe to events inside middlewares or route handlers, but because middlewares are called on every request, you can only use named functions to prevent duplicates or memory leaks!

2 Standalone

// events.js

import { createEmitter } from '@hono/event-emitter'

// Define event handlers
export const handlers = {
  'user:created': [
    (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method
  ],
  'user:deleted': [
    async (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method
  ]
}

// Initialize emitter with handlers
const ee = createEmitter(handlers)

// And you can add more listeners on the fly.
// Here you CAN use anonymous or closure function because .on() is only called once.
// ee.on('foo', async (c, payload) => {
//     console.log('New foo created:', payload)
// })

export default ee

// app.js

import { Hono } from 'hono'
import ee from './events'

// Initialize the app
const app = new Hono()

app.post('/users', async (c) => {
    // ...
    // Emit event and pass current context plus the payload
    ee.emit(c, 'user:created', user)
    // ...
})

app.delete('/users/:id', async (c) => {
    // ...
    // Emit event and pass current context plus the payload
    await ee.emitAsync(c, 'user:deleted', id )
    // ...
})

export default app

Typescript

1. As hono middleware

// types.ts

import type { Emitter } from '@hono/event-emitter'

export type User = {
    id: string,
    title: string,
    role: string
}

export type AvailableEvents = {
    // event key: payload type
    'user:created': User;
    'user:deleted': string;
    'foo': { bar: number };
};

export type Env = {
    Bindings: {};
    Variables: {
        // Define emitter variable type
        emitter: Emitter<AvailableEvents>;
    };
};

// event-handlers.ts

import { defineHandlers } from '@hono/event-emitter'
import { AvailableEvents } from './types'

// Define event handlers
export const handlers = defineHandlers<AvailableEvents>({
  'user:created': [
    (c, user) => {} // c is current Context, payload will be correctly inferred as User
  ],
  'user:deleted': [
    async (c, payload) => {} // c is current Context, payload will be inferred as string
  ]
})

// You can also define single event handler as named function using defineHandler to leverage typings
// export const fooHandler = defineHandler<AvailableEvents, 'foo'>((c, payload) => {
//   // c is current Context, payload will be inferred as { bar: number }
//   // ...
//   console.log('Foo:', payload)
// })

// app.ts

import { emitter, type Emitter, type EventHandlers } from '@hono/event-emitter'
import { handlers, fooHandler } from './event-handlers'
import { Hono } from 'hono'
import { Env } from './types'

// Initialize the app
const app = new Hono<Env>()

// Register the emitter middleware and provide it with the handlers
app.use(emitter(handlers))

// You can also add event listener inside middleware or route handler, but please only use named functions to prevent duplicates and memory leaks!
// app.use((c, next) => {
//   c.get('emitter').on('foo', fooHandler)
//   return next()
// })

// Routes
app.post('/user', async (c) => {
  // ...
  // Emit event and pass current context plus the payload (User type)
  c.get('emitter').emit(c, 'user:created', user)
  // ...
})

app.delete('/user/:id', async (c) => {
  // ...
  // Emit event and pass current context plus the payload (string)
  await c.get('emitter').emitAsync(c, 'user:deleted', id)
  // ...
})

export default app

The emitter is available in the context as emitter key.

As seen above (the commented out 'foo' event) you can also subscribe to events inside middlewares or route handlers, but because middlewares are called on every request, you can only use named functions to prevent duplicates or memory leaks!

2. Standalone:

// types.ts

type User = {
  id: string,
  title: string,
  role: string
}

type AvailableEvents = {
  // event key: payload type
  'user:created': User;
  'user:updated': User;
  'user:deleted': string,
  'foo': { bar: number };
}

// events.ts

import { createEmitter, defineHandlers, type Emitter, type EventHandlers } from '@hono/event-emitter'
import { AvailableEvents } from './types'

// Define event handlers
export const handlers = defineHandlers<AvailableEvents>({
  'user:created': [
    (c, user) => {} // c is current Context, payload will be correctly inferred as User
  ],
  'user:deleted': [
    async (c, payload) => {} // c is current Context, payload will be inferred as string
  ]
})

// You can also define single event handler using defineHandler to leverage typings
// export const fooHandler = defineHandler<AvailableEvents, 'foo'>((c, payload) => {})

// Initialize emitter with handlers
const ee = createEmitter(handlers)

// ee.on('foo', fooHandler)

// And you can add more listeners on the fly.
// Here you can use anonymous or closure function because .on() is only called once.
ee.on('foo', async (c, payload) => { // Payload will be correctly inferred as User
    console.log('User updated:', payload)
})

export default ee

// app.ts

import ee from './events'
import { Hono } from 'hono'

// Initialize the app
const app = new Hono()

app.post('/user', async (c) => {
  // ...
  // Emit event and pass current context plus the payload (User)
  ee.emit(c, 'user:created', user)
  // ...
})

app.delete('/user/:id', async (c) => {
  // ...
  // Emit event and pass current context plus the payload (string)
  ee.emit(c, 'user:deleted', id )
  // ...
})

export default app

API Reference

emitter

Creates a Hono middleware that adds an event emitter to the context.

function emitter<EPMap extends EventPayloadMap>(
    eventHandlers?: EventHandlers<EPMap>,
    options?: EventEmitterOptions
): MiddlewareHandler

Parameters

• eventHandlers - (optional): An object containing initial event handlers. Each key is event name and value is array of event handlers. Use defineHandlers function to create fully typed event handlers.
• options - (optional): An object containing options for the emitter. Currently, the only option is maxHandlers, which is the maximum number of handlers that can be added to an event. The default is 10.

Returns

A Hono middleware function that adds an Emitter instance to the context under the key 'emitter'.

Example

app.use(emitter(eventHandlers));

createEmitter

Creates new instance of event emitter with provided handlers. This is usefull when you want to use the emitter as standalone feature instead of Hono middleware.

function createEmitter<EPMap extends EventPayloadMap>(
    eventHandlers?: EventHandlers<EPMap>,
    options?: EventEmitterOptions
): Emitter<EPMap>

Parameters

• eventHandlers - (optional): An object containing initial event handlers. Each key is event name and value is array of event handlers.
• options - (optional): An object containing options for the emitter. Currently, the only option is maxHandlers, which is the maximum number of handlers that can be added to an event. The default is 10.

Returns

An Emitter instance:

Example

const ee = createEmitter(eventHandlers);

defineHandler

A utility function to define a typed event handler.

function defineHandler<EPMap extends EventPayloadMap, Key extends keyof EPMap, E extends Env = Env>(
    handler: EventHandler<EPMap[Key], E>,
): EventHandler<EPMap[Key], E>

Parameters

• handler: The event handler function to be defined.

Type parameters

• EPMap: The available event key to payload map i.e.: type AvailableEvents = { 'user:created': { name: string } };.
• Key: The key of the event type.
• E: (optional) - The Hono environment, so that the context within the handler has the right info.

Returns

The same event handler function with proper type inference.

Example

type AvailableEvents = {
    'user:created': { name: string };
};

const handler = defineHandler<AvailableEvents, 'user:created'>((c, payload) => {
    console.log('New user created:', payload)
})

defineHandlers

A utility function to define multiple typed event handlers.

function defineHandlers<EPMap extends EventPayloadMap, E extends Env = Env>(
    handlers: { [K in keyof EPMap]?: EventHandler<EPMap[K], E>[] },
): { [K in keyof EPMap]?: EventHandler<EPMap[K], E>[] }

Parameters

• handlers: An object containing event handlers for multiple event types/keys.

Type parameters

• EPMap: The available event key to payload map i.e.: type AvailableEvents = { 'user:created': { name: string } };.
• E: (optional) - The Hono environment, so that the context within the handler has the right info.

Returns

The same handlers object with proper type inference.

Example

type AvailableEvents = {
    'user:created': { name: string };
};

const handlers = defineHandlers<AvailableEvents>({
    'user:created': [
        (c, payload) => {
            console.log('New user created:', pyload)
        }
    ]
})

Emitter instance methods

The Emitter interface provides methods for managing and triggering events. Here's a detailed look at each method:

on

Adds an event handler for the specified event key.

Signature

function on<Key extends keyof EventPayloadMap>(
        key: Key,
        handler: EventHandler<EventPayloadMap[Key]>
): void

Parameters

• key: The event key to listen for. Must be a key of EventHandlerPayloads.
• handler: The function to be called when the event is emitted. If using within a Hono middleware or request handler, do not use anonymous or closure functions! It should accept two parameters:
  • c: The current Hono context object.
  • payload: The payload passed when the event is emitted. The type of the payload is inferred from the EventHandlerPayloads type.

Returns

void

Example

Using outside the Hono middleware or request handler:

type AvailableEvents = {
    'user:created': { name: string };
};
const ee = createEmitter<AvailableEvents>();

// If adding event handler outside of Hono middleware or request handler, you can use both, named or anonymous function.
ee.on('user:created', (c, user) => {
    console.log('New user created:', user)
})

Using within Hono middleware or request handler:

type AvailableEvents = {
    'user:created': { name: string };
};

// Define event handler as named function, outside of the Hono middleware or request handler to prevent duplicates/memory leaks
const namedHandler = defineHandler<AvailableEvents, 'user:created'>((c, user) => {
   console.log('New user created:', user)
})

app.use(emitter<AvailableEvents>());

app.use((c, next) => {
    c.get('emitter').on('user:created', namedHandler)
    return next()
})

off

Removes an event handler for the specified event key.

Signature

function off<Key extends keyof EventPayloadMap>(
    key: Key,
    handler?: EventHandler<EventPayloadMap[Key]>
): void

Parameters

• key: The event key to remove the handler from. Must be a key of EventPayloadMap.
• handler (optional): The specific handler function to remove. If not provided, all handlers for the given key will be removed.

Returns

void

Example

type AvailableEvents = {
    'user:created': { name: string };
};

const ee = createEmitter<AvailableEvents>();

const logUser = defineHandler<AvailableEvents, 'user:created'>((c, user) => {
    console.log(`User: ${user.name}`);
});

ee.on('user:created', logUser);

// Later, to remove the specific handler:
ee.off('user:created', logUser);

// Or to remove all handlers for 'user:created':
ee.off('user:created');

emit

Synchronously emits an event with the specified key and payload.

Signature

emit<Key extends keyof EventPayloadMap>(
    c: Context,
    key: Key,
    payload: EventPayloadMap[Key]
): void

Parameters

• c: The current Hono context object.
• key: The event key to emit. Must be a key of EventPayloadMap.
• payload: The payload to pass to the event handlers. The type of the payload is inferred from the EventPayloadMap type.

Returns

void

Example

app.post('/users', (c) => {
    const user = { name: 'Alice' };
    c.get('emitter').emit(c, 'user:created', user);
});

emitAsync

Asynchronously emits an event with the specified key and payload.

Signature

emitAsync<Key extends keyof EventPayloadMap>(
    c: Context,
    key: Key,
    payload: EventPayloadMap[Key],
    options?: EmitAsyncOptions
): Promise<void>

Parameters

• c: The current Hono context object.
• key: The event key to emit. Must be a key of EventPayloadMap.
• payload: The payload to pass to the event handlers. The type of the payload is inferred from the EventPayloadMap type.
• options (optional): An object containing options for the asynchronous emission. Currently, the only option is mode, which can be 'concurrent' (default) or 'sequencial'.
  • The 'concurrent' mode will call all handlers concurrently (at the same time) and resolve or reject (with aggregated errors) after all handlers settle.
  • The 'sequencial' mode will call handlers one by one and resolve when all handlers are done or reject when the first error is thrown, not executing rest of the handlers.

Returns

Promise<void>

Example

app.post('/users', async (c) => {
    const user = { name: 'Alice' };
    await c.get('emitter').emitAsync(c, 'user:created', user);
    // await c.get('emitter').emitAsync(c, 'user:created', user, { mode: 'sequencial' });
});

Types

EventKey

A string literal type representing an event key.

type EventKey = string | symbol

EventHandler

A function type that handles an event.

type EventHandler<T, E extends Env = Env> = (c: Context<E>, payload: T) => void | Promise<void>

EventHandlers

An object type containing event handlers for multiple event types/keys.

type EventHandlers<T, E extends Env = Env> = { [K in keyof T]?: EventHandler<T[K], E>[] }

EventPayloadMap

An object type containing event keys and their corresponding payload types.

type EventPayloadMap = Record<EventKey, any>

EventEmitterOptions

An object type containing options for the Emitter class.

type EventEmitterOptions = { maxHandlers?: number };

EmitAsyncOptions

An object type containing options for the emitAsync method.

type EmitAsyncOptions = {
    mode?: 'concurrent' | 'sequencial'
}

Emitter

An interface representing an event emitter.

interface Emitter<EventPayloadMap> {
   on<Key extends keyof EventPayloadMap>(key: Key, handler: EventHandler<EventPayloadMap[Key]>): void;
   off<Key extends keyof EventPayloadMap>(key: Key, handler?: EventHandler<EventPayloadMap[Key]>): void;
   emit<Key extends keyof EventPayloadMap>(c: Context, key: Key, payload: EventPayloadMap[Key]): void;
   emitAsync<Key extends keyof EventPayloadMap>(
       c: Context,
       key: Key,
       payload: EventPayloadMap[Key],
       options?: EmitAsyncOptions
   ): Promise<void>;
}

For more usage examples, see the tests or Hono REST API starter kit

FAQ

What the heck is event emitter and why should I use it?

Event emitter is a pattern that allows you to decouple your code and make it more modular and maintainable. It's a way to implement the observer pattern in your application. It's especially useful in larger projects or projects with a lot of interactions between features. Just imagine you have a user registration feature, and you want to send a welcome email after the user is created. You can do this by emitting an event user:created and then listen to this event in another part of your application (e.g. email service).

How is this different to the built-in EventEmitter in Node.js?

The build-in EventEmitter has huge API surface, weak TypeScript support and does only synchronous event emitting. Hono's event emitter is designed to be minimal, lightweight, edge compatible and fully typed. Additionally, it supports async event handlers.

Is there a way to define event handlers with types?

Yes, you can use defineHandlers and defineHandler functions to define event handlers with types. This way you can leverage TypeScript's type inference and get better type checking.

Does it support async event handlers?

Yes, it does. You can use async functions as event handlers and emit the events using emitAsync method.

What happens if I emit an event that has no handlers?

Nothing. The event will be emitted, but no handlers will be called.

Using emitAsync function, what happens if one or more of the handlers reject?

• If using { mode = 'concurrent' } in the options (which is the default), it will call all handlers concurrently (at the same time) and resolve or reject (with aggregated errors) after all handlers settle.
• If using { mode = 'sequencial' } in the options, it will call handlers one by one and resolve when all handlers are done or reject when the first error is thrown, not executing rest of the handlers.

Is it request scoped?

No, by design it's not request scoped. The same Emitter instance is shared across all requests. This aproach prevents memory leaks (especially when using closures or dealing with large data structures within the handlers) and additional strain on Javascript garbage collector.

Why can't I use anonymous functions or closures as event handlers when adding them inside of middleware?

This is because middleware or request handlers run repeatedly on every request, and because anonymous functions are created as new unique object in memory every time, you would be instructing the event emitter to add new handler for same key every time the request/middleware runs. Since they are each different objects in memory they can't be checked for equality and would result in memory leaks and duplicate handlers. You should use named functions if you really want to use the on() method inside of middleware or request handler.

Author

David Havl https://github.com/DavidHavl

License

MIT