@startling/emitter 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nicholas Hutchind / Startling Development, LLC
+
+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,218 @@
+# startling-emitter
+
+A tiny, fully-typed event emitter with exact keys, namespace wildcards, and Promise-based event waiting.
+
+✨ ~1 kB gzipped  
+🚫 Zero dependencies  
+📦 ESM-first  
+
+---
+
+## Install
+
+```bash
+npm install @startling/emitter
+```
+
+---
+
+## Why startling-emitter?
+
+- Strongly typed event maps
+- Exact-key subscriptions
+- Namespace wildcards (`user.*`, `user:*`)
+- Global wildcard (`*`)
+- Promise-based `waitFor`
+- AbortSignal + timeout support
+- Safe against listener mutation during emit
+- Zero dependencies
+
+---
+
+## Quick Start (TypeScript)
+
+```ts
+import { createEmitter } from '@startling/emitter';
+
+type Events = {
+  connected: { id: string };
+  message: { from: string; text: string };
+  closed: void;
+};
+
+const emitter = createEmitter<Events>();
+
+const unsubscribe = emitter.on('message', (payload) => {
+  console.log(payload.from, payload.text);
+});
+
+emitter.emit('message', { from: 'system', text: 'hello' });
+unsubscribe();
+```
+
+Events typed as `void` must be emitted without a payload:
+
+```ts
+emitter.emit('closed'); // ✅
+```
+
+---
+
+## Quick Start (JavaScript)
+
+```js
+import { createEmitter } from '@startling/emitter';
+
+const emitter = createEmitter();
+
+emitter.on('message', (payload) => {
+  console.log(payload);
+});
+
+emitter.emit('message', { from: 'system', text: 'hello' });
+```
+
+Type declarations are included for editor IntelliSense.
+
+---
+
+# Wildcards
+
+### Global wildcard
+
+```ts
+emitter.on('*', (event, payload) => {
+  console.log('event:', event, 'payload:', payload);
+});
+```
+
+Matches all emitted events.
+
+---
+
+### Namespace wildcards
+
+Supports both dot (`.`) and colon (`:`) separators.
+
+```ts
+emitter.on('user.*', (payload) => {
+  console.log('dot namespace:', payload);
+});
+
+emitter.on('user:*', (payload) => {
+  console.log('colon namespace:', payload);
+});
+```
+
+Examples:
+
+```ts
+emitter.emit('user.created', { id: '1' }); // matches "user.*"
+emitter.emit('user:login', { id: '1' });   // matches "user:*"
+```
+
+Namespace matching is prefix-based and evaluated at emit time.
+
+---
+
+# waitFor
+
+Wait for the next matching event.
+
+```ts
+const payload = await emitter.waitFor('message');
+
+emitter.emit('message', { from: 'ops', text: 'ready' });
+```
+
+### With filtering
+
+```ts
+const adminMessage = await emitter.waitFor('message', {
+  filter: (p) => p.from === 'admin'
+});
+```
+
+### With timeout and AbortSignal
+
+```ts
+const controller = new AbortController();
+
+await emitter.waitFor('message', {
+  timeoutMs: 1000,
+  signal: controller.signal
+});
+```
+
+Rejects with:
+
+- `Error('Timed out')`
+- `Error('Aborted')`
+
+---
+
+# once
+
+Registers a handler that runs at most once:
+
+```ts
+emitter.once('connected', (payload) => {
+  console.log('connected:', payload.id);
+});
+```
+
+Works with exact keys and wildcards.
+
+---
+
+# Introspection
+
+```ts
+emitter.on('connected', () => {});
+emitter.on('closed', () => {});
+
+console.log(emitter.listenerCount('connected')); // 1
+console.log(emitter.eventNames()); // ['connected', 'closed']
+
+emitter.clear();
+console.log(emitter.eventNames()); // []
+```
+
+- `listenerCount(event)` — number of listeners attached
+- `eventNames()` — exact event keys currently registered
+- `clear()` — removes all listeners
+
+Wildcard registrations are not included in `eventNames()`.
+
+---
+
+# API Summary
+
+| Method | Description |
+|--------|------------|
+| `on(event, handler)` | Register a listener. Returns unsubscribe function. |
+| `off(event, handler)` | Remove a specific listener. |
+| `once(event, handler)` | Register a listener that auto-unregisters. |
+| `emit(event, payload?)` | Emit an event. |
+| `waitFor(event, options?)` | Resolve when event fires. |
+| `listenerCount(event)` | Number of listeners for a key. |
+| `eventNames()` | List of exact event keys. |
+| `clear()` | Remove all listeners. |
+
+---
+
+# Design Notes
+
+- Listener sets are snapshotted during `emit`, allowing safe mutation during iteration.
+- Namespace wildcards are prefix-based and support both `.` and `:` separators.
+- All APIs are strongly typed when using a typed event map.
+
+---
+
+# Development
+
+```bash
+npm test
+npm run typecheck
+npm run build
+```

