event-emission 0.2.1 → 0.3.0

package/src/event-emission.ts

@@ -129,14 +129,29 @@ export abstract class EventEmission<E extends Record<string, any>> {
   // Convenience Methods
   // ==========================================================================
 
+  /**
+   * Adds a listener for the specified event type (Node.js-style).
+   * Returns an unsubscribe function.
+   */
+  on<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): () => void;
+
   /**
    * Returns an observable for the specified event type.
    */
   on<K extends keyof E & string>(
     type: K,
     options?: OnOptions | boolean,
-  ): ObservableLike<EmissionEvent<E[K], K>> {
-    return this.#target.on(type, options);
+  ): ObservableLike<EmissionEvent<E[K], K>>;
+
+  on<K extends keyof E & string>(
+    type: K,
+    optionsOrListener?: OnOptions | boolean | EventListenerLike<EmissionEvent<E[K], K>>,
+  ): ObservableLike<EmissionEvent<E[K], K>> | (() => void) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument
+    return this.#target.on(type, optionsOrListener as any);
   }
 
   /**
@@ -179,6 +194,104 @@ export abstract class EventEmission<E extends Record<string, any>> {
     return this.#target.pipe(target, mapFn);
   }
 
+  // ==========================================================================
+  // Node.js EventEmitter Compatibility
+  // ==========================================================================
+
+  /**
+   * Emits an event with the given type and detail.
+   * Returns true if the event type had registered listeners, false otherwise.
+   */
+  emit<K extends keyof E & string>(type: K, detail: E[K]): boolean {
+    return this.#target.emit(type, detail);
+  }
+
+  /**
+   * Removes a listener for the specified event type.
+   */
+  off<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): void {
+    this.#target.off(type, listener);
+  }
+
+  /**
+   * Adds a listener for the specified event type.
+   * Returns an unsubscribe function.
+   */
+  addListener<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): () => void {
+    return this.#target.addListener(type, listener);
+  }
+
+  /**
+   * Removes a listener for the specified event type.
+   */
+  removeListener<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): void {
+    this.#target.removeListener(type, listener);
+  }
+
+  /**
+   * Adds a listener at the beginning of the listener list for the specified type.
+   * Returns an unsubscribe function.
+   */
+  prependListener<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): () => void {
+    return this.#target.prependListener(type, listener);
+  }
+
+  /**
+   * Adds a one-time listener at the beginning of the listener list.
+   * Returns an unsubscribe function.
+   */
+  prependOnceListener<K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ): () => void {
+    return this.#target.prependOnceListener(type, listener);
+  }
+
+  /**
+   * Returns an array of listener functions for the specified event type.
+   */
+  listeners<K extends keyof E & string>(
+    type: K,
+  ): Array<EventListenerLike<EmissionEvent<E[K], K>>> {
+    return this.#target.listeners(type);
+  }
+
+  /**
+   * Returns an array of listener functions for the specified event type.
+   * Once-listeners return a wrapper with a `.listener` property pointing to the original.
+   */
+  rawListeners<K extends keyof E & string>(
+    type: K,
+  ): Array<EventListenerLike<EmissionEvent<E[K], K>>> {
+    return this.#target.rawListeners(type);
+  }
+
+  /**
+   * Returns the number of listeners for the specified event type.
+   */
+  listenerCount<K extends keyof E & string>(type: K): number {
+    return this.#target.listenerCount(type);
+  }
+
+  /**
+   * Returns an array of event type names that have registered listeners.
+   */
+  eventNames(): Array<string> {
+    return this.#target.eventNames();
+  }
+
   // ==========================================================================
   // Wildcard Support
   // ==========================================================================

package/src/factory.ts

@@ -10,6 +10,7 @@ import type {
   AddEventListenerOptionsLike,
   AsyncIteratorOptions,
   EmissionEvent,
+  EventListenerLike,
   EventTargetLike,
   Listener,
   ObservableLike,
@@ -207,6 +208,16 @@ export function createEventTarget<T extends object, E extends Record<string, any
       'subscribe',
       'toObservable',
       'events',
+      'emit',
+      'off',
+      'addListener',
+      'removeListener',
+      'prependListener',
+      'prependOnceListener',
+      'listeners',
+      'rawListeners',
+      'listenerCount',
+      'eventNames',
     ] as const;
 
     for (const name of methodNames) {
@@ -544,13 +555,14 @@ function createEventTargetInternal<E extends Record<string, any>>(
     }
   };
 
