event-emission 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+declare global {
+    function queueMicrotask(callback: () => void): void;
+}
+/**
+ * Event structure passed to listeners.
+ */
+export interface EventfulEvent<Detail> {
+    /** The event type identifier. */
+    type: string;
+    /** The event payload data. */
+    detail: Detail;
+}
+/**
+ * Event passed to wildcard listeners, includes the original event type.
+ */
+export interface WildcardEvent<E extends Record<string, unknown>> {
+    type: '*' | `${string}:*`;
+    originalType: keyof E & string;
+    detail: E[keyof E];
+}
+/**
+ * Minimal AbortSignal lookalike so consumers do not need DOM libs.
+ */
+export interface MinimalAbortSignal {
+    readonly aborted: boolean;
+    readonly reason?: unknown;
+    addEventListener: (type: 'abort', listener: () => void, options?: unknown) => void;
+    removeEventListener: (type: 'abort', listener: () => void, options?: unknown) => void;
+}
+/**
+ * Options for addEventListener.
+ */
+export type AddEventListenerOptionsLike = {
+    once?: boolean;
+    signal?: MinimalAbortSignal;
+};
+/**
+ * TC39 Observable observer interface.
+ */
+export interface Observer<T> {
+    next?: (value: T) => void;
+    error?: (err: unknown) => void;
+    complete?: () => void;
+}
+/**
+ * TC39 Observable subscription interface.
+ */
+export interface Subscription {
+    unsubscribe(): void;
+    readonly closed: boolean;
+}
+/**
+ * TC39 Observable-like interface.
+ */
+export interface ObservableLike<T> {
+    subscribe(observerOrNext?: Observer<T> | ((value: T) => void), error?: (err: unknown) => void, complete?: () => void): Subscription;
+}
+/**
+ * Overflow strategy for async iterator buffer.
+ */
+export type OverflowStrategy = 'drop-oldest' | 'drop-latest' | 'throw';
+/**
+ * Options for the events() async iterator.
+ */
+export interface AsyncIteratorOptions {
+    signal?: MinimalAbortSignal;
+    bufferSize?: number;
+    overflowStrategy?: OverflowStrategy;
+}
+/**
+ * Options for the events() async iterator (alias for AsyncIteratorOptions).
+ */
+export type EventsIteratorOptions = AsyncIteratorOptions;
+/**
+ * Options for interop helpers.
+ */
+export interface InteropOptions {
+    signal?: MinimalAbortSignal;
+}
+/**
+ * Minimal DOM Event interface for interop.
+ */
+export interface DOMEventLike {
+    type: string;
+    detail?: unknown;
+}
+/**
+ * Minimal DOM EventTarget interface for interop.
+ */
+export interface DOMEventTargetLike {
+    addEventListener(type: string, listener: (event: DOMEventLike) => void): void;
+    removeEventListener(type: string, listener: (event: DOMEventLike) => void): void;
+    dispatchEvent(event: DOMEventLike): boolean;
+}
+/**
+ * Internal listener record type.
+ */
+export type Listener<E> = {
+    fn: (event: EventfulEvent<E>) => void | Promise<void>;
+    once?: boolean;
+    signal?: MinimalAbortSignal;
+    abortHandler?: () => void;
+};
+/**
+ * Internal wildcard listener record type.
+ */
+export type WildcardListener<E extends Record<string, unknown>> = {
+    fn: (event: WildcardEvent<E>) => void | Promise<void>;
+    pattern: '*' | `${string}:*`;
+    once?: boolean;
+    signal?: MinimalAbortSignal;
+    abortHandler?: () => void;
+};
+/**
+ * Type-safe event target interface compatible with DOM EventTarget
+ * and TC39 Observable patterns.
+ */
+export interface EventTargetLike<E extends Record<string, any>> {
+    addEventListener: <K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>, options?: AddEventListenerOptionsLike) => () => void;
+    removeEventListener: <K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>) => void;
+    dispatchEvent: <K extends keyof E & string>(event: EventfulEvent<E[K]>) => boolean;
+    clear: () => void;
+    once: <K extends keyof E & string>(type: K, listener: (event: EventfulEvent<E[K]>) => void | Promise<void>, options?: Omit<AddEventListenerOptionsLike, 'once'>) => () => void;
+    removeAllListeners: <K extends keyof E & string>(type?: K) => void;
+    /**
+     * Pipe events from this emitter to another target.
+     * Note: Only forwards events for types that have listeners when pipe() is called.
+     * Events for types registered after piping won't be forwarded automatically.
+     */
+    pipe: <T extends Record<string, any>>(target: EventTargetLike<T>, mapFn?: <K extends keyof E & string>(event: EventfulEvent<E[K]>) => EventfulEvent<T[keyof T & string]> | null) => () => void;
+    complete: () => void;
+    readonly completed: boolean;
+    addWildcardListener: (pattern: '*' | `${string}:*`, listener: (event: WildcardEvent<E>) => void | Promise<void>, options?: AddEventListenerOptionsLike) => () => void;
+    removeWildcardListener: (pattern: '*' | `${string}:*`, listener: (event: WildcardEvent<E>) => void | Promise<void>) => void;
+    subscribe: <K extends keyof E & string>(type: K, observerOrNext?: Observer<EventfulEvent<E[K]>> | ((value: EventfulEvent<E[K]>) => void), error?: (err: unknown) => void, complete?: () => void) => Subscription;
+    toObservable: () => ObservableLike<EventfulEvent<E[keyof E]>>;
+    events: <K extends keyof E & string>(type: K, options?: AsyncIteratorOptions) => AsyncIterableIterator<EventfulEvent<E[K]>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "event-emission",
+  "version": "0.1.0",
+  "description": "Lightweight typed event emitter with DOM EventTarget and TC39 Observable compatibility",
+  "keywords": [
+    "event",
+    "emitter",
+    "events",
+    "eventtarget",
+    "observable",
+    "typescript",
+    "typed-events",
+    "pubsub",
+    "publish-subscribe"
+  ],
+  "homepage": "https://github.com/stevekinney/event-emission#readme",
+  "bugs": {
+    "url": "https://github.com/stevekinney/event-emission/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/stevekinney/event-emission.git"
+  },
+  "license": "MIT",
+  "author": "Steve Kinney",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "clean": "rm -rf dist coverage",
+    "dev": "bun --watch run src/index.ts",
+    "format": "prettier --write \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,tsx,js,jsx,json,md}\"",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "prepare": "husky",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "typecheck": "tsc --noEmit",
+    "validate": "bun run lint && bun run typecheck && bun run test && bun run build"
+  },
+  "lint-staged": {
+    "src/**/*.{js,ts,tsx,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "scripts/**/*.{js,ts,tsx,jsx,mjs,cjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "**/*.{json,md,css,scss}": [
+      "prettier --write"
+    ],
+    "package.json": [
+      "sort-package-json"
+    ]
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "@eslint/markdown": "^7.5.1",
+    "@types/bun": "^1.3.5",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "chalk": "^5.6.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-eslint-comments": "^3.2.0",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-regexp": "^2.10.0",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "eslint-plugin-unused-imports": "^4.3.0",
+    "globals": "^16.5.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "sort-package-json": "^3.6.0",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.50.0"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+/**
+ * Error thrown when an async iterator's event buffer overflows
+ * and the overflow strategy is 'throw'.
+ */
+export class BufferOverflowError extends Error {
+  constructor(eventType: string, bufferSize: number) {
+    super(`Buffer overflow for event type "${eventType}" (max: ${bufferSize})`);
+    this.name = 'BufferOverflowError';
+  }
+}

package/src/eventful.ts

@@ -0,0 +1,323 @@
+import { createEventTarget } from './factory';
+import { SymbolObservable } from './symbols';
+import type {
+  AddEventListenerOptionsLike,
+  EventfulEvent,
+  EventsIteratorOptions,
+  EventTargetLike,
+  ObservableLike,
+  Observer,
+  Subscription,
+  WildcardEvent,
+} from './types';
+
+/**
+ * Abstract base class for typed event emitters with DOM EventTarget
+ * and TC39 Observable compatibility.
+ *
+ * Extend this class to create custom event emitters with typed events.
+ * The class provides:
+ * - DOM EventTarget compatible API (addEventListener, removeEventListener, dispatchEvent)
+ * - TC39 Observable interop (subscribe, Symbol.observable)
+ * - Async iteration support (events() method)
+ * - Wildcard listeners for namespaced events
+ * - Lifecycle management (complete(), completed)
+ *
+ * Listener errors are handled via 'error' event: if a listener throws,
+ * an 'error' event is emitted. If no 'error' listener is registered,
+ * the error is re-thrown (Node.js behavior).
+ *
+ * @template E - Event map type where keys are event names and values are event detail types.
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Define your emitter with typed events
+ * class UserService extends Eventful<{
+ *   'user:created': { id: string; name: string };
+ *   'user:deleted': { id: string };
+ *   error: Error;
+ * }> {
+ *   createUser(name: string) {
+ *     const id = crypto.randomUUID();
+ *     // ... create user logic
+ *     this.dispatchEvent({ type: 'user:created', detail: { id, name } });
+ *   }
+ * }
+ *
+ * const service = new UserService();
+ * service.addEventListener('user:created', (event) => {
+ *   console.log(`Created user: ${event.detail.name}`);
+ * });
+ * ```
+ *
+ * @example TC39 Observable interop
+ * ```typescript
+ * const service = new UserService();
+ *
+ * // Subscribe to all events
+ * service.subscribe({
+ *   next: (event) => console.log(event.type, event.detail),
+ *   complete: () => console.log('Service completed'),
+ * });
+ *
+ * // Use with RxJS or other Observable libraries
+ * import { from } from 'rxjs';
+ * const observable = from(service);
+ * ```
+ *
+ * @example Async iteration
+ * ```typescript
+ * const service = new UserService();
+ *
+ * // Iterate over events as async iterator
+ * for await (const event of service.events('user:created')) {
+ *   console.log(`User created: ${event.detail.name}`);
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic constraint requires any for flexibility
+export abstract class Eventful<E extends Record<string, any>> {
+  readonly #target: EventTargetLike<E>;
+
+  constructor() {
+    this.#target = createEventTarget<E>();
+  }
+
+  // ==========================================================================
+  // DOM EventTarget Methods
+  // ==========================================================================
+
+  /**
+   * Adds an event listener for the specified event type.
+   * Returns an unsubscribe function for convenience.
+   */
+  addEventListener<K extends keyof E & string>(
+    type: K,
+    listener: (event: EventfulEvent<E[K]>) => void | Promise<void>,
+    options?: AddEventListenerOptionsLike,
+  ): () => void {
+    return this.#target.addEventListener(type, listener, options);
+  }
+
+  /**
+   * Removes an event listener for the specified event type.
+   */
+  removeEventListener<K extends keyof E & string>(
+    type: K,
+    listener: (event: EventfulEvent<E[K]>) => void | Promise<void>,
+  ): void {
+    this.#target.removeEventListener(type, listener);
+  }
+
+  /**
+   * Dispatches an event to all registered listeners.
+   * Returns false if the emitter has been completed, true otherwise.
+   */
+  dispatchEvent<K extends keyof E & string>(event: EventfulEvent<E[K]>): boolean {
+    return this.#target.dispatchEvent(event);
+  }
+
+  // ==========================================================================
+  // Convenience Methods
+  // ==========================================================================
+
+  /**
+   * Adds a one-time listener for the specified event type.
+   * Returns an unsubscribe function.
+   */
+  once<K extends keyof E & string>(
+    type: K,
+    listener: (event: EventfulEvent<E[K]>) => void | Promise<void>,
+    options?: Omit<AddEventListenerOptionsLike, 'once'>,
+  ): () => void {
+    return this.#target.once(type, listener, options);
+  }
+
+  /**
+   * Removes all listeners, or those of the specified event type.
+   */
+  removeAllListeners<K extends keyof E & string>(type?: K): void {
+    this.#target.removeAllListeners(type);
+  }
+
+  /**
+   * Removes all listeners. Does not trigger completion.
+   */
+  clear(): void {
+    this.#target.clear();
+  }
+
+  /**
+   * Pipe events from this emitter to another target.
+   * Note: Only forwards events for types that have listeners when pipe() is called.
+   * Events for types registered after piping won't be forwarded automatically.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Generic constraint requires any
+  pipe<T extends Record<string, any>>(
+    target: EventTargetLike<T>,
+    mapFn?: <K extends keyof E & string>(
+      event: EventfulEvent<E[K]>,
+    ) => EventfulEvent<T[keyof T & string]> | null,
+  ): () => void {
+    return this.#target.pipe(target, mapFn);
+  }
+
+  // ==========================================================================
+  // Wildcard Support
+  // ==========================================================================
+
+  /**
+   * Adds a wildcard listener that receives events matching the pattern.
+   * Use '*' for all events, or 'namespace:*' for namespaced events.
+   */
+  addWildcardListener(
+    pattern: '*' | `${string}:*`,
+    listener: (event: WildcardEvent<E>) => void | Promise<void>,
+    options?: AddEventListenerOptionsLike,
+  ): () => void {
+    return this.#target.addWildcardListener(pattern, listener, options);
+  }
+
+  /**
+   * Removes a wildcard listener.
+   */
+  removeWildcardListener(
+    pattern: '*' | `${string}:*`,
+    listener: (event: WildcardEvent<E>) => void | Promise<void>,
+  ): void {
+    this.#target.removeWildcardListener(pattern, listener);
+  }
+
+  // ==========================================================================
+  // TC39 Observable Methods
+  // ==========================================================================
+
+  /**
+   * Subscribes an observer to all events (untyped).
+   */
+  subscribe(
+    observerOrNext:
+      | Observer<EventfulEvent<E[keyof E]>>
+      | ((value: EventfulEvent<E[keyof E]>) => void),
+  ): Subscription;
+
+  /**
+   * Subscribes an observer to events of a specific type (typed).
+   */
+  subscribe<K extends keyof E & string>(
+    type: K,
+    observerOrNext?:
+      | Observer<EventfulEvent<E[K]>>
+      | ((value: EventfulEvent<E[K]>) => void),
+    error?: (err: unknown) => void,
+    completeHandler?: () => void,
+  ): Subscription;
+
+  /**
+   * Implementation that handles both typed and untyped subscriptions.
+   */
+  subscribe<K extends keyof E & string>(
+    typeOrObserver:
+      | K
+      | Observer<EventfulEvent<E[keyof E]>>
+      | ((value: EventfulEvent<E[keyof E]>) => void),
+    observerOrNext?:
+      | Observer<EventfulEvent<E[K]>>
+      | ((value: EventfulEvent<E[K]>) => void),
+    error?: (err: unknown) => void,
+    completeHandler?: () => void,
+  ): Subscription {
+    // Typed subscribe: first argument is a string event type
+    if (typeof typeOrObserver === 'string') {
+      return this.#target.subscribe(
+        typeOrObserver,
+        observerOrNext,
+        error,
+        completeHandler,
+      );
+    }
+
+    // Untyped subscribe: first argument is a callback function
+    if (typeof typeOrObserver === 'function') {
+      return this.#target.toObservable().subscribe(typeOrObserver);
+    }
+
+    // Untyped subscribe: first argument is an observer object
+    if (typeof typeOrObserver === 'object' && typeOrObserver !== null) {
+      // Check if it looks like an Observer (has next/error/complete methods)
+      const maybeObserver = typeOrObserver as Record<string, unknown>;
+      if (
+        typeof maybeObserver.next === 'function' ||
+        typeof maybeObserver.error === 'function' ||
+        typeof maybeObserver.complete === 'function'
+      ) {
+        return this.#target.toObservable().subscribe(typeOrObserver);
+      }
+      // Object without observer methods - treat as empty observer (no callbacks)
+      return this.#target.toObservable().subscribe({});
+    }
+
+    // Fallback: should not reach here with proper TypeScript usage
+    throw new Error(
+      'subscribe() requires a string event type, callback function, or observer object',
+    );
+  }
+
+  /**
+   * Returns an observable that emits all events.
+   */
+  toObservable(): ObservableLike<EventfulEvent<E[keyof E]>> {
+    return this.#target.toObservable();
+  }
+
+  /**
+   * Returns this observable for Symbol.observable interop.
+   */
+  [SymbolObservable](): ObservableLike<EventfulEvent<E[keyof E]>> {
+    return this.toObservable();
+  }
+
+  // ==========================================================================
+  // Lifecycle Methods
+  // ==========================================================================
+
+  /**
+   * Marks the emitter as complete. Invokes complete() on all observable subscribers,
+   * ends all async iterators, and suppresses further emits/dispatches.
+   * Idempotent.
+   */
+  complete(): void {
+    this.#target.complete();
+  }
+
+  /**
+   * Returns true if the emitter has been completed.
+   */
+  get completed(): boolean {
+    return this.#target.completed;
+  }
+
+  // ==========================================================================
+  // Async Iterator Method
+  // ==========================================================================
+
+  /**
+   * Returns an async iterator over events of the specified type.
+   *
+   * @param type - The event type to iterate over
+   * @param options - Iterator options (signal, bufferSize, overflowStrategy)
+   *
+   * @example
+   * ```typescript
+   * for await (const event of emitter.events('foo')) {
+   *   console.log(event.detail);
+   * }
+   * ```
+   */
+  events<K extends keyof E & string>(
+    type: K,
+    options?: EventsIteratorOptions,
+  ): AsyncIterableIterator<EventfulEvent<E[K]>> {
+    return this.#target.events(type, options);
+  }
+}