DEV Community: mi-inu

If You Handle Enter, Check event.isComposing

mi-inu — Tue, 30 Sep 2025 14:03:49 +0000

TL;DR: Your Enter key handler is broken for 1.6 billion people using IME (Input Method Editor). When we press Enter to select a character during text conversion, your chat app sends a half-written message. Fix it with event.isComposing check. Please. We're begging you.

Hey there, I'm Japanese.

In Japan, we're basically taught from elementary school that suppressing anger and being polite is a virtue, so we develop this wonderful habit of bottling everything up until we absolutely explode. But today I've had a few drinks, so let me be honest with you.

There's a reason almost every East Asian is pissed off at you ASCII-language developers.

AI chat is all the rage these days, right? And when you think "chat," the normal UI is: press Enter in the text field, message sends. Simple. So you write something like this:

import React, { useCallback, useRef } from 'react';

export function InputField({ onSubmit }) {
  const el = useRef();
  const handleKeydown = useCallback(
    event => {
      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      }
    },
    [onSubmit]
  );

  return <input ref={el} onKeyDown={handleKeydown} />;
}

Yeah, that's it. Simple, clean, perfectly bug-free implementation. It passes your tests, passes E2E, passes QA, gets deployed. And then East Asians lose their minds completely.

Why?

IME. Input Method Editor. Conversion. Composition. Whatever you want to call this nightmare.

I'm Japanese, so let me explain Japanese. We use hiragana, katakana, and about 2,000 commonly-used kanji characters. Meanwhile, your typical keyboard has what, 104 keys?

Obviously not enough. A-Z gives you 26 characters, but あ through ん alone is 46 characters. Why the hell do we use so many characters? Because Japanese people wanted to pack every ounce of emotion into their text. "Yoroshiku" (よろしく), "YOROSHIKU" (ヨロシク), "Yoroshiku" (宜しく), and "YO-RO-SHI-KU" (夜露死苦) all read as "yo-ro-shi-ku." よろしく is orthodox and friendly. ヨロシク means the person is either quirky or keeping their distance. 宜しく? That's a middle-aged salaryman. 夜露死苦? That's definitely a punk-fashion kid wreaking havoc on a huge motorcycle.

Anyway, Japanese people care deeply about character representation even for the same sounds.

So first, we type in ASCII to get phonetic hiragana, then we select from candidate characters that match those sounds.

This image shows exactly what's happening during composition. The underlined part is unconfirmed text, with candidates shown below. It even thoughtfully shows similar emoji and the meaning of each kanji character.

To select the next candidate down, here's the key sequence visualized:

y o r o s h i k u [Space] [Enter]

During conversion, we use [Up] [Down] [Space] [Enter] [Esc] keys.
This happens roughly every 1-3 words. Multiple times per minute of typing.

The Nightmare in Action

Now, let's look back at that first implementation:

import React, { useCallback, useRef } from 'react';

export function InputField({ onSubmit }) {
  const el = useRef();
  const handleKeydown = useCallback(
    event => {
      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      }
    },
    [onSubmit]
  );

  return <input ref={el} onKeyDown={handleKeydown} />;
}

What happens when you implement this? Simple. The moment we try to select a character variant, the message sends.
It's like sending "I " or "Describe this" or "Hi, I'm " in English.
And since most chat apps reset the input field on send, our sentence never gets completed. So Japanese users quietly seethe with rage, open Sublime Text, and start typing there instead.

This happens in SO MANY services originating from ASCII-land. I've sent bug reports and fixes to countless services, but it never ends. Claude Code's 9/30 update had this exact problem, and tons of Japanese users are pissed.

Here's another fun example.
Let's say you want to pick up input values and save them. Debounce the keydown event and save after xx ms. Simple, innocent logic.

import React, { useCallback, useRef, useEffect } from 'react';

export function InputField({ onSubmit, onSave }) {
  const el = useRef();
  const timeoutRef = useRef();

  const handleKeydown = useCallback(
    event => {
      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      } else {
        clearTimeout(timeoutRef.current);
        timeoutRef.current = setTimeout(() => {
          onSave(el.current.value);
        }, 2000);
      }
    },
    [onSubmit, onSave]
  );

  useEffect(() => {
    return () => clearTimeout(timeoutRef.current);
  }, []);

  return <input ref={el} onKeyDown={handleKeydown} />;
}

