From 0b6d821c110ff6ac71846cdd7ffad6e36050b4e7 Mon Sep 17 00:00:00 2001 From: David Havl Date: Tue, 6 Aug 2024 14:05:35 +0200 Subject: [PATCH] feat(event-emitter): Enable invoking asynchronous handlers (#649) * Add new emitAsync method, memory leak prevention and significantly improve README.md * Adjust ci yarn install command * Commit yarn.lock * Run changeset * Revert ci yarn install command * Move context parameter to the first position in the `emit` method * Fix test --- .changeset/tender-knives-compare.md | 12 + packages/event-emitter/README.md | 526 +++++++++++++++--- packages/event-emitter/package.json | 7 +- packages/event-emitter/src/index.test.ts | 671 +++++++++++++++-------- packages/event-emitter/src/index.ts | 216 ++++++-- yarn.lock | 4 +- 6 files changed, 1066 insertions(+), 370 deletions(-) create mode 100644 .changeset/tender-knives-compare.md diff --git a/.changeset/tender-knives-compare.md b/.changeset/tender-knives-compare.md new file mode 100644 index 00000000..16a3c921 --- /dev/null +++ b/.changeset/tender-knives-compare.md @@ -0,0 +1,12 @@ +--- +'@hono/event-emitter': major +--- + +### Added: +- New `emitAsync` method to the EventEmitter to enable invoking asynchronous handlers. +- Added prevention for potential memory leak when adding handlers inside of middleware via `on` method. +- Introduced new option of EventEmitter `maxHandlers` that limits number of handlers that can be added to a single event. +- Significantly improved documentation. + +### Changed: +- Moved context parameter to the first position in the `emit` method. diff --git a/packages/event-emitter/README.md b/packages/event-emitter/README.md index 38b1ff2d..e316d635 100644 --- a/packages/event-emitter/README.md +++ b/packages/event-emitter/README.md @@ -1,12 +1,32 @@ # Event Emitter middleware for Hono +### Minimal, lightweight and edge compatible Event Emitter middleware for [Hono](https://github.com/honojs/hono). -Minimal, lightweight and edge compatible Event Emitter middleware for [Hono](https://github.com/honojs/hono). +## Table of Contents +1. [Introduction](#introduction) +2. [Installation](#installation) +3. [Usage Examples](#usage-examples) + - [1. As Hono middleware](#1-as-hono-middleware) + - [2. Standalone](#2-standalone) +4. [API Reference](#api-reference) + - [emitter](#emitter) + - [createEmitter](#createemitter) + - [defineHandler](#definehandler) + - [defineHandlers](#definehandlers) + - [Emitter API Documentation](#emitter) +5. [Types](#types) -It enables event driven logic flow in hono applications (essential in larger projects or projects with a lot of interactions between features). +## 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](https://docs.adonisjs.com/guides/emitter), [Nest.js](https://docs.nestjs.com/techniques/events), [Hapi.js](https://github.com/hapijs/podium), [Laravel](https://laravel.com/docs/11.x/events), [Sails.js](https://sailsjs.com/documentation/concepts/extending-sails/hooks/events), [Meteor](https://github.com/Meteor-Community-Packages/Meteor-EventEmitter) and others. +as [Adonis.js](https://docs.adonisjs.com/guides/emitter), [Nest.js](https://docs.nestjs.com/techniques/events), [Hapi.js](https://github.com/hapijs/podium), [Meteor](https://github.com/Meteor-Community-Packages/Meteor-EventEmitter) and others. + +See [FAQ](#faq) bellow for some common questions. +For more usage examples, see the [tests](src/index.test.ts) or my [Hono REST API starter kit](https://github.com/DavidHavl/hono-rest-api-starter) ## Installation @@ -20,7 +40,6 @@ pnpm add @hono/event-emitter bun install @hono/event-emitter ``` - ## Usage #### There are 2 ways you can use this with Hono: @@ -33,21 +52,21 @@ bun install @hono/event-emitter // Define event handlers export const handlers = { 'user:created': [ - (c, payload) => {} // c is current Context, payload will be correctly inferred as User + (c, payload) => {} // c is current Context, payload is whatever the emit method passes ], 'user:deleted': [ - (c, payload) => {} // c is current Context, payload will be inferred as string + async (c, payload) => {} // c is current Context, payload is whatever the emit method passes ], 'foo': [ - (c, payload) => {} // c is current Context, payload will be inferred as { bar: number } - ] + (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 userCreatedHandler = (c, user) => { -// // c is current Context, payload will be inferred as User +// export const fooHandler = (c, payload) => { +// // c is current Context, payload is whatever the emit method passes // // ... -// console.log('New user created:', user) +// console.log('New foo created:', payload) // } ``` @@ -56,42 +75,43 @@ export const handlers = { // app.js import { emitter } from '@hono/event-emitter' -import { handlers, userCreatedHandler } from './event-handlers' +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)) +app.use(emitter(handlers)) -// You can also setup "named function" as event listener inside middleware or route handler +// 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('user:created', userCreatedHandler) +// c.get('emitter').on('foo', fooHandler) // return next() // }) // Routes -app.post('/user', async (c) => { +app.post('/users', (c) => { // ... // Emit event and pass current context plus the payload - c.get('emitter').emit('user:created', c, user) + c.get('emitter').emit(c, 'user:created', user) // ... }) -app.delete('/user/:id', async (c) => { +app.delete('/users/:id', async (c) => { // ... - // Emit event and pass current context plus the payload - c.get('emitter').emit('user:deleted', c, id) + // 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, and handlers (when using named functions) will only be subscribed to events once, even if the middleware is called multiple times. +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 you can only use named functions to prevent duplicates! +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 @@ -107,46 +127,43 @@ export const handlers = { (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method ], 'user:deleted': [ - (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method - ], - 'foo': [ - (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method + async (c, payload) => {} // c is current Context, payload will be whatever you pass to emit method ] } // Initialize emitter with handlers -const emitter = createEmitter(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. -emitter.on('user:updated', (c, payload) => { - console.log('User updated:', payload) -}) +// ee.on('foo', async (c, payload) => { +// console.log('New foo created:', payload) +// }) -export default emitter +export default ee ``` ```js // app.js -import emitter from './events' import { Hono } from 'hono' +import ee from './events' // Initialize the app const app = new Hono() -app.post('/user', async (c) => { +app.post('/users', async (c) => { // ... // Emit event and pass current context plus the payload - emitter.emit('user:created', c, user) + ee.emit(c, 'user:created', user) // ... }) -app.delete('/user/:id', async (c) => { +app.delete('/users/:id', async (c) => { // ... // Emit event and pass current context plus the payload - emitter.emit('user:deleted', c, id ) + await ee.emitAsync(c, 'user:deleted', id ) // ... }) @@ -198,18 +215,15 @@ export const handlers = defineHandlers({ (c, user) => {} // c is current Context, payload will be correctly inferred as User ], 'user:deleted': [ - (c, payload) => {} // c is current Context, payload will be inferred as string - ], - 'foo': [ - (c, payload) => {} // c is current Context, payload will be inferred as { bar: number } + 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 userCreatedHandler = defineHandler((c, user) => { -// // c is current Context, payload will be inferred as User +// export const fooHandler = defineHandler((c, payload) => { +// // c is current Context, payload will be inferred as { bar: number } // // ... -// console.log('New user created:', user) +// console.log('Foo:', payload) // }) ``` @@ -218,7 +232,7 @@ export const handlers = defineHandlers({ // app.ts import { emitter, type Emitter, type EventHandlers } from '@hono/event-emitter' -import { handlers, userCreatedHandler } from './event-handlers' +import { handlers, fooHandler } from './event-handlers' import { Hono } from 'hono' import { Env } from './types' @@ -226,11 +240,11 @@ import { Env } from './types' const app = new Hono() // Register the emitter middleware and provide it with the handlers -app.use('*', emitter(handlers)) +app.use(emitter(handlers)) -// You can also setup "named function" as event listener inside middleware or route handler +// 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('user:created', userCreatedHandler) +// c.get('emitter').on('foo', fooHandler) // return next() // }) @@ -238,20 +252,25 @@ app.use('*', emitter(handlers)) app.post('/user', async (c) => { // ... // Emit event and pass current context plus the payload (User type) - c.get('emitter').emit('user:created', c, user) + c.get('emitter').emit(c, 'user:created', user) // ... }) app.delete('/user/:id', async (c) => { // ... // Emit event and pass current context plus the payload (string) - c.get('emitter').emit('user:deleted', c, id) + 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: ```ts @@ -285,39 +304,32 @@ export const handlers = defineHandlers({ (c, user) => {} // c is current Context, payload will be correctly inferred as User ], 'user:deleted': [ - (c, payload) => {} // c is current Context, payload will be inferred as string - ], - 'foo': [ - (c, payload) => {} // c is current Context, payload will be inferred as { bar: number } + 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 userCreatedHandler = defineHandler((c, payload) => { -// // c is current Context, payload will be correctly inferred as User -// // ... -// console.log('New user created:', payload) -// }) +// export const fooHandler = defineHandler((c, payload) => {}) // Initialize emitter with handlers -const emitter = createEmitter(handlers) +const ee = createEmitter(handlers) -// emitter.on('user:created', userCreatedHandler) +// 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. -emitter.on('user:updated', (c, payload) => { // Payload will be correctly inferred as User +ee.on('foo', async (c, payload) => { // Payload will be correctly inferred as User console.log('User updated:', payload) }) -export default emitter +export default ee ``` ```ts // app.ts -import emitter from './events' +import ee from './events' import { Hono } from 'hono' // Initialize the app @@ -326,33 +338,409 @@ const app = new Hono() app.post('/user', async (c) => { // ... // Emit event and pass current context plus the payload (User) - emitter.emit('user:created', c, user) + ee.emit(c, 'user:created', user) // ... }) app.delete('/user/:id', async (c) => { // ... // Emit event and pass current context plus the payload (string) - emitter.emit('user:deleted', c, id ) + ee.emit(c, 'user:deleted', id ) // ... }) export default app ``` +## API Reference + +### emitter +Creates a Hono middleware that adds an event emitter to the context. + +```ts +function emitter( + eventHandlers?: EventHandlers, + 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 + +```ts +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. + +```ts +function createEmitter( + eventHandlers?: EventHandlers, + options?: EventEmitterOptions +): Emitter +``` + +#### 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 + +```ts +const ee = createEmitter(eventHandlers); +``` + +### defineHandler + +A utility function to define a typed event handler. + +```ts +function defineHandler( + handler: EventHandler, +): EventHandler +``` + +#### 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 + +```ts +type AvailableEvents = { + 'user:created': { name: string }; +}; + +const handler = defineHandler((c, payload) => { + console.log('New user created:', payload) +}) +``` + +### defineHandlers + +A utility function to define multiple typed event handlers. + +```ts +function defineHandlers( + handlers: { [K in keyof EPMap]?: EventHandler[] }, +): { [K in keyof EPMap]?: EventHandler[] } +``` + +#### 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 + +```ts +type AvailableEvents = { + 'user:created': { name: string }; +}; + +const handlers = defineHandlers({ + '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 -### NOTE: +Adds an event handler for the specified event key. -When assigning event handlers inside of middleware or route handlers, don't use anonymous or closure functions, only named functions! -This is because anonymous functions or closures in javascript are created as new object every time and therefore can't be easily checked for equality/duplicates. +#### Signature +```ts +function on( + key: Key, + handler: EventHandler +): 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: +```ts +type AvailableEvents = { + 'user:created': { name: string }; +}; +const ee = createEmitter(); + +// 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: +```ts +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((c, user) => { + console.log('New user created:', user) +}) + +app.use(emitter()); + +app.use((c, next) => { + c.get('emitter').on('user:created', namedHandler) + return next() +}) +``` + +### off + +Removes an event handler for the specified event key. + +#### Signature + +```ts +function off( + key: Key, + handler?: EventHandler +): 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 + +```ts +type AvailableEvents = { + 'user:created': { name: string }; +}; + +const ee = createEmitter(); + +const logUser = defineHandler((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 + +```ts +emit( + 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 + +```ts +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 + +```ts +emitAsync( + c: Context, + key: Key, + payload: EventPayloadMap[Key], + options?: EmitAsyncOptions +): Promise +``` + +#### 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` + +#### Example + +```ts +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. + +```ts +type EventKey = string | symbol +``` + +### EventHandler +A function type that handles an event. + +```ts +type EventHandler = (c: Context, payload: T) => void | Promise +``` + +### EventHandlers +An object type containing event handlers for multiple event types/keys. + +```ts +type EventHandlers = { [K in keyof T]?: EventHandler[] } +``` + +### EventPayloadMap +An object type containing event keys and their corresponding payload types. + +```ts +type EventPayloadMap = Record +``` + +### EventEmitterOptions + +An object type containing options for the `Emitter` class. + +```ts +type EventEmitterOptions = { maxHandlers?: number }; +``` + +### EmitAsyncOptions +An object type containing options for the `emitAsync` method. + +```ts +type EmitAsyncOptions = { + mode?: 'concurrent' | 'sequencial' +} +``` + +### Emitter + +An interface representing an event emitter. + +```ts +interface Emitter { + on(key: Key, handler: EventHandler): void; + off(key: Key, handler?: EventHandler): void; + emit(c: Context, key: Key, payload: EventPayloadMap[Key]): void; + emitAsync( + c: Context, + key: Key, + payload: EventPayloadMap[Key], + options?: EmitAsyncOptions + ): Promise; +} +``` For more usage examples, see the [tests](src/index.test.ts) or [Hono REST API starter kit](https://github.com/DavidHavl/hono-rest-api-starter) +## 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 - +David Havl ## License diff --git a/packages/event-emitter/package.json b/packages/event-emitter/package.json index d04db2e7..dbd88b1d 100644 --- a/packages/event-emitter/package.json +++ b/packages/event-emitter/package.json @@ -36,8 +36,11 @@ "hono": "*" }, "devDependencies": { - "hono": "^3.11.7", + "hono": "^4.3.6", "tsup": "^8.0.1", - "vitest": "^1.0.4" + "vitest": "^1.6.0" + }, + "engines": { + "node": ">=16.0.0" } } diff --git a/packages/event-emitter/src/index.test.ts b/packages/event-emitter/src/index.test.ts index 5c922b5f..b7c24ff6 100644 --- a/packages/event-emitter/src/index.test.ts +++ b/packages/event-emitter/src/index.test.ts @@ -1,243 +1,436 @@ -import { Hono } from 'hono'; -import { expect, vi } from 'vitest'; -import { emitter, createEmitter, type Emitter, type EventHandlers, defineHandler, defineHandlers } from '../src'; - -describe('EventEmitter', () => { - describe('Used inside of route handlers', () => { - it('Should work when subscribing to events inside of route handler', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - }; - type Env = { Variables: { emitter: Emitter } }; - - const handler = defineHandler((_c, _payload) => {}); - - const spy = vi.fn(handler); - - const app = new Hono(); - - app.use('*', emitter()); - - app.use((c, next) => { - c.get('emitter').on('todo:created', spy); - return next(); - }); - - let currentContext = null; - app.post('/todo', (c) => { - currentContext = c; - c.get('emitter').emit('todo:created', c, { id: '2', text: 'Buy milk' }); - return c.json({ message: 'Todo created' }); - }); - - const res = await app.request('http://localhost/todo', { method: 'POST' }); - expect(res).not.toBeNull(); - expect(res.status).toBe(200); - expect(spy).toHaveBeenCalledWith(currentContext, { id: '2', text: 'Buy milk' }); - }); - - it('Should not subscribe same handler to same event twice inside of route handler', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - }; - type Env = { Variables: { emitter: Emitter } }; - - const handler = defineHandler((_c, _payload) => {}); - - const spy = vi.fn(handler); - - const app = new Hono(); - - app.use('*', emitter()); - - app.use((c, next) => { - c.get('emitter').on('todo:created', spy); - return next(); - }); - - app.post('/todo', (c) => { - c.get('emitter').emit('todo:created', c, { id: '2', text: 'Buy milk' }); - return c.json({ message: 'Todo created' }); - }); - - await app.request('http://localhost/todo', { method: 'POST' }); - await app.request('http://localhost/todo', { method: 'POST' }); - await app.request('http://localhost/todo', { method: 'POST' }); - expect(spy).toHaveBeenCalledTimes(3); - }); - - it('Should work assigning event handlers via middleware', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - }; - - type Env = { Variables: { emitter: Emitter } }; - - const handlers = defineHandlers({ +import { Hono } from 'hono' +import type {Context} from 'hono' +import { describe, expect, it, vi } from 'vitest' +import { createEmitter, defineHandler, defineHandlers, emitter } from './index' +import type {Emitter} from './index' // Adjust the import path as needed + +describe('Event Emitter Middleware', () => { + describe('createEmitter', () => { + it('should create an emitter with initial handlers', () => { + type EventPayloadMap = { + test: { id: string; text: string } + } + const handlers = { + test: [vi.fn()], + } + const ee = createEmitter(handlers) + expect(ee).toBeDefined() + expect(ee.emit).toBeDefined() + expect(ee.on).toBeDefined() + expect(ee.off).toBeDefined() + expect(ee.emitAsync).toBeDefined() + }) + + it('should create an emitter without initial handlers', () => { + const ee = createEmitter() + expect(ee).toBeDefined() + }) + + it('should allow adding and removing handlers', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + const handler = vi.fn() + ee.on('test', handler) + ee.emit({} as Context, 'test', 'payload') + expect(handler).toHaveBeenCalledWith({}, 'payload') + + ee.off('test', handler) + ee.emit({} as Context, 'test', 'payload') + expect(handler).toHaveBeenCalledTimes(1) + }) + + it('should remove all handlers for an event when no handler is specified', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + const handler1 = vi.fn() + const handler2 = vi.fn() + ee.on('test', handler1) + ee.on('test', handler2) + ee.off('test') + ee.emit({} as Context, 'test', 'payload') + expect(handler1).not.toHaveBeenCalled() + expect(handler2).not.toHaveBeenCalled() + }) + + it('should emit events to all registered handlers', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + const handler1 = vi.fn() + const handler2 = vi.fn() + ee.on('test', handler1) + ee.on('test', handler2) + ee.emit({} as Context, 'test', 'payload') + expect(handler1).toHaveBeenCalledWith({}, 'payload') + expect(handler2).toHaveBeenCalledWith({}, 'payload') + }) + + it('should not add the same named function handler multiple times', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + const handler = vi.fn() + ee.on('test', handler) + ee.on('test', handler) + ee.emit({} as Context, 'test', 'payload') + expect(handler).toHaveBeenCalledTimes(1) + }) + + it('should emit async events concurrently', async () => { + type EventPayloadMap = { + test: { id: string } + } + const ee = createEmitter() + const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) + const handler1 = vi.fn( + defineHandler(async (_c, _payload) => { + await delay(100) + }) + ) + const handler2 = vi.fn( + defineHandler(async (_c, _payload) => { + await delay(100) + }) + ) + + ee.on('test', handler1) + ee.on('test', handler2) + + const start = Date.now() + await ee.emitAsync({} as Context, 'test', { id: '123' }, { mode: 'concurrent' }) + const end = Date.now() + + // The total time should be close to 100ms (since handlers run concurrently) + // We'll allow a small margin for execution time + expect(end - start).toBeLessThan(150) + + expect(handler1).toHaveBeenCalledWith(expect.anything(), { id: '123' }) + expect(handler2).toHaveBeenCalledWith(expect.anything(), { id: '123' }) + expect(handler1).toHaveBeenCalledTimes(1) + expect(handler2).toHaveBeenCalledTimes(1) + }) + + it('should emit async events sequentially', async () => { + type EventPayloadMap = { + test: { id: string } + } + const ee = createEmitter() + const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms)) + const handler1 = vi.fn( + defineHandler(async (_c, _payload) => { + await delay(101) + }) + ) + const handler2 = vi.fn( + defineHandler(async (_c, _payload) => { + await delay(101) + }) + ) + ee.on('test', handler1) + ee.on('test', handler2) + const start = Date.now() + await ee.emitAsync({} as Context, 'test', { id: '123' }, { mode: 'sequencial' }) + const end = Date.now() + + // The total time should be close to 200ms (since handlers run sequentially) + // We'll allow a small margin for execution time + expect(end - start).toBeGreaterThanOrEqual(200) + expect(end - start).toBeLessThan(250) + + expect(handler1).toHaveBeenCalledWith(expect.anything(), { id: '123' }) + expect(handler2).toHaveBeenCalledWith(expect.anything(), { id: '123' }) + expect(handler1).toHaveBeenCalledTimes(1) + expect(handler2).toHaveBeenCalledTimes(1) + }) + + it('should throw AggregateError when async handlers fail using emitAsync with concurent mode', async () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + const handler1 = vi.fn().mockRejectedValue(new Error('Error 1')) + const handler2 = vi.fn().mockRejectedValue(new Error('Error 2')) + ee.on('test', handler1) + ee.on('test', handler2) + await expect(ee.emitAsync({} as Context, 'test', 'payload')).rejects.toThrow(AggregateError) + try { + await ee.emitAsync({} as Context, 'test', 'payload', { mode: 'concurrent' }) + // Should not reach here + expect(true).toBe(false) + } catch (error) { + expect((error as AggregateError).errors).toHaveLength(2) + expect((error as AggregateError).errors[0].message).toBe('Error 1') + expect((error as AggregateError).errors[1].message).toBe('Error 2') + } + }) + + it('should stop execution on first error in async handlers fail using emitAsync with sequential mode', async () => { + type EventPayloadMap = { + test: { id: string } + } + + const ee = createEmitter() + + const handler1 = vi.fn( + defineHandler(async () => { + throw new Error('Error 1') + }) + ) + + const handler2 = vi.fn( + defineHandler(async () => { + // This should not be called + }) + ) + + ee.on('test', handler1) + ee.on('test', handler2) + + try { + await ee.emitAsync({} as Context, 'test', { id: '789' }, { mode: 'sequencial' }) + // Should not reach here + expect(true).toBe(false) + } catch (error) { + expect(error).toBeInstanceOf(Error) + expect((error as Error).message).toBe('Error 1') + } + + expect(handler1).toHaveBeenCalledWith(expect.anything(), { id: '789' }) + expect(handler1).toHaveBeenCalledTimes(1) + expect(handler2).not.toHaveBeenCalled() + }) + + it('should throw TypeError when adding a non-function handler', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + // biome-ignore lint/suspicious/noExplicitAny: + expect(() => ee.on('test', 'not a function' as any)).toThrow(TypeError) + }) + + it('should throw RangeError when max handlers limit is reached', () => { + type EventPayloadMap = { test: string } + const emitter = createEmitter({}, { maxHandlers: 3 }) + emitter.on('test', vi.fn()) + emitter.on('test', vi.fn()) + emitter.on('test', vi.fn()) + expect(() => emitter.on('test', vi.fn())).toThrow(RangeError) + }) + + it('should use default max handlers limit of 10 when not specified', () => { + type EventPayloadMap = { testEvent: string } + const emitter = createEmitter() + for (let i = 0; i < 10; i++) { + emitter.on('testEvent', vi.fn()) + } + expect(() => emitter.on('testEvent', vi.fn())).toThrow(RangeError) + }) + + it('should allow different events to have their own handler counts', () => { + type EventPayloadMap = { test1: string; test2: string } + const emitter = createEmitter({}, { maxHandlers: 2 }) + emitter.on('test1', vi.fn()) + emitter.on('test1', vi.fn()) + emitter.on('test2', vi.fn()) + expect(() => emitter.on('test1', vi.fn())).toThrow(RangeError) + expect(() => emitter.on('test2', vi.fn())).not.toThrow() + }) + + it('should include event key in error message when limit is reached', () => { + type EventPayloadMap = { specificEvent: string } + const emitter = createEmitter({}, { maxHandlers: 1 }) + emitter.on('specificEvent', vi.fn()) + expect(() => emitter.on('specificEvent', vi.fn())).toThrow(/specificEvent/) + }) + + it('should allow setting custom max handlers limit', () => { + type EventPayloadMap = { test: string } + const emitter = createEmitter({}, { maxHandlers: 5 }) + for (let i = 0; i < 5; i++) { + emitter.on('test', vi.fn()) + } + expect(() => emitter.on('test', vi.fn())).toThrow(RangeError) + }) + + it('should do nothing when emitting an event with no handlers', () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + expect(() => ee.emit({} as Context, 'test', 'payload')).not.toThrow() + }) + + it('should do nothing when emitting an async event with no handlers', async () => { + type EventPayloadMap = { + test: string + } + const ee = createEmitter() + await expect(ee.emitAsync({} as Context, 'test', 'payload')).resolves.toBeUndefined() + }) + }) + + describe('emitter middleware', () => { + it('should add emitter to context', async () => { + type EventPayloadMap = { + test: string + } + const middleware = emitter() + const context = { + set: vi.fn(), + } as unknown as Context + const next = vi.fn() + + await middleware(context, next) + + expect(context.set).toHaveBeenCalledWith('emitter', expect.any(Object)) + expect(next).toHaveBeenCalled() + }) + + it('should create emitter with provided handlers', async () => { + const handler = vi.fn() + type EventPayloadMap = { + test: string + } + const middleware = emitter({ test: [handler] }) + + let capturedEmitter: Emitter | undefined + const context = { + set: vi.fn().mockImplementation((key, value) => { + if (key === 'emitter') { + capturedEmitter = value + } + }), + } as unknown as Context + const next = vi.fn() + + await middleware(context, next) + + expect(context.set).toHaveBeenCalledWith('emitter', expect.any(Object)) + expect(capturedEmitter).toBeDefined() + + capturedEmitter?.emit({} as Context, 'test', 'payload') + expect(handler).toHaveBeenCalledWith({}, 'payload') + }) + }) + + describe('defineHandler', () => { + it('should return the provided handler', () => { + type EventPayloadMap = { + test: number + } + const handler = (_c: Context, _payload: number) => {} + const definedHandler = defineHandler(handler) + expect(definedHandler).toBe(handler) + }) + }) + + describe('defineHandlers', () => { + it('should return the provided handlers object', () => { + const handlers = { + test: [(_c: Context, _payload: number) => {}], + } + const definedHandlers = defineHandlers(handlers) + expect(definedHandlers).toBe(handlers) + }) + }) + + describe('type safety', () => { + it('should enforce correct types for event payloads', () => { + type EventPayloadMap = { + numberEvent: number + objectEvent: { id: string } + } + + const ee = createEmitter() + + // These should compile without errors + ee.on('numberEvent', (_c, payload) => { + const _num: number = payload + }) + ee.on('objectEvent', (_c, payload) => { + const _id: string = payload.id + }) + + // @ts-expect-error - payload should be a number + ee.emit('numberEvent', {} as Context, 'not a number') + + // @ts-expect-error - payload should be an object with an id property + ee.emit('objectEvent', {} as Context, { wrongKey: 'value' }) + + // These should compile without errors + ee.emit({} as Context, 'numberEvent', 42) + ee.emit({} as Context, 'objectEvent', { id: 'test' }) + }) + }) + describe('Hono request flow', () => { + it('should work when assigning event handlers via middleware', async () => { + type EventPayloadMap = { + 'todo:created': { id: string; text: string } + } + + type Env = { Variables: { emitter: Emitter } } + + const handlers = defineHandlers({ 'todo:created': [vi.fn((_c, _payload) => {})], - }); - - const app = new Hono(); - - app.use('*', emitter(handlers)); - - let currentContext = null; - app.post('/todo', (c) => { - currentContext = c; - c.get('emitter').emit('todo:created', c, { id: '2', text: 'Buy milk' }); - return c.json({ message: 'Todo created' }); - }); - - const res = await app.request('http://localhost/todo', { method: 'POST' }); - expect(res).not.toBeNull(); - expect(res.status).toBe(200); - expect(handlers['todo:created']?.[0]).toHaveBeenCalledWith(currentContext, { id: '2', text: 'Buy milk' }); - }); - }); - - describe('Used as standalone', () => { - it('Should work assigning event handlers via createEmitter function param', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - 'todo:deleted': { id: string }; - }; - - type Env = { Variables: { emitter: Emitter } }; - - const handlers: EventHandlers = { - 'todo:created': [vi.fn((_payload) => {})], - }; - - const ee = createEmitter(handlers); - - const todoDeletedHandler = vi.fn(defineHandler((_c, _payload) => {})); - - ee.on('todo:deleted', todoDeletedHandler); - - const app = new Hono(); - - let todoCreatedContext = null; - app.post('/todo', (c) => { - todoCreatedContext = c; - ee.emit('todo:created', c, { id: '2', text: 'Buy milk' }); - return c.json({ message: 'Todo created' }); - }); - - let todoDeletedContext = null; - app.delete('/todo/123', (c) => { - todoDeletedContext = c; - ee.emit('todo:deleted', c, { id: '3' }); - return c.json({ message: 'Todo deleted' }); - }); - - const res = await app.request('http://localhost/todo', { method: 'POST' }); - expect(res).not.toBeNull(); - expect(res.status).toBe(200); - expect(handlers['todo:created']?.[0]).toHaveBeenCalledWith(todoCreatedContext, { id: '2', text: 'Buy milk' }); - const res2 = await app.request('http://localhost/todo/123', { method: 'DELETE' }); - expect(res2).not.toBeNull(); - expect(res2.status).toBe(200); - expect(todoDeletedHandler).toHaveBeenCalledWith(todoDeletedContext, { id: '3' }); - }); - - it('Should work assigning event handlers via standalone on()', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - 'todo:deleted': { id: string }; - }; - - type Env = { Variables: { emitter: Emitter } }; - - const ee = createEmitter(); - - const todoDeletedHandler = defineHandler( - (_c, _payload: EventHandlerPayloads['todo:deleted']) => {}, - ); - - const spy = vi.fn(todoDeletedHandler); - - ee.on('todo:deleted', spy); - - const app = new Hono(); - - let currentContext = null; - app.delete('/todo/123', (c) => { - currentContext = c; - ee.emit('todo:deleted', c, { id: '2' }); - return c.json({ message: 'Todo created' }); - }); - - const res = await app.request('http://localhost/todo/123', { method: 'DELETE' }); - expect(res).not.toBeNull(); - expect(res.status).toBe(200); - expect(spy).toHaveBeenCalledWith(currentContext, { id: '2' }); - }); - - it('Should work removing event handlers via off() method', async () => { - type EventHandlerPayloads = { - 'todo:created': { id: string; text: string }; - 'todo:deleted': { id: string }; - }; - - type Env = { Variables: { emitter: Emitter } }; - - const ee = createEmitter(); - - const todoDeletedHandler = defineHandler( - (_c, _payload: EventHandlerPayloads['todo:deleted']) => {}, - ); - - const spy = vi.fn(todoDeletedHandler); - - ee.on('todo:deleted', spy); - - const app = new Hono(); - - app.post('/todo', (c) => { - ee.emit('todo:deleted', c, { id: '2' }); - ee.off('todo:deleted', spy); - return c.json({ message: 'Todo created' }); - }); - - await app.request('http://localhost/todo', { method: 'POST' }); - await app.request('http://localhost/todo', { method: 'POST' }); - expect(spy).toHaveBeenCalledTimes(1); - }); - - it('Should work removing all event handlers via off() method not providing handler as second argument', async () => { - type EventHandlerPayloads = { - 'todo:deleted': { id: string }; - }; - - type Env = { Variables: { emitter: Emitter } }; - - const ee = createEmitter(); - - const todoDeletedHandler = defineHandler( - (_c, _payload: EventHandlerPayloads['todo:deleted']) => {}, - ); - const todoDeletedHandler2 = defineHandler( - (_c, _payload: EventHandlerPayloads['todo:deleted']) => {}, - ); - - const spy = vi.fn(todoDeletedHandler); - const spy2 = vi.fn(todoDeletedHandler2); - - ee.on('todo:deleted', spy); - ee.on('todo:deleted', spy2); + }) - const app = new Hono(); + const app = new Hono() + app.use(emitter(handlers)) + const ee = createEmitter<{ sdf: string; adsf: number }>() + ee.on('adsf', vi.fn()) + let currentContext = null app.post('/todo', (c) => { - ee.emit('todo:deleted', c, { id: '2' }); - ee.off('todo:deleted'); - return c.json({ message: 'Todo created' }); - }); - - await app.request('http://localhost/todo', { method: 'POST' }); - await app.request('http://localhost/todo', { method: 'POST' }); - expect(spy).toHaveBeenCalledTimes(1); - expect(spy2).toHaveBeenCalledTimes(1); - }); - }); -}); + currentContext = c + c.get('emitter').emit(c, 'todo:created', { id: '2', text: 'Buy milk' }) + return c.json({ message: 'Todo created' }) + }) + + const res = await app.request('http://localhost/todo', { method: 'POST' }) + expect(res).not.toBeNull() + expect(res.status).toBe(200) + expect(handlers['todo:created']?.[0]).toHaveBeenCalledWith(currentContext, { + id: '2', + text: 'Buy milk', + }) + }) + + it('should work when assigning async event handlers via middleware', async () => { + type EventPayloadMap = { + 'todo:created': { id: string; text: string } + } + + type Env = { Variables: { emitter: Emitter } } + + const handlers = defineHandlers({ + 'todo:created': [vi.fn(async (_c, _payload) => {})], + }) + + const app = new Hono() + + app.use(emitter(handlers)) + + let currentContext = null + app.post('/todo', async (c) => { + currentContext = c + await c.get('emitter').emitAsync(c, 'todo:created', { id: '2', text: 'Buy milk' }) + return c.json({ message: 'Todo created' }) + }) + + const res = await app.request('http://localhost/todo', { method: 'POST' }) + expect(res).not.toBeNull() + expect(res.status).toBe(200) + expect(handlers['todo:created']?.[0]).toHaveBeenCalledWith(currentContext, { + id: '2', + text: 'Buy milk', + }) + }) + }) +}) diff --git a/packages/event-emitter/src/index.ts b/packages/event-emitter/src/index.ts index d119ff6e..ace600e7 100644 --- a/packages/event-emitter/src/index.ts +++ b/packages/event-emitter/src/index.ts @@ -3,17 +3,28 @@ * Event Emitter Middleware for Hono. */ -import type { Context, Env, MiddlewareHandler } from 'hono'; -import { createMiddleware } from 'hono/factory' +import type { Context, Env, MiddlewareHandler } from 'hono' -export type EventKey = string | symbol; -export type EventHandler = (c: Context, payload: T) => void | Promise; -export type EventHandlers = { [K in keyof T]?: EventHandler[] }; +export type EventKey = string | symbol +export type EventHandler = ( + c: Context, + payload: T +) => void | Promise +export type EventHandlers = { [K in keyof T]?: EventHandler[] } +export type EventPayloadMap = { [key: string]: unknown } +export type EmitAsyncOptions = { mode: 'concurrent' | 'sequencial' } +export type EventEmitterOptions = { maxHandlers?: number } -export interface Emitter { - on(key: Key, handler: EventHandler): void; - off(key: Key, handler?: EventHandler): void; - emit(key: Key, c: Context, payload: EventHandlerPayloads[Key]): void; +export interface Emitter { + on(key: Key, handler: EventHandler): void + off(key: Key, handler?: EventHandler): void + emit(c: Context, key: Key, payload: EPMap[Key]): void + emitAsync( + c: Context, + key: Key, + payload: EPMap[Key], + options?: EmitAsyncOptions + ): Promise } /** @@ -21,25 +32,33 @@ export interface Emitter { * @param {EventHandler} handler - The event handlers. * @returns The event handler. */ -export const defineHandler = ( - handler: EventHandler, -): EventHandler => { - return handler; -}; +export const defineHandler = < + EPMap extends EventPayloadMap, + Key extends keyof EPMap, + E extends Env = Env +>( + handler: EventHandler +): EventHandler => { + return handler +} /** * Function to define fully typed event handlers. * @param {EventHandler[]} handlers - An object where each key is an event type and the value is an array of event handlers. * @returns The event handlers. */ -export const defineHandlers = (handlers: { [K in keyof T]?: EventHandler[] }) => { - return handlers; -}; +export const defineHandlers = (handlers: { + [K in keyof EPMap]?: EventHandler[] +}): { [K in keyof EPMap]?: EventHandler[] } => { + return handlers +} /** * Create Event Emitter instance. * - * @param {EventHandlers} eventHandlers - Event handlers to be registered. + * @template EPMap - The event payload map. + * @param {EventHandlers} [eventHandlers] - Event handlers to be registered. + * @param {EventEmitterOptions} [options] - Options for the event emitter. * @returns {Emitter} The EventEmitter instance. * * @example @@ -59,9 +78,14 @@ export const defineHandlers = (handlers: { [K in keyof T * c.get('logger').log('Bar:', payload.item.id) * }) * + * ee.on('baz', async (c, payload) => { + * // Do something async + * }) + * * // Use the emitter to emit events. - * ee.emit('foo', c, 42) - * ee.emit('bar', c, { item: { id: '12345678' } }) + * ee.emit(c, 'foo', 42) + * ee.emit(c, 'bar', { item: { id: '12345678' } }) + * await ee.emitAsync(c, 'baz', { item: { id: '12345678' } }) * ``` * * ```ts @@ -69,6 +93,7 @@ export const defineHandlers = (handlers: { [K in keyof T * // event key: payload type * 'foo': number; * 'bar': { item: { id: string } }; + * 'baz': { item: { id: string } }; * }; * * // Define event handlers @@ -86,33 +111,52 @@ export const defineHandlers = (handlers: { [K in keyof T * c.get('logger').log('Bar:', payload.item.id) * }) * + * ee.on('baz', async (c, payload) => { + * // Do something async + * }) + * * // Use the emitter to emit events. - * ee.emit('foo', c, 42) // Payload will be expected to be of a type number - * ee.emit('bar', c, { item: { id: '12345678' }, c }) // Payload will be expected to be of a type { item: { id: string }, c: Context } + * ee.emit(c, 'foo', 42) // Payload will be expected to be of a type number + * ee.emit(c, 'bar', { item: { id: '12345678' } }) // Payload will be expected to be of a type { item: { id: string }, c: Context } + * await ee.emitAsync(c, 'baz', { item: { id: '12345678' } }) // Payload will be expected to be of a type { item: { id: string } } * ``` * */ -export const createEmitter = ( - eventHandlers?: EventHandlers, -): Emitter => { +export const createEmitter = ( + eventHandlers?: EventHandlers, + options?: EventEmitterOptions +): Emitter => { // A map of event keys and their corresponding event handlers. const handlers: Map[]> = eventHandlers ? new Map(Object.entries(eventHandlers)) - : new Map(); + : new Map() return { /** * Add an event handler for the given event key. * @param {string|symbol} key Type of event to listen for * @param {Function} handler Function that is invoked when the specified event occurs + * @throws {TypeError} If the handler is not a function */ - on(key: Key, handler: EventHandler) { + on(key: Key, handler: EventHandler) { + if (typeof handler !== 'function') { + throw new TypeError('The handler must be a function') + } if (!handlers.has(key as EventKey)) { - handlers.set(key as EventKey, []); + handlers.set(key as EventKey, []) + } + const handlerArray = handlers.get(key as EventKey) as Array> + const limit = options?.maxHandlers ?? 10 + if (handlerArray.length >= limit) { + throw new RangeError( + `Max handlers limit (${limit}) reached for the event "${String(key)}". + This may indicate a memory leak, + perhaps due to adding anonymous function as handler within middleware or request handler. + Check your code or consider increasing limit using options.maxHandlers.` + ) } - const handlerArray = handlers.get(key as EventKey) as Array>; if (!handlerArray.includes(handler)) { - handlerArray.push(handler); + handlerArray.push(handler) } }, @@ -122,16 +166,16 @@ export const createEmitter = ( * @param {string|symbol} key Type of event to unregister `handler` from * @param {Function} handler - Handler function to remove */ - off(key: Key, handler?: EventHandler) { + off(key: Key, handler?: EventHandler) { if (!handler) { - handlers.delete(key as EventKey); + handlers.delete(key as EventKey) } else { - const handlerArray = handlers.get(key as EventKey); + const handlerArray = handlers.get(key as EventKey) if (handlerArray) { handlers.set( key as EventKey, - handlerArray.filter((h) => h !== handler), - ); + handlerArray.filter((h) => h !== handler) + ) } } }, @@ -139,27 +183,69 @@ export const createEmitter = ( /** * Emit an event with the given event key and payload. * Triggers all event handlers associated with the specified key. - * @param {string|symbol} key - The event key * @param {Context} c - The current context object - * @param {EventHandlerPayloads[keyof EventHandlerPayloads]} payload - Data passed to each invoked handler + * @param {string|symbol} key - The event key + * @param {EventPayloadMap[keyof EventPayloadMap]} payload - Data passed to each invoked handler */ - emit(key: Key, c: Context, payload: EventHandlerPayloads[Key]) { - const handlerArray = handlers.get(key as EventKey); + emit(c: Context, key: Key, payload: EPMap[Key]) { + const handlerArray = handlers.get(key as EventKey) if (handlerArray) { for (const handler of handlerArray) { - handler(c, payload); + handler(c, payload) + } + } + }, + + /** + * Emit an event with the given event key and payload. + * Asynchronously triggers all event handlers associated with the specified key. + * @param {Context} c - The current context object + * @param {string|symbol} key - The event key + * @param {EventPayloadMap[keyof EventPayloadMap]} payload - Data passed to each invoked handler + * @param {EmitAsyncOptions} options - Options. + * @throws {AggregateError} If any handler encounters an error. + */ + async emitAsync( + c: Context, + key: Key, + payload: EPMap[Key], + options: EmitAsyncOptions = { mode: 'concurrent' } + ) { + const handlerArray = handlers.get(key as EventKey) + if (handlerArray) { + if (options.mode === 'sequencial') { + for (const handler of handlerArray) { + await handler(c, payload) + } + } else { + const results = await Promise.allSettled( + handlerArray.map(async (handler) => { + await handler(c, payload) + }) + ) + const errors = ( + results.filter((r) => r.status === 'rejected') as PromiseRejectedResult[] + ).map((e) => e.reason) + if (errors.length > 0) { + throw new AggregateError( + errors, + `${errors.length} handler(s) for event ${String(key)} encountered errors` + ) + } } } }, - }; -}; + } +} /** * Event Emitter Middleware for Hono. * - * @see {@link https://hono.dev/middleware/builtin/event-emitter} + * @see {@link https://github.com/honojs/middleware/tree/main/packages/event-emitter} * - * @param {EventHandlers} eventHandlers - Event handlers to be registered. + * @template EPMap - The event payload map. + * @param {EventHandlers} [eventHandlers] - Event handlers to be registered. + * @param {EventEmitterOptions} [options] - Options for the event emitter. * @returns {MiddlewareHandler} The middleware handler function. * * @example @@ -169,9 +255,14 @@ export const createEmitter = ( * const handlers: { * 'foo': [ * (c, payload) => { console.log('Foo:', payload) } - * ] + * ], * 'bar': [ * (c, payload) => { console.log('Bar:', payload.item.id) } + * ], + * 'baz': [ + * async (c, payload) => { + * // Do something async + * } * ] * } * @@ -183,8 +274,9 @@ export const createEmitter = ( * // Use the emitter in route handlers to emit events. * app.post('/foo', async (c) => { * // The emitter is available under "emitter" key in the context. - * c.get('emitter').emit('foo', c, 42) - * c.get('emitter').emit('bar', c, { item: { id: '12345678' } }) + * c.get('emitter').emit(c, 'foo', 42) + * c.get('emitter').emit(c, 'bar', { item: { id: '12345678' } }) + * await c.get('emitter').emitAsync(c, 'baz', { item: { id: '12345678' } }) * return c.text('Success') * }) * ``` @@ -194,6 +286,7 @@ export const createEmitter = ( * // event key: payload type * 'foo': number; * 'bar': { item: { id: string } }; + * 'baz': { item: { id: string } }; * }; * * type Env = { Bindings: {}; Variables: { emitter: Emitter }; } @@ -202,9 +295,14 @@ export const createEmitter = ( * const handlers: defineHandlers({ * 'foo': [ * (c, payload) => { console.log('Foo:', payload) } // payload will be inferred as number - * ] + * ], * 'bar': [ * (c, payload) => { console.log('Bar:', payload.item.id) } // payload will be inferred as { item: { id: string } } + * ], + * 'baz': [ + * async (c, payload) => { + * // Do something async + * } * ] * }) * @@ -216,19 +314,21 @@ export const createEmitter = ( * // Use the emitter in route handlers to emit events. * app.post('/foo', async (c) => { * // The emitter is available under "emitter" key in the context. - * c.get('emitter').emit('foo', c, 42) // Payload will be expected to be of a type number - * c.get('emitter').emit('bar', c, { item: { id: '12345678' } }) // Payload will be expected to be of a type { item: { id: string } } + * c.get('emitter').emit(c, 'foo', 42) // Payload will be expected to be of a type number + * c.get('emitter').emit(c, 'bar', { item: { id: '12345678' } }) // Payload will be expected to be of a type { item: { id: string } } + * await c.get('emitter').emitAsync(c, 'baz', { item: { id: '12345678' } }) // Payload will be expected to be of a type { item: { id: string } } * return c.text('Success') * }) * ``` */ -export const emitter = ( - eventHandlers?: EventHandlers, +export const emitter = ( + eventHandlers?: EventHandlers, + options?: EventEmitterOptions ): MiddlewareHandler => { // Create new instance to share with any middleware and handlers - const instance = createEmitter(eventHandlers); - return createMiddleware(async (c, next) => { - c.set('emitter', instance); - await next(); - }); -}; + const instance = createEmitter(eventHandlers, options) + return async (c, next) => { + c.set('emitter', instance) + await next() + } +} diff --git a/yarn.lock b/yarn.lock index 1457372a..822e5d5e 100644 --- a/yarn.lock +++ b/yarn.lock @@ -2299,9 +2299,9 @@ __metadata: version: 0.0.0-use.local resolution: "@hono/event-emitter@workspace:packages/event-emitter" dependencies: - hono: "npm:^3.11.7" + hono: "npm:^4.3.6" tsup: "npm:^8.0.1" - vitest: "npm:^1.0.4" + vitest: "npm:^1.6.0" peerDependencies: hono: "*" languageName: unknown