@supercat1337/event-emitter 1.0.12 → 2.0.1

package/README.md

@@ -1,16 +1,21 @@
 # @supercat1337/event-emitter 🐈⚡
 
-A modern, feature-rich EventEmitter implementation for JavaScript and TypeScript with advanced capabilities and excellent type safety.
+A modern, feature-rich EventEmitter implementation for JavaScript and TypeScript with advanced capabilities and industry-leading type safety.
+
+---
 
 ## Features
 
--   ✅ **Full TypeScript support** with generics and complete type definitions
--   🎯 **Promise-based event waiting** with timeout support
--   📊 **Listener lifecycle tracking** - know when events gain/lose listeners
--   🛡️ **Memory safe** - automatic cleanup and unsubscribe functions
--   ⚡ **High performance** - optimized for frequent events
--   🔒 **Immutable patterns** - listener arrays are copied during emission
--   🚀 **Modern ES2022+** - private fields, arrow functions, and more
+- ✅ **Dual Implementation** – Choose between lightweight `EventEmitterLite` or full-featured `EventEmitter`.
+- ✅ **First-class TypeScript** – Deep generic support for event names and argument validation.
+- ✅ **Promise-based Waiting** – Native `waitForEvent` and `waitForAnyEvent` with built-in timeout support.
+- ✅ **Lifecycle Tracking** – Monitor when events gain or lose listeners (`onHasEventListeners`, `onNoEventListeners`).
+- ✅ **Centralized Error Handling** – Intercept and handle listener errors globally via `onListenerError`.
+- ✅ **Memory-Efficient** – Automatic cleanup of unused event keys and dedicated `destroy()` lifecycle.
+- ✅ **Immutable Emission** – Listener arrays are snapshotted during emission, making it safe to modify listeners inside callbacks.
+- ✅ **Modern ES2022+** – Leverages native private fields and optimized logic.
+
+---
 
 ## Installation
 
@@ -18,9 +23,13 @@ A modern, feature-rich EventEmitter implementation for JavaScript and TypeScript
 npm install @supercat1337/event-emitter
 ```
 
+---
+
 ## Quick Start
 
-```javascript
+### Using the full-featured `EventEmitter`
+
+```typescript
 import { EventEmitter } from '@supercat1337/event-emitter';
 
 // Define your event types
@@ -28,7 +37,7 @@ type AppEvents = 'user:created' | 'user:deleted' | 'notification:sent';
 
 const emitter = new EventEmitter<AppEvents>();
 
-// Subscribe to events
+// Subscribe with an auto-generated unsubscribe function
 const unsubscribe = emitter.on('user:created', (userData) => {
     console.log('User created:', userData);
 });
@@ -36,224 +45,167 @@ const unsubscribe = emitter.on('user:created', (userData) => {
 // Emit events
 emitter.emit('user:created', { id: 1, name: 'John' });
 
-// Unsubscribe when done
+// Clean up
 unsubscribe();
 ```
 
-## API Reference
-
-### Core Properties
-
-#### `isDestroyed`
+### Using the lightweight `EventEmitterLite`
 
-Is the event emitter destroyed?
+For performance-critical paths where you only need core `on`/`off`/`emit` logic:
 
 ```javascript
-console.log(emitter.isDestroyed); // false
-emitter.destroy();
-console.log(emitter.isDestroyed); // true
-```
-
-#### `events`
-
-The list of events and their listeners.
+import { EventEmitterLite } from '@supercat1337/event-emitter';
 
-```javascript
-console.log(emitter.events); // { 'user:created': [Function] }
+const lite = new EventEmitterLite();
+lite.on('data', (msg) => console.log(msg));
+lite.emit('data', 'Hello, World!');
 ```
 
-#### `logErrors`
-
-Should errors be logged to the console?
-
-```javascript
-emitter.logErrors = true;
-```
-
-### Core Methods
-
-#### `on(event, listener)`
+---
 
-Subscribe to an event. Returns an unsubscribe function.
+## API Reference
 
-```javascript
-const unsubscribe = emitter.on("user:created", (data) => {
-    console.log(data);
-});
+### Core Classes
 
-// Later...
-unsubscribe();
-```
+#### `EventEmitterLite<Events>`
+The core implementation focused on performance. Use this when you don't need async waiting or lifecycle hooks.
 
