emitterkit 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright 2026 EmitterKit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the “Software”),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,237 @@
+# EmitterKit
+
+Tiny, dependency-free, type-safe event emitters for TypeScript.
+
+Create an event emitter, listen for named events, and emit them wherever they
+need to be handled. TypeScript provides autocomplete for event names and checks
+that each handler and emit call receives the right arguments.
+
+## Install
+
+```sh
+npm install emitterkit
+```
+
+## Quick start
+
+```ts
+import { createEventEmitter } from 'emitterkit';
+
+interface AppEvents {
+  userSignedIn: [userId: string, rememberMe: boolean];
+  toast: [message: string];
+  ready: [];
+};
+
+const events = createEventEmitter<AppEvents>();
+
+events.on('userSignedIn', (userId, rememberMe) => {
+  console.log(`${userId} signed in; remember: ${rememberMe}`);
+});
+
+events.emit('userSignedIn', 'ada', true);
+events.emit('toast', 'Welcome back!');
+events.emit('ready');
+```
+
+The event key and its arguments are checked together:
+
+```ts
+events.emit('toast');                 // Type error: message is required.
+events.emit('ready', 'unexpected');  // Type error: ready has no arguments.
+events.on('missing', () => {}); // Type error: unknown event.
+```
+
+## API
+
+### `createEventEmitter<Events>(options?)`
+
+Creates a new isolated `EventEmitter`. `Events` maps each event key to a tuple of
+arguments. Event keys may be strings, numbers, or symbols.
+
+By default, the same handler can be registered multiple times and each call is
+kept. Pass `{ dedupe: true }` to ignore repeated registrations of the same
+handler for an event key.
+
+```ts
+const saved = Symbol('saved');
+
+const emitter = createEventEmitter<{
+  [saved]: [path: string];
+  progress: [completed: number, total: number];
+}>();
+```
+
+### `emitter.on(eventKey, handler)`
+
+Registers `handler` for `eventKey`. Registering the same function more than once
+for an event key creates multiple registrations by default. Returns a function that
+removes that specific registration.
+
+### `emitter.once(eventKey, handler)`
+
+Registers `handler` for one call only. It is removed immediately before its
+first invocation. Returns a function that removes the handler before then.
+
+### `emitter.watch(watcher)`
+
+Registers `watcher` for every emitted event. The watcher receives the event key
+followed by its arguments, and runs after handlers registered for that event key.
+Returns a function that removes the watcher.
+
+```ts
+const stop = emitter.watch((eventKey, ...args) => {
+  console.log(eventKey, args);
+});
+```
+
+### `emitter.off(eventKey, handler)`
+
+Unregisters the most recently registered matching handler and returns `true` when
+it was registered, `false` when that event key and handler pair not found.
+
+### `emitter.emit(eventKey, ...args)`
+
+Calls every handler registered for `eventKey`, forwarding the supplied arguments.
+Handlers added or removed while an event is being emitted take effect on the
+next call to `emit`.
+
+## Types
+
+`EventEmitter`, `EventHandler`, `EventWatcher`, `EventMap`, and `EventEmitterOptions` are exported for
+use in public APIs:
+
+- `EventHandler<EventKey, Events>` is the callback type for one event key, with its arguments inferred from `Events`.
+- `EventWatcher<Events>` is the callback type for observing every emitted event.
+- `EventMap` is the base type for an object that associates event keys with their argument tuples.
+- `EventEmitterOptions` configures an emitter; use `dedupe: true` to ignore repeated handler registrations.
+
+```ts
+import type { EventEmitter } from 'emitterkit';
+
+type EditorEvents = {
+  changed: [contents: string];
+};
+
+function connectEditor(events: EventEmitter<EditorEvents>) {
+  events.on('changed', (contents) => save(contents));
+}
+```
+
+## Examples
+
+### Destructuring methods
+
+The emitter methods do not depend on `this`, so they can be destructured and
+used directly:
+
+```ts
+const { on, emit } = createEventEmitter<{ saved: [path: string]; }>();
+
+on('saved', (path) => console.log(`Saved ${path}`));
+emit('saved', '/tmp/note.md');
+```
+
+### Removing a registration
+
+`on`, `once`, and `watch` return a function that removes the exact registration
+they created:
+
+```ts
+const emitter = createEventEmitter<{ changed: [] }>();
+const stop = emitter.on('changed', () => console.log('Changed'));
+stop();
+```
+
+### Watching all events
+
+Use `watch` for logging, diagnostics, or other cross-cutting behavior:
+
+```ts
+const emitter = createEventEmitter<{ saved: [path: string] }>();
+const stop = emitter.watch((eventKey, ...args) => {
+  console.debug('Event emitted:', eventKey, args);
+});
+
+emitter.emit('saved', '/tmp/note.md');
+stop();
+```
+
+### Mixing with an object
+
+Create a new object with event emitter methods mixed in:
+
+```ts
+const counter = {
+  value: 0,
+  ...createEventEmitter<{ changed: [value: number] }>(),
+};
+
+counter.on('changed', (value) => console.log(value));
+counter.value += 1;
+counter.emit('changed', counter.value);
+```
+
+### Adding events to a class
+
+Create an emitter for each instance in the constructor. Interface merging adds
+the emitter methods to the class type:
+
+```ts
+import { createEventEmitter, type EventEmitter } from 'emitterkit';
+
+type MyClazzEvents = {
+  changed: [value: number];
+};
+
+interface MyClazz extends EventEmitter<MyClazzEvents> {}
+
+class MyClazz {
+  constructor() {
+    Object.assign(this, createEventEmitter<MyClazzEvents>());
+  }
+
+  setValue(value: number) {
+    this.emit('changed', value);
+  }
+}
+
+const instance = new MyClazz();
+instance.on('changed', console.log);
+instance.setValue(1);
+```
+
+### Event-specific methods / wrapping
+
+Event-specific methods such as `onChanged` are useful when a class exposes a
+small domain API and should not expose the generic emitter directly.
+
+```ts
+import { createEventEmitter, type EventHandler } from 'emitterkit';
+
+type CounterEvents = {
+  changed: [value: number];
+};
+
+class Counter {
+  private readonly events = createEventEmitter<CounterEvents>();
+  private value = 0;
+
+  onChanged(handler: EventHandler<'changed', CounterEvents>) {
+    return this.events.on('changed', handler);
+  }
+
+  increment() {
+    this.value += 1;
+    this.events.emit('changed', this.value);
+  }
+}
+
+const counter = new Counter();
+counter.onChanged(console.log);
+counter.increment();
+```
+
+## License
+
+[MIT](LICENSE)