This doesn't cause problems by itself. But when upstream re-rendering happens and the element gets destroyed and recreated, absolute chaos ensues. Mid-conversion, the text suddenly disappears and reverts to an earlier state, or you get garbage hiragana stuck in the field. This actually happened in ChatGPT's macOS app.

Writing is thought organization and output. These subtle harassment-level UX issues completely destroy a product's appeal.

ASCII-language folks can't know this, can't notice this. That's why I'm writing this article today—we need to keep speaking up about this.

The Fix That Will Save You From 1.6 Billion Enemies

So how do we fix this? There's this incredibly convenient property called event.isComposing.
It tells you if conversion is happening right now. Simple bugs like saving mid-conversion can be prevented with this.

export function InputField({ onSubmit, onSave }) {
  const el = useRef();
  const timeoutRef = useRef();

  const handleKeydown = useCallback(
    event => {
      clearTimeout(timeoutRef.current);
      if (event.nativeEvent.isComposing) {
        return ;
      }

      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      } else {  
        timeoutRef.current = setTimeout(() => {
          onSave(el.current.value);
        }, 2000);
      }
    },
    [onSubmit, onSave]
  );

  useEffect(() => {
    return () => clearTimeout(timeoutRef.current);
  }, []);

  return <input ref={el} onKeyDown={handleKeydown} />;
}

The Safari Special Hell Edition

But isComposing has a huge problem: in Safari, it becomes false on the keydown event the moment Enter is pressed. This behavior has been ignored for ages, and if any Apple engineers are reading this, please create an issue immediately.

Anyway, there's a proper way to work around this and a cheap trick. The easy one: during IME conversion, the keyCode for Enter becomes 229 instead of 13.

import React, { useCallback, useRef } from 'react';

export function InputField({ onSubmit }) {
  const el = useRef();
  const handleKeydown = useCallback(
    event => {
      if (event.nativeEvent.isComposing || event.nativeEvent.keyCode === 229) {
        return ;
      }

      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      }
    },
    [onSubmit]
  );

  return <input ref={el} onKeyDown={handleKeydown} />;
}

Or, more complex but modern approach:

import React, { useCallback, useRef } from 'react';

export function InputField({ onSubmit }) {
  const el = useRef();
  const isComposingRef = useRef(false);

  const handleKeydown = useCallback(
    event => {
      if (isComposingRef.current) {
        return ;
      }

      if (event.key === 'Enter') {
        onSubmit(el.current.value);
      }
    },
    [onSubmit]
  );

  const handleCompositionStart = useCallback(() => {
    isComposingRef.current = true;
  }, []);

  const handleCompositionEnd = useCallback(() => {
    isComposingRef.current = false;
  }, []);

  return (
    <input 
      ref={el} 
      onKeyDown={handleKeydown}
      onCompositionStart={handleCompositionStart}
      onCompositionEnd={handleCompositionEnd}
    />
  );
}

Please, For the Love of All That Is Holy

That's it. That's literally it. This tiny bit of code prevents you from earning the hatred of 1.6 billion East Asians.

Don't capture Enter, Esc, Up, or Down during isComposing. Just that. That's all it takes to save countless people from suffering.

Oh, and by the way—Slack and Discord figured this out years ago. But somehow every new service steps on the exact same rake. Chinese developers with Pinyin input and Korean developers with Hangul composition are screaming alongside us.

Go add this to your project's AGENTS.md right now: "When handling Enter in text fields, reference isComposing with Safari considerations." Better yet, add to your QA checklist: "When processing Enter, test with multi-byte character IME."

This is all we East Asians wanted to say.
I'm dead serious. Please.

P.S. After reading this article, go buy coffee for the East Asian developer sitting next to you. They're probably silently patching your code as we speak.

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

mi-inu — Sun, 30 Mar 2025 05:29:59 +0000

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<PayloadType>()). 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<PayloadType>()) 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<T>()` (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<T>(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> | void) and emit(args: T): Promise<void> returns a Promise that resolves when all listeners complete.

`monoRestrict<T>()` (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<T>(options?: { parallel?: boolean })` (Asynchronous, Restricted Emission)

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

Decorators

monoDebounce<F extends Function>(func: F, wait: number): F: Creates a debounced version of func.
monoThrottle<F extends Function>(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!