-#### `off(event, listener)`
+#### `EventEmitter<Events>`
+Extends `EventEmitterLite` with the full suite of advanced features: async promises, tracking hooks, and instance destruction.
 
-Remove a specific listener from an event.
+### Common Properties
 
-```javascript
-function listener(data) {
-    /* ... */
-}
-emitter.on("user:created", listener);
-emitter.off("user:created", listener);
-```
+| Property      | Type      | Description                                                                                |
+|---------------|-----------|--------------------------------------------------------------------------------------------|
+| `logErrors`   | `boolean` | If `true`, errors in listeners are logged to the console. (Default: `true`)<br>Even when `false`, errors can still be caught via `onListenerError`. |
+| `isDestroyed` | `boolean` | (`EventEmitter` only) Returns `true` if the instance has been destroyed.                   |
 
-#### `emit(event, ...args)`
+### Common Methods
 
-Emit an event with optional arguments.
+| Method                          | Description                                                                           |
+|---------------------------------|---------------------------------------------------------------------------------------|
+| `on(event, listener)`           | Subscribes to an event. Returns an `unsubscribe()` function.                          |
+| `once(event, listener)`         | Subscribes for a single invocation, then auto-removes.                                |
+| `off(event, listener)`          | Removes a specific listener. Alias for `removeListener`.                              |
+| `emit(event, ...args)`          | Triggers all listeners for the event with provided arguments.                         |
+| `removeListener(event, listener)` | Same as `off`.                                                                        |
 
-```javascript
-emitter.emit("user:created", { id: 1, name: "Alice" });
-```
+### Advanced Methods (`EventEmitter` only)
 
-#### `once(event, listener)`
+| Method                                          | Description                                                                                                 |
+|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `waitForEvent(event, [maxWaitMs])`              | Returns a `Promise<boolean>`. Resolves `true` when the event fires. If `maxWaitMs` is reached, resolves `false`. |
+| `waitForAnyEvent(events, [maxWaitMs])`          | Waits for the first occurring event from an array of event names.                                           |
+| `clear()`                                        | Removes all listeners from all events.                                                                      |
+| `clearEventListeners(event)`                     | Removes all listeners for a specific event.                                                                 |
+| `destroy()`                                      | Completely wipes the instance. Clears all listeners and prevents further emissions.                          |
+| `onHasEventListeners(callback)`                  | Invoked when any event gains its **first** listener. Receives the event name.                               |
+| `onNoEventListeners(callback)`                   | Invoked when any event loses its **last** listener. Receives the event name.                                |
+| `onListenerError(callback)`                      | Invoked when any listener throws an error. Receives `(error, eventName, ...args)`.                          |
 
-Add a one-time listener that auto-removes after execution.
+#### Example: lifecycle tracking
 
 ```javascript
-emitter.once("app:ready", () => {
-    console.log("App is ready!");
+emitter.onHasEventListeners((event) => {
+    console.log(`First listener added for ${event}`);
 });
-```
-
-### Advanced Methods
-
-#### `waitForEvent(event, [maxWaitMs])`
-
-Wait for an event using Promises.
-
-```javascript
-// Wait indefinitely
-const result = await emitter.waitForEvent("data:loaded");
-
-// Wait with timeout (returns false if timeout reached)
-const success = await emitter.waitForEvent("data:loaded", 5000);
-```
-
-#### `waitForAnyEvent(events, [maxWaitMs])`
-
-Wait for any of multiple events.
-
-```javascript
-const events = ['success', 'error', 'timeout'] as const;
-const result = await emitter.waitForAnyEvent(events, 3000);
-```
 
-#### `onHasEventListeners(callback)`
-
-Get notified when any event gains its first listener.
-
-```javascript
-emitter.onHasEventListeners((eventName) => {
-    console.log(`Event ${eventName} now has listeners!`);
+emitter.onNoEventListeners((event) => {
+    console.log(`Last listener removed for ${event}`);
 });
-```
-
-#### `onNoEventListeners(callback)`
-
-Get notified when any event loses its last listener.
 
