Beyond EventEmitter: Introducing `mono-event` for Simpler, Stricter Event Management

1. Introduction: The Event Handling Headache Ever found yourself wrestling with JavaScript or TypeScript event systems? Maybe you've been bitten by runtime errors because an event payload wasn't what you expected (any strikes again!). Or perhaps you've spent too long debugging memory leaks caused by forgotten listeners. Traditional approaches like Node.js's EventEmitter or DOM Events are powerful, but they often come with trade-offs: verbosity, potential type safety issues, and sometimes, performance bottlenecks. If these frustrations sound familiar, you're in the right place. Meet mono-event, a minimal, type-safe, single-event management library designed to bring clarity, safety, and impressive performance to your event handling code. Inspired by the simplicity of C# events, mono-event focuses on doing one thing well: managing individual events with an intuitive API, strong typing, and excellent performance characteristics. The Core Promise: mono-event delivers compile-time type safety, a minimal API, balanced performance, flexible listener management, and robust emission control, all in a tiny package. 2. Why We Need a Better Way: Problems with Existing Solutions While libraries like EventEmitter3 or native EventTarget are widely used, they can introduce subtle challenges in modern TypeScript projects: The any Trap: Standard EventEmitters often rely on string-based event names and untyped payloads. This forces developers into defensive type checking or resorting to any, sacrificing the benefits of TypeScript and opening the door to runtime errors. // Potential runtime error if 'data' is not a string eventEmitter.on('userLoggedIn', (data: any) => { console.log(`Welcome, ${data.toUpperCase()}!`); // Oops! What if data is a number? }); Listener Management Complexity: Manually managing addListener/removeListener or on/off can be verbose and error-prone. Forgetting to remove listeners is a common source of memory leaks, especially in dynamic applications or component lifecycles. Accidental Emissions: When the emit method is widely accessible, any part of the codebase can potentially trigger an event, sometimes unintentionally. This can make debugging complex interactions difficult and violate encapsulation principles. Performance Considerations: While often fast enough, high-throughput scenarios or applications with frequent event emissions and listener changes can sometimes reveal performance bottlenecks in traditional event systems. mono-event was built specifically to address these pain points head-on. 3. Introducing mono-event: Simple, Safe, and Fast mono-event is built on a philosophy of minimalism, type safety, and balanced performance. A key design principle differentiating mono-event is its "one event, one instance" approach. Unlike traditional event emitters that manage multiple named events within a single instance (often leading to stringly-typed APIs and potential any pitfalls), mono-event requires you to create a distinct instance for each specific type of event. This instance itself carries the event's payload type information via generics (mono()). This fundamental design choice is what enables inherent compile-time type safety for both emitting and listening, eliminating a whole class of runtime errors common with string-based event systems. It also contributes to the library's minimal and focused API surface. Key Features: Minimal API: Easily add, remove, and emit events with just a few core functions (add, remove, removeAll, emit). Compile-Time Type Safety: Leverage TypeScript generics (mono()) to ensure event data types are checked at compile time, catching errors before they hit production. import { mono } from 'mono-event'; // Declare the event payload type explicitly const userLoginEvent = mono(); userLoginEvent.add((payload) => { // 'payload' is correctly typed here! console.log(`User ${payload.userId} logged in at ${payload.timestamp}`); // console.log(payload.userName); // Compile-time error! Property 'userName' does not exist. }); userLoginEvent.emit({ userId: 'user-123', timestamp: new Date() }); // userLoginEvent.emit({ userId: 'user-456' }); // Compile-time error! Missing 'timestamp'. Balanced Performance: Designed with a focus on balancing overall performance, memory usage, and bundle size, providing excellent results in practical use cases. (More on this in the Performance section!) Tiny Bundle Size: Only 4.08 KB minified (1.05 KB gzipped), adding minimal overhead to your project. Synchronous / Asynchronous Support: Choose between mono (synchronous) and monoAsync (asynchronous) versions. With monoAsync, you can even control whether async listeners run sequentially (default) or in parallel. Emission Control Separation: Use monoRestrict and monoRestrictAsync to separate the responsibilities of event registration (add/remove) and event emission (emit). This is great for enforcing architectural patterns where only s

Mar 30, 2025 - 07:07

