events-ex 2.3.0 → 2.4.0

package/src/default-methods.js

@@ -1,6 +1,6 @@
 import {defineProperty, isArray, isFunction, isNumber, isObject, isRegExp as _isRegExp, isUndefined, isRegExpStr, toRegExp } from 'util-ex'
 import './util/promise-any'
-import {RegExpEventSymbol} from './consts'
+import {RegExpEventSymbol, createAbortError} from './consts'
 import {Event} from './event';
 
 const create          = Object.create
@@ -19,6 +19,12 @@ export 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) {
@@ -39,7 +45,7 @@ export 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) {
@@ -62,7 +68,7 @@ export 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.
@@ -88,8 +94,8 @@ export function getEventableMethods(aClass) {
         data = data[RegExpEventSymbol] || (data[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') {
@@ -158,11 +164,14 @@ export 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
@@ -183,6 +192,8 @@ export function getEventableMethods(aClass) {
       const listeners = r.listeners
       const evt = Event(this, r.type)
       const errs = []
+      const opts = _getOptions(this)
+      let _throwErr
       try {
         let i = 0
         let listener
@@ -191,6 +202,7 @@ export function getEventableMethods(aClass) {
             _notify(listener, evt, args)
             if (evt.stopped) {break}
           } catch(err) {
+            if (opts.raiseError === true) {throw err}
             errs.push({err: err, listener: listener})
           }
           ++i
@@ -198,13 +210,18 @@ export 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()
     },
 
     /**
@@ -213,18 +230,35 @@ export function getEventableMethods(aClass) {
      * @returns {Promise<*>} A promise that resolves with the result of the event.
      */
     async emitAsync(/* type, msg , ... */) {
+      const options = Object.assign({}, this._emitterOptions, this._eeRuntimeOptions)
+      if (options.signal && options.signal.aborted) {
+        throw createAbortError()
+      }
       const r = _emit.apply(this, arguments)
       if (!r) {return}
       const args = r.args
       const listeners = r.listeners
       const evt = 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) {
@@ -386,6 +420,16 @@ export function getEventableMethods(aClass) {
 
 export 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
@@ -399,8 +443,24 @@ 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)}
     throw msg
   }
@@ -450,9 +510,54 @@ 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(createAbortError())
+      return
+    }
+    const onAbort = () => {
+      evt.aborted = true
+      reject(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') {
@@ -472,6 +577,7 @@ async function _executeAsync(listeners, evt, args, options) {
       }
       return result
     } catch (err) {
+      if (options.raiseError === true) {throw err}
       errs.push({err, listener})
       throw err
     }
@@ -479,27 +585,54 @@ 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)
         }
@@ -507,10 +640,22 @@ async function _executeAsync(listeners, evt, args, options) {
     }
   }
 
-  if (errs.length) {
+      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 createAbortError()
+  }
 }

package/src/event.js