-```javascript
-emitter.onNoEventListeners((eventName) => {
-    console.log(`Event ${eventName} has no more listeners!`);
-});
+emitter.on('foo', () => {}); // logs: First listener added for foo
+emitter.off('foo', () => {}); // logs: Last listener removed for foo
 ```
 
-#### `onListenerError(callback)`
-
-Get notified when any listener throws an error.
+#### Example: error handling
 
 ```javascript
-emitter.onListenerError((error, eventName, ...args) => {
-    console.error(`Listener for event ${eventName} threw an error:`, error);
+emitter.onListenerError((error, event, ...args) => {
+    console.error(`Error in ${event}:`, error);
+    myLoggingService.report(error);
 });
+
+emitter.on('crash', () => { throw new Error('boom'); });
+emitter.emit('crash'); // error is caught, passed to the callback, and (if logErrors=true) also logged.
 ```
 
-### Lifecycle Management
+---
 
-#### `destroy()`
+## TypeScript Usage
 
-Completely destroy the emitter and clean up all resources.
+### 1. Simple string union
+Good for events that don't pass complex data.
 
-```javascript
-emitter.destroy();
-console.log(emitter.isDestroyed); // true
+```typescript
+type MyEvents = 'start' | 'stop' | 'tick';
+const emitter = new EventEmitter<MyEvents>();
+emitter.emit('start'); // OK
+emitter.emit('unknown'); // Type error
 ```
 
-#### `clear()`
-
-Remove all listeners while keeping the emitter functional.
+### 2. Full type safety (recommended)
+Define a record mapping event names to argument tuples. This gives you autocompletion and argument validation.
 
-```javascript
-emitter.clear();
-```
+```typescript
+type MyEvents = {
+    'user:updated': [id: number, name: string];
+    'ping': []; // no arguments
+};
 
-#### `clearEventListeners(event)`
+const emitter = new EventEmitter<MyEvents>();
 
-Remove all listeners for a specific event.
+// Listener gets correct argument types
+emitter.on('user:updated', (id, name) => {
+    console.log(id, name);
+});
 
-```javascript
-emitter.clearEventListeners("user:created");
+// Emit is type-checked
+emitter.emit('user:updated', 1, 'Alice'); // ✅
+emitter.emit('user:updated', '1');        // ❌ Type error
 ```
 
-## TypeScript Usage
+### 3. Using `keyof` with a separate type map
+If you prefer to keep event names as a union but still want argument types, combine a union with a mapped type:
 
 ```typescript
-import { EventEmitter } from "@supercat1337/event-emitter";
-
-// Define your event types
-type MyEvents =
-    | "user:created"
-    | "user:updated"
-    | { type: "user:deleted"; payload: { id: string; reason: string } };
+type EventNames = 'start' | 'stop' | 'tick';
+type EventMap = {
+    [K in EventNames]: K extends 'tick' ? [counter: number] : [];
+};
 
-const emitter = new EventEmitter<MyEvents>();
-
-// Full type safety!
-emitter.emit("user:created", { id: 1, name: "John" }); // ✅ Correct
-emitter.emit("user:created", "invalid"); // ❌ Type error
+const emitter = new EventEmitter<EventMap>();
+emitter.on('tick', (counter) => console.log(counter)); // counter is number
 ```
 
-## Error Handling
+---
 
-All listener errors are caught and logged to console, preventing emitter crashes:
+## Error Handling
 
-```javascript
-emitter.on("data:received", () => {
-    throw new Error("Something went wrong!");
-});
+By default, all listener errors are caught to prevent the emitter from crashing.  
+- If `logErrors` is `true` (default), errors are printed to `console.error`.  
+- Even with `logErrors: false`, you can still intercept errors globally using `onListenerError` for custom logging or reporting.
 
-// Error is caught and logged, emitter continues working
-emitter.emit("data:received");
-```
+---
 
 ## Performance Notes
 
--   🔄 Listener arrays are copied before iteration to allow safe modification during emission
--   ⚡ Event existence checks are optimized with direct property access
--   🗑️ Automatic cleanup prevents memory leaks
--   📏 No external dependencies
+- **Snapshotted iteration**: Listener arrays are copied before emission. If a listener calls `off()` on itself during emission, the current cycle continues safely without skipping elements.
+- **Zero dependencies**: Ultra-small bundle size.
+- **Memory management**: Event keys are deleted from the internal store when the last listener is removed, reducing memory usage over time.
+
+---
 
 ## Browser Support
 
 | Feature    | Support         |