package/index.d.mts

@@ -0,0 +1,43 @@
+/** A mapping from event keys to the arguments emitted for that event. */
+export type EventMap = object;
+type EventArgs<EventKey extends keyof Events, Events extends EventMap> = Events[EventKey] extends readonly unknown[] ? Events[EventKey] : never;
+/** A callback that receives the arguments for one event key. */
+export type EventHandler<EventKey extends keyof Events, Events extends EventMap> = (...args: EventArgs<EventKey, Events>) => void;
+/** A callback that receives every emitted event and its arguments. */
+export type EventWatcher<Events extends EventMap> = <EventKey extends keyof Events>(eventKey: EventKey, ...args: EventArgs<EventKey, Events>) => void;
+/** Options for {@link createEventEmitter}. */
+export interface EventEmitterOptions {
+    /** Ignore registrations that use a handler already registered for the same event key. */
+    dedupe?: boolean;
+}
+/**
+ * A lightweight, type-safe event emitter.
+ *
+ * Create one with {@link createEventEmitter}; handlers registered on an instance
+ * are notified only by `emit` calls on that same instance.
+ */
+export interface EventEmitter<Events extends EventMap = Record<string, unknown[]>> {
+    /** Register a handler for an event key. Duplicate registrations are ignored when `dedupe` is enabled. */
+    on<EventKey extends keyof Events>(this: void, eventKey: EventKey, handler: EventHandler<EventKey, Events>): () => void;
+    /** Register a handler for an event key that is removed after its first call. */
+    once<EventKey extends keyof Events>(this: void, eventKey: EventKey, handler: EventHandler<EventKey, Events>): () => void;
+    /** Register a callback that is notified for every emitted event. */
+    watch(this: void, watcher: EventWatcher<Events>): () => void;
+    /** Remove a handler. Returns whether that handler was registered. */
+    off<EventKey extends keyof Events>(this: void, eventKey: EventKey, handler: EventHandler<EventKey, Events>): boolean;
+    /**
+     * Notify every handler registered for an event key.
+     * Handlers added or removed while emitting take effect on the next emit.
+     */
+    emit<EventKey extends keyof Events>(this: void, eventKey: EventKey, ...args: EventArgs<EventKey, Events>): void;
+}
+/**
+ * Creates an isolated event emitter.
+ *
+ * @example
+ * const emitter = createEventEmitter<{ saved: [id: string, at: Date] }>();
+ * emitter.on('saved', (id, at) => console.log(id, at.toISOString()));
+ * emitter.emit('saved', 'file-42', new Date());
+ */
+export declare function createEventEmitter<Events extends EventMap = Record<string, unknown[]>>({ dedupe }?: EventEmitterOptions): EventEmitter<Events>;
+export {};