Beyond EventEmitter: Introducing `mono-event` for Simpler, Stricter Event Management

1. Introduction: The Event Handling Headache

Ever found yourself wrestling with JavaScript or TypeScript event systems? Maybe you've been bitten by runtime errors because an event payload wasn't what you expected (any strikes again!). Or perhaps you've spent too long debugging memory leaks caused by forgotten listeners. Traditional approaches like Node.js's EventEmitter or DOM Events are powerful, but they often come with trade-offs: verbosity, potential type safety issues, and sometimes, performance bottlenecks.

If these frustrations sound familiar, you're in the right place. Meet mono-event, a minimal, type-safe, single-event management library designed to bring clarity, safety, and impressive performance to your event handling code. Inspired by the simplicity of C# events, mono-event focuses on doing one thing well: managing individual events with an intuitive API, strong typing, and excellent performance characteristics.

The Core Promise: mono-event delivers compile-time type safety, a minimal API, balanced performance, flexible listener management, and robust emission control, all in a tiny package.

2. Why We Need a Better Way: Problems with Existing Solutions

While libraries like EventEmitter3 or native EventTarget are widely used, they can introduce subtle challenges in modern TypeScript projects:

The any Trap: Standard EventEmitters often rely on string-based event names and untyped payloads. This forces developers into defensive type checking or resorting to any, sacrificing the benefits of TypeScript and opening the door to runtime errors.
```
// Potential runtime error if 'data' is not a string
eventEmitter.on('userLoggedIn', (data: any) => {
  console.log(`Welcome, ${data.toUpperCase()}!`); // Oops! What if data is a number?
});
```
Listener Management Complexity: Manually managing addListener/removeListener or on/off can be verbose and error-prone. Forgetting to remove listeners is a common source of memory leaks, especially in dynamic applications or component lifecycles.
Accidental Emissions: When the emit method is widely accessible, any part of the codebase can potentially trigger an event, sometimes unintentionally. This can make debugging complex interactions difficult and violate encapsulation principles.
Performance Considerations: While often fast enough, high-throughput scenarios or applications with frequent event emissions and listener changes can sometimes reveal performance bottlenecks in traditional event systems.

mono-event was built specifically to address these pain points head-on.

3. Introducing `mono-event`: Simple, Safe, and Fast

mono-event is built on a philosophy of minimalism, type safety, and balanced performance.

A key design principle differentiating mono-event is its "one event, one instance" approach. Unlike traditional event emitters that manage multiple named events within a single instance (often leading to stringly-typed APIs and potential any pitfalls), mono-event requires you to create a distinct instance for each specific type of event.

This instance itself carries the event's payload type information via generics (mono()). This fundamental design choice is what enables inherent compile-time type safety for both emitting and listening, eliminating a whole class of runtime errors common with string-based event systems. It also contributes to the library's minimal and focused API surface.

Key Features:

Minimal API: Easily add, remove, and emit events with just a few core functions (add, remove, removeAll, emit).

Compile-Time Type Safety: Leverage TypeScript generics (mono()) to ensure event data types are checked at compile time, catching errors before they hit production.

import { mono } from 'mono-event';

// Declare the event payload type explicitly
const userLoginEvent = mono<{ userId: string; timestamp: Date }>();

userLoginEvent.add((payload) => {
  // 'payload' is correctly typed here!
  console.log(`User ${payload.userId} logged in at ${payload.timestamp}`);
  // console.log(payload.userName); // Compile-time error! Property 'userName' does not exist.
});

userLoginEvent.emit({ userId: 'user-123', timestamp: new Date() });
// userLoginEvent.emit({ userId: 'user-456' }); // Compile-time error! Missing 'timestamp'.

Balanced Performance: Designed with a focus on balancing overall performance, memory usage, and bundle size, providing excellent results in practical use cases. (More on this in the Performance section!)
Tiny Bundle Size: Only 4.08 KB minified (1.05 KB gzipped), adding minimal overhead to your project.
Synchronous / Asynchronous Support: Choose between mono (synchronous) and monoAsync (asynchronous) versions. With monoAsync, you can even control whether async listeners run sequentially (default) or in parallel.
Emission Control Separation: Use monoRestrict and monoRestrictAsync to separate the responsibilities of event registration (add/remove) and event emission (emit). This is great for enforcing architectural patterns where only specific parts of your system should trigger an event.
Flexible Listener Registration: Register listeners simply, with a caller context (this), or use the { once: true } option for one-time event handling. The add method conveniently returns an unsubscribe function.
Comprehensive Listener Management: Remove listeners by reference, by caller context, or remove all listeners at once with removeAll().