-  const addEventListener: EventTargetLike<E>['addEventListener'] = (
-    type,
-    listener,
-    options,
-  ) => {
+  const addListenerInternal = (
+    type: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Internal helper; callers provide type-safe wrappers
+    listener: EventListenerLike<any> | null,
+    options: AddEventListenerOptionsLike | boolean | undefined,
+    position: 'append' | 'prepend',
+  ): (() => void) => {
     if (isCompleted || !listener) {
-      // Return no-op unsubscribe if already completed
       return () => {};
     }
 
@@ -589,7 +601,12 @@ function createEventTargetInternal<E extends Record<string, any>>(
       signal,
       removed: false,
     };
-    list.push(record);
+
+    if (position === 'prepend') {
+      list.unshift(record);
+    } else {
+      list.push(record);
+    }
 
     const unsubscribe = () => removeListenerRecord(type, record);
 
@@ -603,6 +620,14 @@ function createEventTargetInternal<E extends Record<string, any>>(
     return unsubscribe;
   };
 
+  const addEventListener: EventTargetLike<E>['addEventListener'] = (
+    type,
+    listener,
+    options,
+  ) => {
+    return addListenerInternal(type, listener, options, 'append');
+  };
+
   const addWildcardListener: EventTargetLike<E>['addWildcardListener'] = (
     pattern,
     listener,
@@ -816,11 +841,30 @@ function createEventTargetInternal<E extends Record<string, any>>(
 
   // New ergonomics
 
-  const on: EventTargetLike<E>['on'] = (type, options) => {
-    /* eslint-disable @typescript-eslint/no-explicit-any */
+  const isListenerArg = (
+    arg: unknown,
+  ): arg is EventListenerLike<EmissionEvent<unknown>> => {
+    if (typeof arg === 'function') return true;
+    if (
+      arg &&
+      typeof arg === 'object' &&
+      typeof (arg as { handleEvent?: unknown }).handleEvent === 'function'
+    )
+      return true;
+    return false;
+  };
+
+  /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument */
+  const on: EventTargetLike<E>['on'] = ((type: any, optionsOrListener: any) => {
+    // Node-style overload: on(type, listener) → () => void
+    if (isListenerArg(optionsOrListener)) {
+      return addEventListener(type, optionsOrListener);
+    }
+
+    // Observable-style: on(type, options?) → ObservableLike
+    const options = optionsOrListener as OnOptions | boolean | undefined;
     return new Observable<EmissionEvent<any>>(
       (observer: SubscriptionObserver<EmissionEvent<any>>) => {
-        /* eslint-enable @typescript-eslint/no-explicit-any */
         let opts: OnOptions;
         if (typeof options === 'boolean') {
           opts = { capture: options };
@@ -850,7 +894,6 @@ function createEventTargetInternal<E extends Record<string, any>>(
           observer.error(e.detail);
         };
 
-        /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument */
         const unsubscribeEvent = addEventListener(
           type as keyof E & string,
           eventHandler as any,
@@ -865,7 +908,6 @@ function createEventTargetInternal<E extends Record<string, any>>(
             opts,
           );
         }
-        /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument */
 
         return () => {
           unsubscribeEvent();
@@ -875,7 +917,8 @@ function createEventTargetInternal<E extends Record<string, any>>(
         };
       },
     );
-  };
+  }) as EventTargetLike<E>['on'];
+  /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-argument */
 
   const onceMethod: EventTargetLike<E>['once'] = (type, listener, options) => {
     if (typeof options === 'boolean') {
@@ -1285,6 +1328,89 @@ function createEventTargetInternal<E extends Record<string, any>>(
     return iterator;
   }
 
+  // Node.js EventEmitter compatibility methods
+
+  const emit: EventTargetLike<E>['emit'] = (type, detail) => {
+    if (isCompleted) return false;
+
+    const list = listeners.get(type);
+    const hasListeners = list !== undefined && list.length > 0;
+    let hasWildcard = false;
+    if (wildcardListeners.size > 0) {
+      for (const rec of wildcardListeners) {
+        if (matchesWildcard(type, rec.pattern)) {
+          hasWildcard = true;
+          break;
+        }
+      }
+    }
+
+    dispatchEvent({ type, detail } as Parameters<EventTargetLike<E>['dispatchEvent']>[0]);
+    return hasListeners || hasWildcard;
+  };
+
+  const off: EventTargetLike<E>['off'] = (type, listener) => {
+    removeEventListener(type, listener);
+  };
+
+  const addListener: EventTargetLike<E>['addListener'] = (type, listener) => {
+    return addEventListener(type, listener);
+  };
+
+  const removeListener: EventTargetLike<E>['removeListener'] = (type, listener) => {
+    removeEventListener(type, listener);
+  };
+
+  const prependListener: EventTargetLike<E>['prependListener'] = (type, listener) => {
+    return addListenerInternal(type, listener, undefined, 'prepend');
+  };
+
+  const prependOnceListener: EventTargetLike<E>['prependOnceListener'] = (
+    type,
+    listener,
+  ) => {
+    return addListenerInternal(type, listener, { once: true }, 'prepend');
+  };
+
+  const getListeners: EventTargetLike<E>['listeners'] = (type) => {
+    const list = listeners.get(type);
+    if (!list) return [];
+    return list.filter((r) => !r.removed).map((r) => r.original);
+  };
+
+  const rawListenersMethod: EventTargetLike<E>['rawListeners'] = (type) => {
+    const list = listeners.get(type);
+    if (!list) return [];
+    /* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
+    return list
+      .filter((r) => !r.removed)
+      .map((r) => {
+        if (r.once) {
+          const wrapper = ((...args: any[]) => (r.callback as any)(...args)) as any;
+          wrapper.listener = r.original;
+          return wrapper;
+        }
+        return r.original;
+      });
+    /* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access */
+  };
+
+  const listenerCount: EventTargetLike<E>['listenerCount'] = (type) => {
+    const list = listeners.get(type);
+    if (!list) return 0;
+    return list.filter((r) => !r.removed).length;
+  };
+
+  const eventNamesMethod: EventTargetLike<E>['eventNames'] = () => {
+    const names: string[] = [];
+    for (const [type, list] of listeners) {
+      if (list.some((r) => !r.removed)) {
+        names.push(type);
+      }
+    }
+    return names;
+  };
+
   const target: EventTargetLike<E> = {
     addEventListener,
     removeEventListener,
@@ -1303,6 +1429,16 @@ function createEventTargetInternal<E extends Record<string, any>>(
     subscribe,
     toObservable,
     events,
+    emit,
+    off,
+    addListener,
+    removeListener,
+    prependListener,
+    prependOnceListener,
+    listeners: getListeners,
+    rawListeners: rawListenersMethod,
+    listenerCount,
+    eventNames: eventNamesMethod,
   };
 
   // Add Symbol.observable - return an observable that emits all events from all types

package/src/interoperability.ts

@@ -202,6 +202,16 @@ export function fromEventTarget<E extends Record<string, unknown>>(
       return emitter.completed;
     },
     events: emitter.events,
+    emit: emitter.emit,
+    off: emitter.off,
+    addListener: emitter.addListener,
+    removeListener: emitter.removeListener,
+    prependListener: emitter.prependListener,
+    prependOnceListener: emitter.prependOnceListener,
+    listeners: emitter.listeners,
+    rawListeners: emitter.rawListeners,
+    listenerCount: emitter.listenerCount,
+    eventNames: emitter.eventNames,
     destroy: () => {
       // Clean up abort signal listener to prevent memory leak
       if (options?.signal && onAbort) {

package/src/types.ts

@@ -253,16 +253,53 @@ export interface EventTargetLike<E extends Record<string, any>> {
   clear: () => void;
 
   // Ergonomics
-  on: <K extends keyof E & string>(
-    type: K,
-    options?: OnOptions | boolean,
-  ) => ObservableLike<EmissionEvent<E[K], K>>;
+  on: {
+    <K extends keyof E & string>(
+      type: K,
+      listener: EventListenerLike<EmissionEvent<E[K], K>>,
+    ): () => void;
+    <K extends keyof E & string>(
+      type: K,
+      options?: OnOptions | boolean,
+    ): ObservableLike<EmissionEvent<E[K], K>>;
+  };
   once: <K extends keyof E & string>(
     type: K,
     listener: EventListenerLike<EmissionEvent<E[K], K>> | null,
     options?: Omit<AddEventListenerOptionsLike, 'once'> | boolean,
   ) => () => void;
   removeAllListeners: <K extends keyof E & string>(type?: K) => void;
+
+  // Node.js EventEmitter compatibility
+  emit: <K extends keyof E & string>(type: K, detail: E[K]) => boolean;
+  off: <K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ) => void;
+  addListener: <K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ) => () => void;
+  removeListener: <K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ) => void;
+  prependListener: <K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ) => () => void;
+  prependOnceListener: <K extends keyof E & string>(
+    type: K,
+    listener: EventListenerLike<EmissionEvent<E[K], K>>,
+  ) => () => void;
+  listeners: <K extends keyof E & string>(
+    type: K,
+  ) => Array<EventListenerLike<EmissionEvent<E[K], K>>>;
+  rawListeners: <K extends keyof E & string>(
+    type: K,
+  ) => Array<EventListenerLike<EmissionEvent<E[K], K>>>;
+  listenerCount: <K extends keyof E & string>(type: K) => number;
+  eventNames: () => Array<string>;
   /**
    * Pipe events from this emitter to another target.
    * Forwards all events. If mapFn returns null, the event is skipped.