-| ---------- | --------------- |
+|------------|-----------------|
 | ES2022+    | Modern browsers |
 | TypeScript | 4.0+            |
 | Node.js    | 14+             |
 
-## License
-
-MIT License - feel free to use in commercial projects.
-
-## Contributing
-
-Contributions welcome! Please ensure:
-
--   ✅ All tests pass
--   ✅ TypeScript types are maintained
--   ✅ New features include tests
--   ✅ Code follows existing style
-
 ---
 
-**Made with ❤️ by [supercat1337](https://github.com/supercat1337)**
+## License
+
+MIT © [supercat1337](https://github.com/supercat1337)

package/index.d.ts

@@ -1,2 +1,2 @@
-export { EventEmitter } from "./dist/event-emitter.esm.js";
-//# sourceMappingURL=index.d.ts.map
+export { EventEmitterLite } from "./src/event-emitter-lite.js";
+export { EventEmitter } from "./src/event-emitter.js";

package/index.js

@@ -1,2 +1,3 @@
 // @ts-check
-export { EventEmitter } from "./dist/event-emitter.esm.js";
+export { EventEmitterLite } from './src/event-emitter-lite.js';
+export { EventEmitter } from './src/event-emitter.js';

package/package.json

@@ -1,32 +1,57 @@
 {
     "name": "@supercat1337/event-emitter",
-    "version": "1.0.12",
-    "description": "Event Emitter",
+    "version": "2.0.1",
+    "description": "Lightweight typed event emitter with Symbol support, one-time listeners, and zero dependencies. Works in Node.js and browsers.",
     "main": "index.js",
+    "type": "module",
+    "exports": {
+        ".": "./index.js",
+        "./package.json": "./package.json"
+    },
+    "types": "./index.d.ts",
+    "files": [
+        "index.js",
+        "index.d.ts",
+        "src/**/*.js",
+        "src/**/*.d.ts"
+    ],
     "scripts": {
         "test": "c8 ava",
-        "build": "npm run remove_type_files && npm run build_esm && npm run build_esm_min && npm run create_types",
-        "build_esm": "rollup ./src/index.js --file ./dist/event-emitter.esm.js --format es",
-        "build_esm_min": "esbuild --minify --bundle --platform=neutral --legal-comments=none ./src/index.js --outfile=./dist/event-emitter.esm.min.js",
-        "create_types": "npx -p typescript tsc --project my.tsconfig.types.json",
-        "remove_type_files": "del /q *.d.ts *.d.ts.map && cd dist && del /s /q *.d.ts *.d.ts.map && cd ../src && del /s /q *.d.ts *.d.ts.map && cd .."
+        "clean": "shx rm -f *.d.ts *.d.ts.map && shx rm -rf src/**/*.d.ts src/**/*.d.ts.map",
+        "build:types": "npm run clean && tsc --project my.tsconfig.types.json"
     },
-    "author": "Supercat",
+    "keywords": [
+        "event",
+        "emitter",
+        "eventemitter",
+        "event-emitter",
+        "typed",
+        "typescript",
+        "symbols",
+        "lightweight",
+        "tiny",
+        "zero-dependencies",
+        "browser",
+        "node",
+        "events",
+        "pubsub",
+        "observer"
+    ],
+    "author": "Albert Bazaleev",
     "license": "MIT",
     "devDependencies": {
+        "@types/node": "^20.12.2",
         "ava": "^6.1.2",
         "c8": "^9.1.0",
-        "esbuild": "^0.20.2",
-        "@types/node": "^20.12.2"
+        "shx": "^0.4.0",
+        "typescript": "^5.4.3"
     },
-    "type": "module",
-    "moduleResolution": "nodenext",
-    "keywords": [
-        "typed event emitter",
-        "typed event bus"
-    ],
     "publishConfig": {
         "registry": "https://registry.npmjs.org"
     },
-    "homepage": "https://github.com/supercat1337/event-emitter"
+    "homepage": "https://github.com/supercat1337/event-emitter",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/supercat1337/event-emitter.git"
+    }
 }

package/src/event-emitter-lite.d.ts

@@ -0,0 +1,52 @@
+export const ORIGINAL: unique symbol;
+/**
+ * @template {string | symbol | Record<string|symbol, any[]>} [Events=string]
+ */
+export class EventEmitterLite<Events extends string | symbol | Record<string | symbol, any[]> = string> {
+    /**
+     * @type {Object.<Events extends string | symbol ? Events : keyof Events, Function[]>}
+     */
+    events: any;
+    /**
+     * logErrors indicates whether errors thrown by listeners should be logged to the console.
+     * @type {boolean}
+     */
+    logErrors: boolean;
+    /**
+     * on is used to add a callback function that's going to be executed when the event is triggered
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     * @returns {() => void}
+     */
+    on<K extends Events extends string | symbol ? Events : keyof Events>(event: K, listener: Function): () => void;
+    /**
+     * Add a one-time listener
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     * @returns {()=>void}
+     */
+    once<K extends Events extends string | symbol ? Events : keyof Events>(event: K, listener: Function): () => void;
+    /**
+     * off is an alias for removeListener
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     */
+    off<K extends Events extends string | symbol ? Events : keyof Events>(event: K, listener: Function): void;
+    /**
+     * Remove an event listener from an event
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     */
+    removeListener<K extends Events extends string | symbol ? Events : keyof Events>(event: K, listener: Function): void;
+    /**
+     * emit is used to trigger an event
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {...any} args
+     */
+    emit<K extends Events extends string | symbol ? Events : keyof Events>(event: K, ...args: any[]): void;
+}

package/src/event-emitter-lite.js

@@ -0,0 +1,104 @@
+// @ts-check
+
+export const ORIGINAL = Symbol('original');
+
+/**
+ * @template {string | symbol | Record<string|symbol, any[]>} [Events=string]
+ */
+export class EventEmitterLite {
+    /**
+     * @type {Object.<Events extends string | symbol ? Events : keyof Events, Function[]>}
+     */
+    events = Object.create(null);
+
+    /**
+     * logErrors indicates whether errors thrown by listeners should be logged to the console.
+     * @type {boolean}
+     */
+    logErrors = true;
+
+    /**
+     * on is used to add a callback function that's going to be executed when the event is triggered
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     * @returns {() => void}
+     */
+    on(event, listener) {
+        if (!this.events[event]) this.events[event] = [];
+
+        this.events[event].push(listener);
+        let unsubscriber = () => this.removeListener(event, listener);
+        return unsubscriber;
+    }
+
+    /**
+     * Add a one-time listener
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     * @returns {()=>void}
+     */
+    once(event, listener) {
+        const wrapper = (/** @type {...any} */ ...args) => {
+            this.removeListener(event, wrapper);
+            listener.apply(this, args);
+        };
+        wrapper[ORIGINAL] = listener;
+        return this.on(event, wrapper);
+    }
+
+    /**
+     * off is an alias for removeListener
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     */
+    off(event, listener) {
+        return this.removeListener(event, listener);
+    }
+
+    /**
+     * Remove an event listener from an event
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {Function} listener
+     */
+    removeListener(event, listener) {
+        if (typeof listener !== 'function') return;
+
+        const listeners = this.events[event];
+        if (!listeners) return;
+
+        // @ts-ignore
+        const idx = listeners.findIndex(l => l === listener || l[ORIGINAL] === listener);
+        if (idx > -1) {
+            listeners.splice(idx, 1);
+            if (listeners.length === 0) delete this.events[event];
+        }
+    }
+
+    /**
+     * emit is used to trigger an event
+     * @template {Events extends string | symbol ? Events : keyof Events} K
+     * @param {K} event
+     * @param {...any} args
+     */
+    emit(event, ...args) {
+        const listeners = this.events[event];
+        if (!listeners) return;
+
+        const queue = (this.events[event] || []).slice();
+        var length = queue.length;
+
+        for (let i = 0; i < length; i++) {
+            try {
+                queue[i].apply(this, args);
+            } catch (e) {
+                if (this.logErrors) {
+                    console.error(`Error in listener for event "${String(event)}":`, e);
+                }
+            }
+        }
+    }
+}