events-ex 2.3.0 → 2.4.0

package/lib/consts.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Creates an AbortError with name 'AbortError'.
+ * Ensures a fresh Error instance each call for proper stack traces.
+ * @returns {Error}
+ */
+export function createAbortError(): Error;
 export namespace states {
     export { CONTINUE };
     export { DONE };
@@ -5,7 +11,7 @@ export namespace states {
     export { ABORT };
 }
 export const RegExpEventSymbol: symbol | "@@RegExpEvent";
-declare const CONTINUE: any;
+declare const CONTINUE: undefined;
 declare const DONE: 1;
 declare const STOPPED: 2;
 declare const ABORT: -1;

package/lib/consts.js

@@ -3,7 +3,9 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.states = exports.RegExpEventSymbol = void 0;
+exports.RegExpEventSymbol = void 0;
+exports.createAbortError = createAbortError;
+exports.states = void 0;
 const CONTINUE = undefined;
 const DONE = 1;
 const STOPPED = 2;
@@ -14,4 +16,17 @@ const states = exports.states = {
   STOPPED,
   ABORT
 };
-const RegExpEventSymbol = exports.RegExpEventSymbol = typeof Symbol === 'function' ? Symbol('RegExpEvent') : '@@RegExpEvent';
+
+/* v8 ignore next — false branch only reachable without Symbol, which is impossible in Node.js */
+const RegExpEventSymbol = exports.RegExpEventSymbol = typeof Symbol === 'function' ? Symbol('RegExpEvent') : '@@RegExpEvent';
+
+/**
+ * Creates an AbortError with name 'AbortError'.
+ * Ensures a fresh Error instance each call for proper stack traces.
+ * @returns {Error}
+ */
+function createAbortError() {
+  return Object.assign(new Error('The operation was aborted'), {
+    name: 'AbortError'
+  });
+}

package/lib/consts.mjs

@@ -0,0 +1,23 @@
+const CONTINUE = undefined
+const DONE = 1
+const STOPPED = 2
+const ABORT = -1
+
+export const states = {
+  CONTINUE,
+  DONE,
+  STOPPED,
+  ABORT,
+}
+
+/* v8 ignore next — false branch only reachable without Symbol, which is impossible in Node.js */
+export const RegExpEventSymbol = typeof Symbol === 'function' ? Symbol('RegExpEvent') : '@@RegExpEvent'
+
+/**
+ * Creates an AbortError with name 'AbortError'.
+ * Ensures a fresh Error instance each call for proper stack traces.
+ * @returns {Error}
+ */
+export function createAbortError() {
+  return Object.assign(new Error('The operation was aborted'), { name: 'AbortError' })
+}

package/lib/default-methods.d.ts

@@ -4,11 +4,19 @@ export function getEventableMethods(aClass: any): {
      * @param {Object} options - Configuration options for event emission.
      * @param {string} [options.asyncMode='serial'] - The mode of asynchronous emission ('serial' or 'parallel').
      * @param {string} [options.resultMode='last'] - The strategy for handling multiple return values ('last', 'first', 'collect').
+     * @param {AbortSignal} [options.signal] - An AbortSignal to cancel async event emission.
+     * @param {boolean|null} [options.raiseError] - Controls error handling behavior:
+     *   - `true`: Always throw listener errors immediately.
+     *   - `false`: Silently swallow listener errors.
+     *   - `null`: Throw only for 'error' events with no error listeners (Node.js default).
+     *   - `undefined` (default): Same as `false` for emitAsync.
      * @returns {import('./event-emitter').EventEmitter} A proxy object representing the configured EventEmitter.
      */
     configure(options: {
-        asyncMode?: string;
-        resultMode?: string;
+        asyncMode?: string | undefined;
+        resultMode?: string | undefined;
+        signal?: any;
+        raiseError?: boolean | null | undefined;
     }): import("./event-emitter").EventEmitter;
     /**
      * A shortcut for parallel configuration.
@@ -18,10 +26,10 @@ export function getEventableMethods(aClass: any): {
     parallel(resultMode?: string): import("./event-emitter").EventEmitter;
     /**
      * Sets the configuration options for the EventEmitter instance.
-     * @param {Object} options - Configuration options for the emitter (e.g., asyncMode, resultMode, maxListeners).
+     * @param {Object} options - Configuration options for the emitter (e.g., asyncMode, resultMode, maxListeners, raiseError).
      * @returns {import('./event-emitter').EventEmitter} The EventEmitter instance for chaining.
      */
-    setEmitterOptions(options: any): import("./event-emitter").EventEmitter;
+    setEmitterOptions(options: Object): import("./event-emitter").EventEmitter;
     /**
      * Adds a listener function to the specified event type.
      * @param {string|RegExp} type - The event type to listen for.

package/lib/default-methods.js

@@ -23,6 +23,12 @@ function getEventableMethods(aClass) {
      * @param {Object} options - Configuration options for event emission.
      * @param {string} [options.asyncMode='serial'] - The mode of asynchronous emission ('serial' or 'parallel').
      * @param {string} [options.resultMode='last'] - The strategy for handling multiple return values ('last', 'first', 'collect').
+     * @param {AbortSignal} [options.signal] - An AbortSignal to cancel async event emission.
+     * @param {boolean|null} [options.raiseError] - Controls error handling behavior:
+     *   - `true`: Always throw listener errors immediately.
+     *   - `false`: Silently swallow listener errors.
+     *   - `null`: Throw only for 'error' events with no error listeners (Node.js default).
+     *   - `undefined` (default): Same as `false` for emitAsync.
      * @returns {import('./event-emitter').EventEmitter} A proxy object representing the configured EventEmitter.
      */
     configure(options) {
@@ -44,7 +50,7 @@ function getEventableMethods(aClass) {
     },
     /**
      * Sets the configuration options for the EventEmitter instance.
-     * @param {Object} options - Configuration options for the emitter (e.g., asyncMode, resultMode, maxListeners).
+     * @param {Object} options - Configuration options for the emitter (e.g., asyncMode, resultMode, maxListeners, raiseError).
      * @returns {import('./event-emitter').EventEmitter} The EventEmitter instance for chaining.
      */
     setEmitterOptions(options) {
@@ -68,7 +74,7 @@ function getEventableMethods(aClass) {
      * Adds a listener function to the specified event type.
      * @param {string|RegExp} type - The event type to listen for.
      * @param {Function} listener - The listener function to be called when the event is emitted.
-     * @param {number|'first'|'last'} [index] - The index at which to insert the listener. 
+     * @param {number|'first'|'last'} [index] - The index at which to insert the listener.
      *        - 'first' or -Infinity: Adds to the "Head" zone. The first listener added as 'first' is placed at the very front.
      *        - 'last' or Infinity: Adds to the "Tail" zone. The first listener added as 'last' will always be the very last one to execute.
      *        - number: Inserts at the specified index within the "Body" (normal) zone.
@@ -95,8 +101,8 @@ function getEventableMethods(aClass) {
       if (isRegExp(type)) {
         data = data[_consts.RegExpEventSymbol] || (data[_consts.RegExpEventSymbol] = create(null));
       }
-      const isFirst = index === 'first' || index === -Infinity;
-      const isLast = index === 'last' || index === Infinity;
+      const isFirst = index === -Infinity || index === 'first';
+      const isLast = index === Infinity || index === 'last';
       if (!data[type]) {
         if (isFirst || isLast || typeof index === 'number') {
           data[type] = [listener];
@@ -158,11 +164,14 @@ function getEventableMethods(aClass) {
       }
       let fired = false;
       const self = this;
-      async function _once() {
+      function _once() {
         self.off(type, _once);
         if (!fired) {
           fired = true;
-          await listener.apply(this, arguments);
+          const result = listener.apply(this, arguments);
+          if (result instanceof Promise) {
+            return result;
+          }
         }
       }
       _once.listener = listener;
@@ -184,6 +193,8 @@ function getEventableMethods(aClass) {
       const listeners = r.listeners;
       const evt = (0, _event.Event)(this, r.type);
       const errs = [];
+      const opts = _getOptions(this);
+      let _throwErr;
       try {
         let i = 0;
         let listener;
@@ -194,6 +205,9 @@ function getEventableMethods(aClass) {
               break;
             }
           } catch (err) {
+            if (opts.raiseError === true) {
+              throw err;
+            }
             errs.push({
               err: err,
               listener: listener
@@ -204,13 +218,20 @@ function getEventableMethods(aClass) {
         if (errs.length) {
           for (let i = 0; i < errs.length; i++) {
             const it = errs[i];
+            if (r.type === 'error') {
+              throw it.err;
+            }
             this.emit('error', it.err, 'notify', r.type, it.listener, args);
           }
         }
       } finally {
-        // eslint-disable-next-line no-unsafe-finally
-        return evt.end();
+        if (r.type === 'error' && opts.raiseError === null) {
+          const err = args[0];
+          _throwErr = err instanceof Error ? err : new Error(UnCAUGHT_ERR);
+        }
       }
+      if (_throwErr) throw _throwErr;
+      return evt.end();
     },
     /**
      * Asynchronously emits the specified event type with the given arguments.
@@ -219,6 +240,10 @@ function getEventableMethods(aClass) {
      */
     async emitAsync(/* type, msg , ... */
     ) {
+      const options = Object.assign({}, this._emitterOptions, this._eeRuntimeOptions);
+      if (options.signal && options.signal.aborted) {
+        throw (0, _consts.createAbortError)();
+      }
       const r = _emit.apply(this, arguments);
       if (!r) {
         return;
@@ -226,13 +251,29 @@ function getEventableMethods(aClass) {
       const args = r.args;
       const listeners = r.listeners;
       const evt = (0, _event.Event)(this, r.type);
-      const options = Object.assign({}, this._emitterOptions, this._eeRuntimeOptions);
+      let _throwErr;
       try {
         await _executeAsync.call(this, listeners, evt, args, options);
-      } finally {
-        // eslint-disable-next-line no-unsafe-finally
+      } catch (err) {
+        if (err && err.name === 'AbortError') throw err;
+        if (options.raiseError === true) throw err;
+        if (r.type === 'error') {
+          Object.defineProperty(err, '_errorInError', {
+            value: true,
+            enumerable: false
+          });
+          throw err;
+        }
+        if (err && err._errorInError) throw err;
+        // Other unexpected errors: still return the event result
         return evt.end();
       }
+      if (r.type === 'error' && options.raiseError === null) {
+        const err = args[0];
+        _throwErr = err instanceof Error ? err : new Error(UnCAUGHT_ERR);
+      }
+      if (_throwErr) throw _throwErr;
+      return evt.end();
     },
     setMaxListeners(n) {
       if (!(0, _utilEx.isNumber)(n) || n < 0 || isNaN(n)) {
@@ -408,6 +449,15 @@ function getEventableMethods(aClass) {
   };
 }
 var _default = exports.default = getEventableMethods;
+/**
+ * Merges instance-level emitter options with per-call runtime options.
+ * Runtime options (set via configure()) take precedence.
+ * @param {Object} self - The emitter instance.
+ * @returns {Object} Merged options.
+ */
+function _getOptions(self) {
+  return Object.assign({}, self._emitterOptions, self._eeRuntimeOptions);
+}
 function _emit(type, msg) {
   const data = this._events;
   let listeners;
@@ -423,8 +473,26 @@ function _emit(type, msg) {
       args.push(msg);
     }
   }
+  if (type === 'error') {
+    const opts = _getOptions(this);
+    // raiseError: true → always throw, bypass listener dispatch
+    if (opts.raiseError === true) {
+      /* v8 ignore next — msg is guaranteed truthy here; falsy case is caught by earlier !msg check */
+      if (!(msg instanceof Error)) {
+        msg = new Error(msg ? UnCAUGHT_ERR + msg : UnCAUGHT_ERR);
+      }
+      throw msg;
+    }
+  }
   // If there is no 'error' event listener then throw.
   if (!listeners && type === 'error') {
+    const opts = _getOptions(this);
+    // raiseError: false → silently return, never throw
+    if (opts.raiseError === false) {
+      return;
+    }
+    // raiseError: undefined / null → Node.js default behavior
+    /* v8 ignore next — msg is guaranteed truthy here; falsy case is caught by earlier !msg check */
     if (!(msg instanceof Error)) {
       msg = new Error(msg ? UnCAUGHT_ERR + msg : UnCAUGHT_ERR);
     }
@@ -481,9 +549,56 @@ function _notify(listener, evt, args) {
   }
   return result;
 }
+
+/**
+ * Creates a promise that rejects with AbortError when the given AbortSignal fires.
+ * Sets evt.aborted = true before rejecting.
+ * @param {AbortSignal} signal - The abort signal to listen on.
+ * @param {import('./event').Event} evt - The event object to mark as aborted.
+ * @returns {Promise<never>} A promise that rejects with AbortError on abort.
+ */
+function _createAbortPromise(signal, evt) {
+  return new Promise((_, reject) => {
+    if (signal.aborted) {
+      evt.aborted = true;
+      reject((0, _consts.createAbortError)());
+      return;
+    }
+    const onAbort = () => {
+      evt.aborted = true;
+      reject((0, _consts.createAbortError)());
+    };
+    signal.addEventListener('abort', onAbort, {
+      once: true
+    });
+  });
+}
+
+/**
+ * Executes all listener promises in parallel and assigns the result to evt.
+ * @param {Promise[]} promises - The listener promises to execute.
+ * @param {import('./event').Event} evt - The event object.
+ * @param {string} resultMode - 'last', 'first', or 'collect'.
+ */
+async function _runParallelListeners(promises, evt, resultMode) {
+  if (resultMode === 'collect') {
+    const wrapped = promises.map(p => p.catch(() => undefined));
+    const results = await Promise.all(wrapped);
+    evt.result = results;
+  } else if (resultMode === 'first') {
+    try {
+      await Promise.any(promises.map(p => p.then(res => res === undefined ? Promise.reject() : res)));
+    } catch (e) {
+      // If all rejected or returned undefined, ignore
+    }
+  } else {
+    await Promise.all(promises.map(p => p.catch(() => undefined)));
+  }
+}
 async function _executeAsync(listeners, evt, args, options) {
   const asyncMode = options.asyncMode || 'serial';
   const resultMode = options.resultMode || 'last';
+  const signal = options.signal;
   const errs = [];
   if (resultMode === 'collect') {
     evt.result = [];
@@ -501,6 +616,9 @@ async function _executeAsync(listeners, evt, args, options) {
       }
       return result;
     } catch (err) {
+      if (options.raiseError === true) {
+        throw err;
+      }
       errs.push({
         err,
         listener
@@ -510,27 +628,44 @@ async function _executeAsync(listeners, evt, args, options) {
   };
   if (asyncMode === 'parallel') {
     const promises = listeners.map(listener => notifyListener(listener));
-    if (resultMode === 'collect') {
-      evt.result = await Promise.all(promises.map(p => p.catch(() => undefined)));
-    } else if (resultMode === 'first') {
-      try {
-        await Promise.any(promises.map(p => p.then(res => res === undefined ? Promise.reject() : res)));
-      } catch (e) {
-        // If all rejected or returned undefined, ignore
+    if (options.raiseError === true) {
+      // Collect all rejections into AggregateError (all parallel listeners start simultaneously)
+      const settled = signal ? await Promise.race([Promise.allSettled(promises), _createAbortPromise(signal, evt)]) : await Promise.allSettled(promises);
+      const rejections = settled.filter(r => r.status === 'rejected').map(r => r.reason);
+      if (rejections.length > 0) {
+        throw rejections.length === 1 ? rejections[0] : new AggregateError(rejections);
       }
     } else {
-      await Promise.all(promises.map(p => p.catch(() => undefined)));
+      const runParallel = () => _runParallelListeners(promises, evt, resultMode);
+      if (signal) {
+        await Promise.race([runParallel(), _createAbortPromise(signal, evt)]);
+      } else {
+        await runParallel();
+      }
     }
   } else {
-    // Serial mode (default)
+    // Serial mode
+    // Only race against abort signal when raiseError is explicitly set;
+    // default (undefined) keeps old behavior: check signal between listeners only.
+    const canRaceAbort = signal && 'raiseError' in options;
     for (const listener of listeners) {
+      // Check AbortSignal before firing the next listener
+      if (signal && signal.aborted) {
+        evt.aborted = true;
+        break;
+      }
       try {
-        const result = await notifyListener(listener);
+        const result = canRaceAbort ? await Promise.race([notifyListener(listener), _createAbortPromise(signal, evt)]) : await notifyListener(listener);
         if (resultMode === 'collect') {
           evt.result.push(result);
         }
         if (evt.stopped || resultMode === 'first' && evt.resolved) break;
       } catch (err) {
+        if (canRaceAbort && err && err.name === 'AbortError') {
+          evt.aborted = true;
+          throw err;
+        }
+        if (options.raiseError === true) throw err;
         if (resultMode === 'collect') {
           evt.result.push(undefined);
         }
@@ -540,7 +675,24 @@ async function _executeAsync(listeners, evt, args, options) {
   if (errs.length) {
     for (let i = 0; i < errs.length; i++) {
       const it = errs[i];
-      this.emit('error', it.err, 'notify', evt.type, it.listener, args);
+      if (evt.type === 'error') {
+        throw it.err;
+      }
+      // Temporarily clear signal so error re-emission is not blocked by an already-aborted signal
+      const savedSignal = this._eeRuntimeOptions && this._eeRuntimeOptions.signal;
+      if (savedSignal) {
+        delete this._eeRuntimeOptions.signal;
+      }
+      try {
+        await this.emitAsync('error', it.err, 'notify', evt.type, it.listener, args);
+      } finally {
+        if (savedSignal) {
+          this._eeRuntimeOptions.signal = savedSignal;
+        }
+      }
     }
   }
+  if (evt.aborted) {
+    throw (0, _consts.createAbortError)();
+  }
 }