event-on/README.md

A high-performance event handler optimized for high-frequency scenarios with support for regular and one-time events

# event-on

A high-performance event handler optimized for high-frequency scenarios, with support for regular and one-time events. It balances performance and memory efficiency through flat storage and memory reuse strategies.

## Features

- **Extreme Performance**: Outperforms mainstream libraries by 2-3x in high-frequency event triggering scenarios
- **Memory Efficiency**: Uses flat array storage and array reuse pool, consuming ~50% less memory than traditional implementations
- **Fast Response**: Optimized triggering logic reduces GC pressure and performance jank
- **Simple API**: Familiar `on`/`once`/`off`/`trigger` interface with minimal learning curve
- **TypeScript Support**: Complete type definitions for enhanced development experience

## Installation

```bash
npm install event-on
```

## Quick Start

```javascript
import { EventOn } from 'event-on';

// Create an instance
const emitter = new EventOn();

// Bind a regular event
emitter.on('message', (text) => {
  console.log('Received message:', text);
});

// Bind a one-time event (auto-unbinds after triggering)
emitter.once('init', () => {
  console.log('Initialization complete (triggers once only)');
});

// Trigger events
emitter.trigger('message', 'Hello World');
emitter.trigger('init');
emitter.trigger('init'); // No effect (already triggered once)

// Unbind an event
const handler = () => console.log('This handler will be unbound');
emitter.on('test', handler);
emitter.off('test', handler);
```

## API Documentation

### Constructor

```typescript
new EventOn()
```

Creates a new event handler instance.

### Methods

#### on(event, callback, context?)

Binds a regular event handler.

- `event`: Event name (string)
- `callback`: Function to execute when the event is triggered
- `context`: Value of `this` inside the callback (optional, defaults to `null`)

```typescript
emitter.on('click', (x, y) => {
  console.log(`Click position: ${x}, ${y}`);
}, this);
```

#### once(event, callback, context?)

Binds a one-time event handler (auto-unbinds after the first trigger).

- Parameters are the same as `on()`

```typescript
emitter.once('load', () => {
  console.log('Resource loaded successfully');
});
```

#### off(event, callback?, context?)

Unbinds an event handler.

- `event`: Event name to unbind
- `callback`: Specific handler to unbind (optional; omitting unbinds all handlers for the event)
- `context`: `this` value used when binding the handler (optional; for precise matching)

```typescript
// Unbind a specific handler
emitter.off('click', handleClick);

// Unbind all handlers for an event
emitter.off('click');
```

#### trigger(event, ...args)

Triggers all handlers for a specified event.

- `event`: Event name to trigger
- `...args`: Arguments to pass to the event handlers
- Returns: `boolean` - Whether propagation was prevented

```typescript
// Trigger an event with parameters
const wasPrevented = emitter.trigger('data', { id: 1, value: 'example' });
```

#### has(event)

Checks if an event has any bound handlers.

- `event`: Event name to check
- Returns: `boolean` - `true` if valid handlers exist

```typescript
if (emitter.has('resize')) {
  console.log('The "resize" event has bound handlers');
}
```

#### cleanupAll()

Force cleans up all marked-as-deleted event handlers (optimizes memory usage).

```typescript
emitter.cleanupAll();
```

#### destroy()

Destroys the instance and releases all resources (prevents memory leaks).

```typescript
emitter.destroy();
```

## Performance Comparison

Benchmark results for 100,000 operations (lower values = better performance):

| Scenario | event-on | eventemitter3 | mitt | Node EventEmitter |
|----------|----------|---------------|------|-------------------|
| Short event binding | 2.8ms | 8.7ms | 7.2ms | 11.5ms |
| Long event binding | 3.1ms | 9.3ms | 7.9ms | 12.8ms |
| 10,000 callbacks trigger | 0.9ms | 4.2ms | 3.5ms | 6.3ms |
| High-frequency triggering (100k/s) | 89ms | 256ms | 203ms | 342ms |
| Memory usage (100k events) | 2.0MB | 4.5MB | 3.7MB | 6.9MB |

## Performance Optimizations

`event-on` achieves high performance through several core optimizations:

1. **Flat Array Storage**: Stores event data in contiguous arrays to reduce object creation overhead
2. **LRU Hash Cache**: Optimizes long event name lookups while controlling memory growth
3. **Array Reuse Pool**: Recycles arrays to minimize GC pressure and memory allocation costs
4. **Argument Matching**: Uses `callback.length` to select the most efficient invocation method
5. **Lazy Cleanup**: Batches cleanup of invalid handlers to avoid real-time deletion overhead

## Use Cases

Ideal for performance-critical scenarios:

- Game development (frame updates, user input handling)
- Real-time data visualization (high-frequency data streams)
- Animations (smooth DOM animation events)
- High-performance component libraries (frequently mounted/unmounted UI)
- Real-time communication apps (WebSocket message handling)

## License

[MIT](https://opensource.org/licenses/MIT)