4. Getting Hands-On: How to Use `mono-event`

Let's see mono-event in action.

Installation

# npm
npm install mono-event

# yarn
yarn add mono-event

# bun
bun add mono-event

# Deno (via npm specifier or esm.sh)
import { mono } from "npm:mono-event";
// or
import { mono } from "https://esm.sh/mono-event";

Example 1: Basic Synchronous Events (`mono`)

import { mono } from 'mono-event';

// Create an event that carries a string payload
const messageEvent = mono<string>();

// 1. Register a simple listener (returns an unsubscribe function)
const unsubscribeSimple = messageEvent.add((msg) => {
  console.log("Simple listener received:", msg);
});

// 2. Register a listener bound to a class instance (caller context)
class MessageHandler {
  lastMessage = '';
  handleEvent(msg: string) {
    this.lastMessage = msg;
    console.log("Handler instance received:", msg, "| Last:", this.lastMessage);
  }
}
const handler = new MessageHandler();
const unsubscribeHandler = messageEvent.add(handler, handler.handleEvent);

// 3. Register a one-time listener
messageEvent.add((msg) => {
  console.log("One-time listener received:", msg);
}, { once: true });

// Emit the event
console.log("Emitting 'Hello, Dev.to!'...");
messageEvent.emit("Hello, Dev.to!");
// Output:
// Simple listener received: Hello, Dev.to!
// Handler instance received: Hello, Dev.to! | Last: Hello, Dev.to!
// One-time listener received: Hello, Dev.to!

console.log("\nEmitting 'Second Message'...");
messageEvent.emit("Second Message");
// Output:
// Simple listener received: Second Message
// Handler instance received: Second Message | Last: Second Message
// (One-time listener does not fire again)

// Remove listeners
unsubscribeSimple(); // Using the returned function
messageEvent.remove(handler, handler.handleEvent); // By reference

console.log("\nEmitting 'Third Message' (after removals)...");
messageEvent.emit("Third Message");
// Output: (No listeners left)

// Add some listeners back and remove all
messageEvent.add((msg) => console.log("Listener A"));
messageEvent.add((msg) => console.log("Listener B"));
messageEvent.removeAll();
console.log("\nEmitting 'Fourth Message' (after removeAll)...");
messageEvent.emit("Fourth Message");
// Output: (No listeners left)

Example 2: Handling Asynchronicity (`monoAsync`)

Need to perform async operations in your listeners? monoAsync has you covered.

import { monoAsync } from 'mono-event';
import { setTimeout } from 'timers/promises'; // Node.js example

// Event carrying a number payload
const processingEvent = monoAsync<number>(); // Async listeners run sequentially by default

// Register async listeners
processingEvent.add(async (num) => {
  console.log(`Async Listener 1: Starting processing ${num}...`);
  await setTimeout(500); // Simulate async work
  console.log(`Async Listener 1: Finished processing ${num}.`);
});

class AsyncProcessor {
  async processData(num: number) {
    console.log(`Async Processor: Starting work on ${num}...`);
    await setTimeout(300);
    console.log(`Async Processor: Done with ${num}.`);
  }
}
const processor = new AsyncProcessor();
processingEvent.add(processor, processor.processData);

// Emit the event and wait for all sequential listeners to complete
console.log("Emitting 42 (Sequential)...");
await processingEvent.emit(42);
console.log("Sequential emission complete.");
// Output (order guaranteed):
// Async Listener 1: Starting processing 42...
// Async Listener 1: Finished processing 42.
// Async Processor: Starting work on 42...
// Async Processor: Done with 42.
// Sequential emission complete.

// Now, let's try parallel execution
const parallelEvent = monoAsync<string>({ parallel: true });

