🌪️ Zephyr Events

Ultra-fast ES2023 event emitter with 905B bundle size and race-condition safety.

---

⚡ Key Features

• 🔥 Ultra Fast: 33M+ operations/second with native Set/Map optimizations
• 🪶 Tiny Bundle: Only 905B minified, 0 dependencies
• 🛡️ Race-Condition Safe: Immutable snapshots prevent handler modification issues
• 🎯 ES2023 Native: Optional chaining, nullish coalescing, spread operators
• 📦 Tree Shakeable: ES modules with proper exports
• 🔧 TypeScript: Full type safety with generics and strict types

---

📥 Installation

npm install zephyr-events

---

🚀 Quick Start

import zephyrEvents from 'zephyr-events';

// Create typed emitter
type Events = {
  user: { id: number; name: string }
  error: Error
}

const emitter = zephyrEvents<Events>();

// Subscribe with auto-cleanup
const unsubscribe = emitter.on('user', (user) => {
  console.log(`User: ${user.name}`);
});

// Emit events
emitter.emit('user', { id: 1, name: 'Alice' });

// Cleanup
unsubscribe();

---

🎨 API Reference

zephyrEvents<Events>()

Create a new event emitter instance.

const emitter = zephyrEvents<{
  message: string
  data: { value: number }
}>();

emitter.on(type, handler)

Register event handler. Returns unsubscribe function.

const unsub = emitter.on('message', (msg) => {
  console.log(msg);
});

// Wildcard listener
emitter.on('*', (type, event) => {
  console.log(`Event ${type}:`, event);
});

emitter.off(type, handler?)

Remove event handler(s).

// Remove specific handler
emitter.off('message', handler);

// Remove all handlers for type
emitter.off('message');

emitter.emit(type, event)

Emit event to all registered handlers.

emitter.emit('message', 'Hello World!');
emitter.emit('data', { value: 42 });

---

🏗️ Technical Details

Architecture

Zephyr Events uses a dual-storage architecture for maximum performance:

• Set: O(1) add/remove operations
• Array snapshots: Fast iteration with race-condition safety
• ES2023 optimizations: Native optional chaining and nullish coalescing

Race-Condition Safety

Handlers are executed from immutable snapshots:

emitter.on('test', function selfRemover() {
  emitter.off('test', selfRemover); // Safe during emit
});

ES2023 Features

• Nullish coalescing: all ??= new Map()
• Optional chaining: handlers?.size
• Spread operators: [...handlers] for fast snapshots

Bundle Formats

• ESM: dist/zephyr-events.mjs (905B)
• CommonJS: dist/zephyr-events.js (977B)
• UMD: dist/zephyr-events.umd.js (1.3KB)

---

🆚 Comparison

Feature	Zephyr Events	mitt*	eventemitter3
Bundle Size	905B	200B	7KB
TypeScript	✅ Native	✅	✅
Race-Safe	✅	❌	❌
ES2023	✅	❌	❌
Performance	33M ops/s	15M ops/s	10M ops/s

*Based on original mitt package by Jason Miller

---

🚀 Performance Benchmarks

Comprehensive performance benchmarks on Apple Silicon M-series (ARM64) with Node.js v23.10.0:

Core Operations Performance

Operation	Ops/Second	Description
Emitter Creation	10.54M	Creating new emitter instances
Single Handler Emit	33.69M	Emitting to one event handler
Wildcard Emit	26.12M	Emitting to wildcard listeners
10 Handlers Emit	9.32M	Emitting to 10 concurrent handlers
100 Handlers Emit	1.57M	Emitting to 100 concurrent handlers
Mixed Operations	7.17M	Realistic usage: on/emit/off cycle

Management Operations Performance

Operation	Ops/Second	Description
Off Method	194.17M	Removing specific handler with .off()
Unsubscribe	143.54M	Removing handler with returned function
Event Subscription	9.19K	Adding new event handlers with .on()
Memory Stress	130	Complex multi-event scenario

Key Performance Insights

• 🔥 Ultra-fast emission: Up to 33.69M operations/second for single handlers
• ⚡ Instant cleanup: Handler removal at 194.17M operations/second
• 📈 Scales efficiently: Maintains high performance with multiple handlers
• 🛡️ Race-condition safe: Minimal overhead for safety guarantees
• 🎯 Real-world optimized: 7.17M ops/sec for typical usage patterns

Architecture Benefits

• Dual Storage: Set for O(1) add/remove + Array snapshots for fast iteration
• ES2023 Native: Optional chaining (?.) and nullish coalescing (??) optimizations
• Memory Efficient: Stable performance under stress conditions
• Zero Dependencies: Pure JavaScript with no external overhead

---

🙏 Acknowledgments

Zephyr Events is a heavy modernization and performance upgrade of the original mitt package by Jason Miller. Thanks for the foundational work!

---

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md.

📄 License

MIT © ebogdum

Original mitt: MIT © Jason Miller