package/index.mjs

@@ -0,0 +1,93 @@
+/**
+ * Creates an isolated event emitter.
+ *
+ * @example
+ * const emitter = createEventEmitter<{ saved: [id: string, at: Date] }>();
+ * emitter.on('saved', (id, at) => console.log(id, at.toISOString()));
+ * emitter.emit('saved', 'file-42', new Date());
+ */
+export function createEventEmitter({ dedupe = false } = {}) {
+    const WATCH_KEY = Symbol();
+    const registrations = new Map();
+    const noop = () => { };
+    const removeLatestRegistration = (eventKey, handler) => {
+        const eventRegistrations = registrations.get(eventKey);
+        if (!eventRegistrations) {
+            return false;
+        }
+        for (let index = eventRegistrations.length - 1; index >= 0; index -= 1) {
+            if (eventRegistrations[index].handler === handler) {
+                eventRegistrations.splice(index, 1);
+                if (eventRegistrations.length === 0) {
+                    registrations.delete(eventKey);
+                }
+                return true;
+            }
+        }
+        return false;
+    };
+    const removeRegistration = (eventKey, registration) => {
+        const eventRegistrations = registrations.get(eventKey);
+        const index = eventRegistrations?.indexOf(registration) ?? -1;
+        if (index < 0 || !eventRegistrations) {
+            return false;
+        }
+        eventRegistrations.splice(index, 1);
+        if (eventRegistrations.length === 0) {
+            registrations.delete(eventKey);
+        }
+        return true;
+    };
+    const addRegistration = (eventKey, registration) => {
+        const eventRegistrations = registrations.get(eventKey);
+        if (dedupe && eventRegistrations?.some(({ handler }) => handler === registration.handler)) {
+            return false;
+        }
+        if (eventRegistrations) {
+            eventRegistrations.push(registration);
+        }
+        else {
+            registrations.set(eventKey, [registration]);
+        }
+        return true;
+    };
+    return {
+        on(eventKey, handler) {
+            const registration = { handler, invoke: handler };
+            if (!addRegistration(eventKey, registration)) {
+                return noop;
+            }
+            return () => removeRegistration(eventKey, registration);
+        },
+        once(eventKey, handler) {
+            let registration;
+            const invokeOnce = (...args) => {
+                removeRegistration(eventKey, registration);
+                handler(...args);
+            };
+            registration = { handler, invoke: invokeOnce };
+            if (!addRegistration(eventKey, registration)) {
+                return noop;
+            }
+            return () => removeRegistration(eventKey, registration);
+        },
+        watch(watcher) {
+            const registration = { handler: watcher, invoke: watcher };
+            if (!addRegistration(WATCH_KEY, registration)) {
+                return noop;
+            }
+            return () => removeRegistration(WATCH_KEY, registration);
+        },
+        off(eventKey, handler) {
+            return removeLatestRegistration(eventKey, handler);
+        },
+        emit(eventKey, ...args) {
+            for (const { invoke } of [...(registrations.get(eventKey) ?? [])]) {
+                invoke(...args);
+            }
+            for (const { invoke } of [...(registrations.get(WATCH_KEY) ?? [])]) {
+                invoke(eventKey, ...args);
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "emitterkit",
+  "version": "0.1.0",
+  "description": "Tiny, type-safe event emitters for TypeScript, similar to Node.js EventEmitter",
+  "type": "module",
+  "main": "index.mjs",
+  "types": "index.d.mts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./index.d.mts",
+        "default": "./index.mjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.mjs",
+    "index.d.mts"
+  ],
+  "homepage": "https://github.com/lionel87/emitterkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lionel87/emitterkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lionel87/emitterkit/issues"
+  },
+  "author": "László BULIK",
+  "license": "MIT",
+  "keywords": [
+    "event",
+    "event emitter",
+    "event bus",
+    "events",
+    "pubsub",
+    "typescript",
+    "type-safe"
+  ]
+}