parallelEvent.add(async (id) => {
  console.log(`Parallel 1 (${id}): Starting (500ms)`);
  await setTimeout(500);
  console.log(`Parallel 1 (${id}): Finished`);
});
parallelEvent.add(async (id) => {
  console.log(`Parallel 2 (${id}): Starting (300ms)`);
  await setTimeout(300);
  console.log(`Parallel 2 (${id}): Finished`);
});

console.log("\nEmitting 'Task-A' (Parallel)...");
await parallelEvent.emit("Task-A");
console.log("Parallel emission complete.");
// Output (order depends on timing, but they run concurrently):
// Parallel 1 (Task-A): Starting (500ms)
// Parallel 2 (Task-A): Starting (300ms)
// Parallel 2 (Task-A): Finished
// Parallel 1 (Task-A): Finished
// Parallel emission complete.

Example 3: Encapsulating Emission (`monoRestrict` / `monoRestrictAsync`)

Want to control who can trigger an event? monoRestrict separates the ability to add/remove listeners (event) from the ability to trigger the event (emit).

import { monoRestrict } from 'mono-event';

// Imagine this is inside a class or module that manages state
class DataService {
  // Create the restricted event
  private readonly _onDataUpdate = monoRestrict<string[]>();

  // Expose only the 'event' part publicly for listeners
  public get onDataUpdate() {
    return this._onDataUpdate.event;
  }

  private data: string[] = [];

  // Internal method that can emit the event
  private fetchData() {
    // Simulate fetching data
    this.data = ["apple", "banana", "cherry"];
    console.log("Data fetched, emitting update...");
    // Only code with access to _onDataUpdate.emit can trigger it
    this._onDataUpdate.emit(this.data);
  }

  // Public method to initiate the process
  public refreshData() {
    this.fetchData();
  }
}

// --- Code outside the DataService ---
const service = new DataService();

// External code can *only* add/remove listeners
service.onDataUpdate.add((newData) => {
  console.log("External Listener: Data updated!", newData);
});

// Attempting to emit from outside fails (compile-time error in TS)
// service.onDataUpdate.emit(["fake data"]); // Error: Property 'emit' does not exist on type...

// Trigger the data fetch, which will internally emit the event
service.refreshData();
// Output:
// Data fetched, emitting update...
// External Listener: Data updated! [ 'apple', 'banana', 'cherry' ]

// The async version `monoRestrictAsync` works similarly.

Example 4: Using Decorators (`monoDebounce`, `monoThrottle`)

mono-event provides handy utilities for common patterns like debouncing and throttling event handlers.

import { mono, monoDebounce, monoThrottle } from 'mono-event';
import { setTimeout } from 'timers/promises';

const inputEvent = mono<string>();
const waitMs = 500;

// Debounced: Executes only *after* 500ms of inactivity
const debouncedHandler = monoDebounce((text: string) => {
  console.log(`[Debounced] Processing: ${text}`);
}, waitMs);

// Throttled: Executes at most *once* every 500ms (leading + trailing edge)
const throttledHandler = monoThrottle((text: string) => {
  console.log(`[Throttled] Handling: ${text}`);
}, waitMs);

inputEvent.add(debouncedHandler);
inputEvent.add(throttledHandler);

console.log("Simulating rapid input...");
inputEvent.emit('A'); // Throttle runs immediately (leading edge)
await setTimeout(100);
inputEvent.emit('AB');
await setTimeout(100);
inputEvent.emit('ABC'); // Debounce timer resets
await setTimeout(600); // Wait long enough for debounce & throttle trailing edge
console.log("Input simulation finished.");

// Expected Output (approximate):
// Simulating rapid input...
// [Throttled] Handling: A
// (after ~600ms pause)
// [Debounced] Processing: ABC
// [Throttled] Handling: ABC  (trailing edge)
// Input simulation finished.

5. API Overview

Here's a quick reference for the main functions:

`mono()` (Synchronous)

Returns: An object with methods:
- add(handler: (args: T) => void, options?: { once?: boolean }): () => void
- add(caller: object, handler: (args: T) => void, options?: { once?: boolean }): () => void
- remove(handler: (args: T) => void): boolean
- remove(caller: object, handler: (args: T) => void): boolean
- removeAll(): void
- emit(args: T): void

`monoAsync(options?: { parallel?: boolean })` (Asynchronous)