package/dist/createEmitter.d.ts

@@ -0,0 +1,5 @@
+import type { Emitter, EventMap } from './types';
+/**
+ * Creates a typed emitter with exact-key and wildcard subscriptions.
+ */
+export declare function createEmitter<Events extends EventMap>(): Emitter<Events>;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createEmitter } from './createEmitter';
+export type { Emitter, EventMap, Handler } from './types';

package/dist/startling-emitter.js

@@ -0,0 +1,137 @@
+function m(i) {
+  return i.endsWith(".*") || i.endsWith(":*");
+}
+function p(i) {
+  return i.slice(0, -1);
+}
+function b(i) {
+  const u = [];
+  for (let s = 0; s < i.length; s += 1) {
+    const a = i[s];
+    (a === "." || a === ":") && u.push(i.slice(0, s + 1));
+  }
+  return u;
+}
+function F() {
+  const i = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), s = /* @__PURE__ */ new Set();
+  function a(t, r) {
+    let e = t.get(r);
+    return e || (e = /* @__PURE__ */ new Set(), t.set(r, e)), e;
+  }
+  function l(t, r, e) {
+    const o = t.get(r);
+    o && (o.delete(e), o.size === 0 && t.delete(r));
+  }
+  function w(t, r) {
+    if (t === "*")
+      return s.add(r), () => s.delete(r);
+    if (typeof t == "string" && m(t)) {
+      const e = p(t);
+      return a(u, e).add(r), () => l(u, e, r);
+    }
+    return a(i, t).add(r), () => l(i, t, r);
+  }
+  function x(t, r) {
+    if (t === "*") {
+      s.delete(r);
+      return;
+    }
+    if (typeof t == "string" && m(t)) {
+      const e = p(t);
+      l(u, e, r);
+      return;
+    }
+    l(i, t, r);
+  }
+  function y(t, r) {
+    if (t === "*") {
+      const o = (f, n) => {
+        s.delete(o), r(f, n);
+      };
+      s.add(o);
+      return;
+    }
+    if (typeof t == "string" && m(t)) {
+      const o = p(t), f = ((n) => {
+        l(u, o, f), r(n);
+      });
+      a(u, o).add(f);
+      return;
+    }
+    const e = (o) => {
+      l(i, t, e), r(o);
+    };
+    a(i, t).add(e);
+  }
+  function A(t) {
+    if (t === "*") return s.size;
+    if (typeof t == "string" && m(t)) {
+      const r = p(t);
+      return u.get(r)?.size ?? 0;
+    }
+    return i.get(t)?.size ?? 0;
+  }
+  return {
+    on: w,
+    off: x,
+    listenerCount: A,
+    eventNames: () => Array.from(i.keys()),
+    clear: () => {
+      i.clear(), u.clear(), s.clear();
+    },
+    emit: (...t) => {
+      const r = t[0], e = t.length === 2, o = e ? t[1] : void 0, f = i.get(r);
+      if (f)
+        for (const n of Array.from(f))
+          e ? n(o) : n();
+      if (typeof r == "string") {
+        const n = b(r);
+        for (const g of n) {
+          const c = u.get(g);
+          if (c)
+            for (const d of Array.from(c))
+              e ? d(o) : d();
+        }
+      }
+      if (s.size)
+        for (const n of Array.from(s))
+          e ? n(r, o) : n(r);
+    },
+    once: y,
+    waitFor: (t, r) => new Promise((e, o) => {
+      const f = [];
+      let n = () => {
+        for (let c = f.length - 1; c >= 0; c -= 1) f[c]();
+        f.length = 0, n = () => {
+        };
+      };
+      const g = ((c) => {
+        try {
+          if (r?.filter && !r.filter(c)) return;
+          n(), e(c);
+        } catch (d) {
+          n(), o(d);
+        }
+      });
+      if (f.push(w(t, g)), r?.timeoutMs !== void 0) {
+        const c = setTimeout(() => {
+          n(), o(new Error("Timed out"));
+        }, r.timeoutMs);
+        f.push(() => clearTimeout(c));
+      }
+      if (r?.signal) {
+        if (r.signal.aborted) {
+          n(), o(new Error("Aborted"));
+          return;
+        }
+        const c = () => {
+          n(), o(new Error("Aborted"));
+        };
+        r.signal.addEventListener("abort", c), f.push(() => r.signal?.removeEventListener("abort", c));
+      }
+    })
+  };
+}
+export {
+  F as createEmitter
+};