@@ -30,6 +30,12 @@ Event.prototype.init = function(target, type) {
    * @public
    */
   this.stopped = false
+  /**
+   * Whether the event emission was aborted via AbortSignal.
+   * @type {boolean}
+   * @public
+   */
+  this.aborted = false
   /**
    * Whether a result has been resolved (for 'first' result mode)
    * @type {boolean}

package/src/index.js

@@ -9,6 +9,7 @@ export * from './event-emitter'
 export * from './has-listeners'
 export * from './pipe'
 export * from './pipe-async'
+export * from './once-promise'
 export * from './unify'
 export * from './wrap-event-emitter'
 

package/src/once-promise.js

@@ -0,0 +1,80 @@
+// @sourceType: module
+import validObject from './util/valid-object'
+import {createAbortError} from './consts'
+
+/**
+ * Returns a Promise that resolves with the Event object when the specified event is emitted on the given emitter.
+ * If an 'error' event is emitted (and the waiting event is not 'error'), the promise rejects by default.
+ * If the provided AbortSignal is aborted, the promise rejects with an AbortError.
+ *
+ * Note: The resolved Event object's `result` field may not be the final value if other listeners have not yet run.
+ * For the definitive emit return value, use `emit()` or `emitAsync()` directly.
+ *
+ * @param {import('./event-emitter').EventEmitter} emitter - The event emitter to listen on.
+ * @param {string|RegExp} type - The event type to wait for.
+ * @param {Object} [options] - Optional configuration.
+ * @param {AbortSignal} [options.signal] - An AbortSignal to cancel the wait.
+ * @param {boolean|null} [options.raiseError] - Controls behavior when an 'error' event is emitted:
+ *   - `true` / `undefined` (default): The promise rejects with the error.
+ *   - `false`: The promise resolves with the error object instead of rejecting.
+ * @returns {Promise<import('./event').Event>} - A promise that resolves with the Event object.
+ * @throws {TypeError} - If emitter is not a valid event emitter object.
+ */
+export function oncePromise(emitter, type, options) {
+  validObject(emitter)
+
+  const signal = options && options.signal
+  const raiseError = options && options.raiseError
+
+  return new Promise((resolve, reject) => {
+    let onAbort = null
+    let aborted = false
+
+    const cleanup = () => {
+      emitter.off(type, onEvent)
+      if (type !== 'error') {
+        emitter.off('error', onError)
+      }
+      if (signal && onAbort) {
+        signal.removeEventListener('abort', onAbort)
+      }
+    }
+
+    if (signal) {
+      if (signal.aborted) {
+        reject(createAbortError())
+        return
+      }
+      onAbort = () => {
+        /* v8 ignore next — defensive guard, { once: true } ensures callback fires at most once */
+        if (!aborted) {
+          aborted = true
+          cleanup()
+          reject(createAbortError())
+        }
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+    }
+
+    function onEvent() {
+      cleanup()
+      resolve(this) // resolve with the Event object
+    }
+
+    function onError(err) {
+      cleanup()
+      if (raiseError === false) {
+        resolve(err) // resolve with the error instead of rejecting
+      } else {
+        reject(err) // true | null | undefined → reject
+      }
+    }
+
+    emitter.on(type, onEvent)
+    if (type !== 'error') {
+      emitter.on('error', onError)
+    }
+  })
+}
+
+export default oncePromise

package/src/pipe-async.js

@@ -17,7 +17,9 @@ const emit           = methods.emitAsync
  * @param {string} [name='emitAsync'] - The name of the event to pipe (defaults to 'emitAsync').
  * @param {Object} [options] - Configuration for the pipeline.
  * @param {string} [options.asyncMode='serial'] - The mode of propagation ('serial' or 'parallel').
- * @param {string} [options.resultMode] - Strategy for aggregating results from the pipe chain ('collect', 'first').
+ * @param {string} [options.resultMode='last'] - Strategy for aggregating results from the pipe chain ('last', 'first', 'collect').
+ * @param {AbortSignal} [options.signal] - An AbortSignal to cancel forwarding to remaining pipe targets (serial mode only).
+ *   Can also be set on the source emitter via `configure({ signal })`.
  * @returns {Object} - An object with a `close` method that removes the pipeline between the two event emitters.
  * @throws {TypeError} - If either of the arguments is not an event emitter object.
  */
@@ -59,6 +61,9 @@ export function pipeAsync(e1, e2/* , name, options */) {
       return fn.apply(target, args)
     }
 
+    // Read signal from source emitter's runtime options, if configured
+    const signal = this._eeRuntimeOptions && this._eeRuntimeOptions.signal
+
     if (asyncMode === 'parallel') {
       const promises = [emit.apply(this, arguments)]
       for (let i = 0; i < data.length; ++i) {
@@ -67,17 +72,25 @@ export function pipeAsync(e1, e2/* , name, options */) {
       const results = await Promise.all(promises)
       if (resultMode === 'collect') return results
       if (resultMode === 'first') return results.find(r => r !== undefined)
-      return results[0] // Default: return main emitter's result
+      // Default: 'last' — return last non-undefined result in the pipe chain
+      for (let i = results.length - 1; i >= 0; i--) {
+        if (results[i] !== undefined) return results[i]
+      }
     } else {
       const mainResult = await emit.apply(this, arguments)
       const allResults = [mainResult]
       for (let i = 0; i < data.length; ++i) {
+        // Check signal before forwarding to each pipe target in serial mode
+        if (signal && signal.aborted) break
         const res = await forward(data[i], arguments)
         allResults.push(res)
       }
       if (resultMode === 'collect') return allResults
       if (resultMode === 'first') return allResults.find(r => r !== undefined)
-      return mainResult // Default: return main emitter's result
+      // Default: 'last' — return last non-undefined result in the pipe chain
+      for (let i = allResults.length - 1; i >= 0; i--) {
+        if (allResults[i] !== undefined) return allResults[i]
+      }
     }
   }
   defineProperty(e1, name, desc.value, desc)

package/src/unify.js

@@ -1,7 +1,7 @@
 import validObject from './util/valid-object'
 import forEach from './util/object-for-each'
 
-const push = Array.prototype.apply
+const push = Array.prototype.push
 const defineProperty = Object.defineProperty
 const create = Object.create
 const hasOwnProperty = Object.prototype.hasOwnProperty

package/tsconfig.json

@@ -17,7 +17,8 @@
       // Types should go into this directory.
       // Removing this would place the .d.ts files
       // next to the .js files
-      "outDir": "types"
+      "outDir": "lib",
+      "rootDir": "./src"
     },
     "typedocOptions": {
       "entryPointStrategy": "expand",

package/vitest.config.js

@@ -0,0 +1,61 @@
+import { defineConfig } from 'vitest/config'
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+
+// util-ex has an exports field that only exposes "." and blocks deep
+// imports like 'util-ex/lib/defineProperty'. Dependencies like
+// custom-ability also import many util-ex/lib/ subpaths via bare
+// specifiers (e.g., 'util-ex/lib/is/type/array').
+//
+// Vite's resolver strictly enforces the exports field, so we need
+// to intercept resolution at a low level. We do this by having a
+// Vite plugin that patches the util-ex package.json at config
+// resolution time, adding wildcard exports for the lib directory.
+
+export default defineConfig({
+  plugins: [
+    {
+      name: 'fix-util-ex-resolution',
+      configResolved() {
+        const pkgPath = path.resolve(__dirname, 'node_modules/util-ex/package.json')
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+        if (!pkg._patched) {
+          pkg.exports = {
+            '.': pkg.exports['.'],
+            './lib/*': {
+              import: './lib/*.mjs',
+              require: './lib/*.js',
+            },
+          }
+          pkg._patched = true
+          fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+        }
+      },
+    },
+  ],
+  test: {
+    globals: true,
+    include: ['test/**/*-test.js'],
+    reporters: ['verbose'],
+    coverage: {
+      provider: 'v8',
+      reportsDirectory: './coverage',
+      reporter: ['text', 'html', 'lcov', 'clover'],
+      include: ['src/**'],
+      exclude: [
+        'src/index.js',
+        'src/event-emitter.d.ts',
+        'src/util/**',
+      ],
+      thresholds: {
+        statements: 80,
+        branches: 70,
+        functions: 80,
+        lines: 80,
+      },
+    },
+  },
+})

package/.mocharc.yml

@@ -1,3 +0,0 @@
-require: '@babel/register'
-spec:
-  - 'test/**/*-test.js' # the positional arguments!