Evenex

A lightweight, type-safe, fully-featured Event Bus library for modern JavaScript and TypeScript projects.

English | 简体中文

✨ Features

• ✅ Type-safe event definitions
• 🔁 on / once / off / emit API
• 🧼 Clear & remove listeners easily
• 🧰 Utility methods: has, listenerCount, eventNames, listeners
• 🛡️ Global error handling with onError
• 🧠 Debug mode for development
• ⚡ Zero dependencies & lightweight

📦 Installation

npm install evenex
# or
yarn add evenex
# or
pnpm add evenex

🪄 Basic Usage

import evenex from 'evenex'

// Listen to an event
evenex.on('hello', (name: string) => {
  console.log(`Hello, ${name}!`)
})

// Emit event
evenex.emit('hello', 'World')
// -> Hello, World!

🧠 Type-safe Events

You can define your own event map interface for better type inference:

import { createEvenex } from 'evenex'

interface MyEvents {
  'user:login': [userId: string]
  'user:logout': []
}

const bus = createEvenex<MyEvents>()

bus.on('user:login', (userId) => {
  console.log('User logged in:', userId)
})

bus.emit('user:login', '12345') // ✅ OK
bus.emit('user:login') // ❌ Type error

🧼 Removing Listeners

const handler = () => console.log('event')

bus.on('foo', handler)
bus.off('foo', handler) // remove specific
bus.off('foo') // remove all listeners of foo
bus.clear() // remove all listeners of all events

🛠 API

| Method | Description | | ---------------------- | ------------------------------------------------ | | on(event, handler) | Subscribe to an event | | once(event, handler) | Subscribe once only | | off(event, handler?) | Unsubscribe handler or all handlers of the event | | emit(event, ...args) | Trigger event | | has(event) | Check if event has listeners | | listenerCount(event) | Get number of listeners | | eventNames() | Get all event names | | listeners(event) | Get all listener functions | | clear(event?) | Clear specific or all events | | removeAllListeners() | Alias for clear() |

🪝 Global Error Handling

import { createEvenex } from 'evenex'

const bus = createEvenex({
  onError(error, event, handler) {
    console.error(`Error in ${String(event)}:`, error)
  }
})

bus.on('boom', () => {
  throw new Error('💥')
})

bus.emit('boom') // error is caught by onError

📄 License

MIT License © 2025-PRESENT king3

🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check the issues page.