package/dist/types.d.ts

@@ -0,0 +1,27 @@
+export type EventMap = Record<PropertyKey, any>;
+export type Handler<T = unknown> = T extends void ? () => void : (payload: T) => void;
+export type EmitArgs<Events extends EventMap, K extends keyof Events> = Events[K] extends void ? [event: K] : [event: K, payload: Events[K]];
+export type WildcardKey = '*' | `${string}.*` | `${string}:*`;
+export type AnyEventHandler<Events extends EventMap> = (event: keyof Events, payload?: Events[keyof Events]) => void;
+export type NamespaceWildcardHandler<Events extends EventMap> = Handler<Events[keyof Events]> | (() => void);
+export interface Emitter<Events extends EventMap> {
+    on<K extends keyof Events>(event: K, handler: Handler<Events[K]>): () => void;
+    on(event: '*', handler: AnyEventHandler<Events>): () => void;
+    on(event: `${string}.*` | `${string}:*`, handler: NamespaceWildcardHandler<Events>): () => void;
+    off<K extends keyof Events>(event: K, handler: Handler<Events[K]>): void;
+    off(event: '*', handler: AnyEventHandler<Events>): void;
+    off(event: `${string}.*` | `${string}:*`, handler: NamespaceWildcardHandler<Events>): void;
+    listenerCount<K extends keyof Events>(event: K): number;
+    listenerCount(event: WildcardKey): number;
+    eventNames(): Array<keyof Events>;
+    clear(): void;
+    emit<K extends keyof Events>(...args: EmitArgs<Events, K>): void;
+    once<K extends keyof Events>(event: K, handler: Handler<Events[K]>): void;
+    once(event: '*', handler: AnyEventHandler<Events>): void;
+    once(event: `${string}.*` | `${string}:*`, handler: NamespaceWildcardHandler<Events>): void;
+    waitFor<K extends keyof Events>(event: K, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+        filter?: (payload: Events[K]) => boolean;
+    }): Promise<Events[K]>;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@startling/emitter",
+  "version": "1.0.3",
+  "description": "A tiny, fully-typed event emitter for modern TypeScript and JavaScript projects — with wildcard support, Promise-based `waitFor`, and AbortSignal integration.",
+  "author": "Nicholas Hutchind",
+  "license": "MIT",
+  "homepage": "https://github.com/StartlingDev/startling-emitter#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/StartlingDev/startling-emitter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/StartlingDev/startling-emitter/issues"
+  },
+  "type": "module",
+  "main": "./dist/startling-emitter.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/startling-emitter.js",
+      "default": "./dist/startling-emitter.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "rm -rf dist && vite build && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check:clean": "git diff --quiet && git diff --cached --quiet && npm run test && npm run typecheck",
+    "release": "npm publish",
+    "release:patch": "npm run check:clean && npm version patch && git push --follow-tags && npm run release",
+    "release:minor": "npm run check:clean && npm version minor && git push --follow-tags && npm run release",
+    "release:major": "npm run check:clean && npm version major && git push --follow-tags && npm run release"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.9.0",
+    "vite": "^7.0.0",
+    "vitest": "^4.0.18"
+  }
+}