Options: parallel (boolean, default false): Run async listeners in parallel if true.
Returns: An object with methods similar to mono, but handlers can be async ((args: T) => Promise | void) and emit(args: T): Promise returns a Promise that resolves when all listeners complete.

`monoRestrict()` (Synchronous, Restricted Emission)

Returns: { event, emit }
- event: Object with add, remove, removeAll (like mono).
- emit(args: T): void: A standalone function to trigger the event.

`monoRestrictAsync(options?: { parallel?: boolean })` (Asynchronous, Restricted Emission)

Returns: { event, emit }
- event: Object with add, remove, removeAll (like monoAsync).
- emit(args: T): Promise: A standalone async function to trigger the event.

Decorators

monoDebounce(func: F, wait: number): F: Creates a debounced version of func.
monoThrottle(func: F, wait: number): F: Creates a throttled version of func.

6. Performance Deep Dive: The Numbers Don't Lie

mono-event is designed for a balance of speed, memory efficiency, and bundle size. Here's how it stacks up against popular alternatives based on recent benchmarks:

(Benchmark environment: macOS, Apple M2 Ultra. Results are average of 3 runs. See docs/performance in the repo for full details and methodology.)

Performance Summary (Node.js)

Library	Init (ms)	Register (Single) (ms)	Register (Multi) (ms)	Removal (Fwd) (ms)	Removal (Bwd) (ms)	Removal (Rnd) (ms)	Emit (ms)	Emit Once (ms)	Memory (Empty) (KB/inst)	Memory (100 Listeners) (KB/inst)	Comprehensive (ms)
mono-event	5.76	6.17	6.04	7.35	75.13	49.36	205.42	1.12	0.13	8.44	1977.62
Restrict	-	-	-	-	-	-	209.24	-	-	-	-
EventEmitter3	3.99	1.72	2.86	218.14	210.16	238.02	240.84	224.64	0.09	7.33	1936.56
mitt	58.50	3.85	8.18	6.09	10.68	9.01	217.67	6.31	0.49	2.94	1999.64
nanoevents	2.84	3.85	1.68	220.79	172.63	178.82	164.89	186.16	0.23	13.49	1341.75
RxJS	4.44	41.54	79.27	10.73	12.67	12.83	372.83	9.33	0.15	52.50	5047.33
Node Events	101.13	2.64	30.17	58.35	1.95	64.40	237.65	119.43	0.28	5.76	1651.50
EventTarget	164.45	12229.94	48.62	156.30	311.80	262.19	318.72	339.96	0.44	9.34	2735.08

Performance Summary (Bun)

Library	Init (ms)	Register (Single) (ms)	Register (Multi) (ms)	Removal (Fwd) (ms)	Removal (Bwd) (ms)	Removal (Rnd) (ms)	Emit (ms)	Emit Once (ms)	Comprehensive (ms)
mono-event	2.38	4.59	12.91	88.04	0.67	58.90	121.48	0.86	696.29
Restrict	-	-	-	-	-	-	126.51	-	-
EventEmitter3	1.98	1.43	4.88	178.34	152.54	195.17	132.41	160.25	992.84
mitt	23.35	0.77	2.89	6.35	9.94	9.64	180.11	5.94	2197.11
nanoevents	2.20	1.47	2.91	158.35	152.67	182.38	136.22	160.28	1259.63
RxJS	42.25	12.16	15.99	7.36	11.22	11.83	205.36	6.57	2005.92
Node Events	118.95	1.28	4.19	60.20	0.91	34.83	145.26	75.15	989.63
EventTarget	566.28	13155.77	34.42	127.79	252.76	204.71	1164.29	132.11	12307.24

Memory Usage Summary (Node.js)

Library	Per Instance (KB)	With 10,000 Handlers (KB)	1,000 Events × 100 Instances (KB)	1,000,000 Instances (Total KB)
mono-event	0.09	1,786.47	-	282,977.47
EventEmitter3	0.09	733.39	5,366.01	166,269.33
mitt	0.31	260.34	2,366.6	527,172.73
nanoevents	0.24	1,338.14	19,156.15	405,540.1
RxJS	0.13	6,658.26	73,713.15	767,824.14
Node Events	0.12	277.9	91.51	249,870.11
EventTarget	0.27	1,046.12	-	537,181.27

Analysis: How mono-event Achieves its Speed (and Trade-offs)

Optimized Internals: mono-event uses simple JavaScript Arrays to store listeners ({ h: handler, c: caller } objects). Operations like add (push), remove (splice after a linear search), and emit (iterating over array copies) are highly optimized by modern JavaScript engines.
Efficient once Handling: One-time listeners ({ once: true }) are managed in a dedicated internal array (onceListeners). When emit occurs, these listeners are executed and then efficiently removed to prevent subsequent calls. (Internally, this involves splice for synchronous/sequential async modes, and array copying followed by clearing (length = 0) for parallel async mode). This optimization ensures safe and fast handling of once listeners, contributing significantly to the performance gains seen in Emit Once benchmarks, especially in parallel async scenarios.
Prototype Sharing: Methods like add, remove, etc., are shared via prototype objects (Object.create()), reducing the memory footprint and initialization cost for each event instance.
Memory vs. Speed: Storing listeners in simple arrays means memory usage generally scales linearly with the number of listeners. While often acceptable, this can lead to higher memory consumption compared to libraries using more complex internal structures (like Maps per event name) when dealing with a very large number of listeners per instance. This is an intentional trade-off favoring the speed of operations like Emit Once and remove.

When Does mono-event Excel?

High-frequency event emissions.
Heavy use of one-time (once) listeners.
Scenarios where listener removal performance is critical.
Applications where compile-time type safety is paramount.
Architectures benefiting from clear separation of emission control (monoRestrict).

Reproducibility:

You can run the benchmarks yourself! Clone the repository, install dev dependencies, build, and run:

# In the mono-event project directory
npm install eventemitter3 mitt nanoevents rxjs --save-dev # Install benchmark deps
npm run build

# Run with Node.js (all tests)
node --expose-gc docs/performance/benchmark.js
# Run specific tests (e.g., Emit and Comprehensive)
node --expose-gc docs/performance/benchmark.js 7 11

# Run with Bun (Memory results may vary)
bun --gc-expose docs/performance/benchmark.js

# Run with Deno (Memory results may vary)
deno run --import-map deno.importmap.json --allow-net --allow-read --allow-env docs/performance/benchmark.js

7. Use Cases & Considerations

So, when should you reach for mono-event? It shines in scenarios where:

Type Safety is Paramount: If you're tired of any and want compile-time guarantees for your event payloads in TypeScript.
Simplicity is Key: You need basic, reliable event subscription and emission without the complexity of reactive streams (like RxJS).
Controlled Emission is Desired: You want to enforce clear architectural boundaries using monoRestrict to control who can trigger events.
once Listeners are Frequent: The optimized handling of one-time listeners offers performance benefits.
Debounce/Throttle Utilities are Handy: You need quick access to these common patterns for UI events or other frequent triggers.

More specifically, mono-event is a great fit for:

UI Components/Frameworks: Managing internal state changes or user interactions within components.
State Management: Signaling updates between different parts of your application state.
Game Development: Handling game events like collisions, player actions, or state transitions.
Performance-Sensitive Systems: Anywhere event emission speed or efficient once listeners are crucial.
Modular Architectures: Using monoRestrict to enforce clear boundaries for event emission.
Any TypeScript project where you want robust, type-safe event handling without unnecessary complexity.

However, mono-event might not be the best choice if:

You need complex event stream manipulation (filtering, mapping, combining streams) - RxJS is likely a better fit.
Absolute minimal bundle size is the single most important factor (though mono-event is already very small, mitt or nanoevents are slightly smaller).
You heavily rely on wildcard event listeners or need introspection capabilities not provided by the minimal API.

8. Conclusion & Call to Action

mono-event offers a compelling blend of type safety, performance, simplicity, and control for event management in modern JavaScript and TypeScript applications. By addressing common pain points of traditional event emitters and focusing on a minimal, well-typed API, it helps you write more robust, maintainable, and performant code.

Ready to give it a try?

npm install mono-event

We welcome your feedback, bug reports, and contributions! Check out the project on GitHub:

GitHub Repository: https://github.com/yukimi-inu/mono-event
Contributing Guidelines: CONTRIBUTING.md
Detailed Performance Docs: docs/performance

Let us know what you think in the comments below! Happy coding!