events-ex 2.1.1 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "events-ex",
-  "version": "2.1.1",
+  "version": "2.3.0",
   "description": "Browser-friendly enhanced events most compatible with standard node.js, it's powerful eventable ability.",
   "contributors": [
     {
@@ -37,25 +37,25 @@
   "main": "./lib/index.js",
   "module": "./src/index.js",
   "dependencies": {
-    "custom-ability": "^2.0.1",
-    "util-ex": "^2.0.0"
+    "custom-ability": "^2.1.0",
+    "util-ex": "^2.5.1"
   },
   "devDependencies": {
-    "@antfu/eslint-config": "^2.6.1",
-    "@babel/cli": "^7.23.4",
-    "@babel/core": "^7.23.7",
+    "@antfu/eslint-config": "^7.7.0",
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.29.0",
     "@babel/plugin-proposal-dynamic-import": "^7.18.6",
-    "@babel/plugin-transform-modules-commonjs": "^7.23.3",
-    "@babel/register": "^7.23.7",
-    "chai": "~4.3.7",
-    "eslint": "^8.56.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-tsdoc": "^0.2.17",
-    "mocha": "^10.6.0",
-    "prettier": "^3.1.1",
-    "typedoc": "^0.25.4",
-    "typedoc-plugin-markdown": "^3.17.1",
-    "typescript": "^5.3.3"
+    "@babel/plugin-transform-modules-commonjs": "^7.28.6",
+    "@babel/register": "^7.28.6",
+    "chai": "~4.3.10",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "mocha": "^11.7.5",
+    "prettier": "^3.8.1",
+    "typedoc": "^0.28.17",
+    "typedoc-plugin-markdown": "^4.10.0",
+    "typescript": "~5.7.3"
   },
   "scripts": {
     "build": "npm run build.cjs && npm run build.ts && npm run doc.md",

package/src/default-methods.js

@@ -1,4 +1,5 @@
 import {defineProperty, isArray, isFunction, isNumber, isObject, isRegExp as _isRegExp, isUndefined, isRegExpStr, toRegExp } from 'util-ex'
+import './util/promise-any'
 import {RegExpEventSymbol} from './consts'
 import {Event} from './event';
 
@@ -13,11 +14,59 @@ function isRegExp(value) {
 
 export function getEventableMethods(aClass) {
   return {
+    /**
+     * Configures the event emitter with specified options using a Fluent API.
+     * @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').
+     * @returns {import('./event-emitter').EventEmitter} A proxy object representing the configured EventEmitter.
+     */
+    configure(options) {
+      const proxy = Object.create(this)
+      const mergedOptions = Object.assign({}, this._eeRuntimeOptions, options)
+      defineProperty(proxy, '_eeRuntimeOptions', mergedOptions)
+      return proxy
+    },
+
+    /**
+     * A shortcut for parallel configuration.
+     * @param {string} [resultMode='last'] - The strategy for handling multiple return values.
+     * @returns {import('./event-emitter').EventEmitter} A proxy object representing the configured EventEmitter.
+     */
+    parallel(resultMode) {
+      return this.configure({asyncMode: 'parallel', resultMode: resultMode || 'last'})
+    },
+
+    /**
+     * Sets the configuration options for the EventEmitter instance.
+     * @param {Object} options - Configuration options for the emitter (e.g., asyncMode, resultMode, maxListeners).
+     * @returns {import('./event-emitter').EventEmitter} The EventEmitter instance for chaining.
+     */
+    setEmitterOptions(options) {
+      if (!isObject(options)) {return this}
+      let data
+      if (!this.hasOwnProperty('_emitterOptions')) {
+        data = create(null)
+        defineProperty(this, '_emitterOptions', data)
+      } else {
+        data = this._emitterOptions
+      }
+      Object.assign(data, options)
+      if (!isUndefined(options.maxListeners) && isFunction(this.setMaxListeners)) {
+        this.setMaxListeners(options.maxListeners)
+      }
+      return this
+    },
+
     /**
      * 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} [index] - The index at which to insert the listener. If not specified, the listener will be added at the end of the listeners array.
+     * @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.
+     *        If not specified, the listener is added to the end of the "Body" zone.
      * @returns {import('./event-emitter').EventEmitter} The EventEmitter instance to allow chaining.
      * @throws {TypeError} If the listener is not a function.
      */
@@ -38,16 +87,38 @@ export function getEventableMethods(aClass) {
       if (isRegExp(type)) {
         data = data[RegExpEventSymbol] || (data[RegExpEventSymbol] = create(null))
       }
-      if  (!data[type]) {
-        data[type] = listener
-      } else if (isObject(data[type])) {
-        if (typeof index === 'number') {
-          data[type].splice(index, 0, listener)
+
+      const isFirst = index === 'first' || index === -Infinity
+      const isLast = index === 'last' || index === Infinity
+
+      if (!data[type]) {
+        if (isFirst || isLast || typeof index === 'number') {
+          data[type] = [listener]
+          if (isFirst) data[type]._headCount = 1
+          if (isLast) data[type]._tailCount = 1
         } else {
-          data[type].push(listener)
+          data[type] = listener
         }
       } else {
-        data[type] = [data[type], listener]
+        if (isFunction(data[type])) {
+          data[type] = [data[type]]
+        }
+        const listeners = data[type]
+        const headCount = listeners._headCount || 0
+        const tailCount = listeners._tailCount || 0
+
+        if (isFirst) {
+          listeners.splice(headCount, 0, listener)
+          listeners._headCount = headCount + 1
+        } else if (isLast) {
+          listeners.splice(listeners.length - tailCount, 0, listener)
+          listeners._tailCount = tailCount + 1
+        } else if (typeof index === 'number' && !isNaN(index)) {
+          const pos = Math.min(Math.max(headCount + index, headCount), listeners.length - tailCount)
+          listeners.splice(pos, 0, listener)
+        } else {
+          listeners.splice(listeners.length - tailCount, 0, listener)
+        }
       }
       // Check for listener leak
       if (isObject(data[type]) && !data[type].warned) {
@@ -74,7 +145,11 @@ export function getEventableMethods(aClass) {
      * Adds a one-time 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 once when the event is emitted.
-     * @param {number} [index] - The index at which to insert the listener. If not specified, the listener will be added at the end of the listeners array.
+     * @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.
+     *        If not specified, the listener is added to the end of the "Body" zone.
      * @returns {import('./event-emitter').EventEmitter} The EventEmitter instance to allow chaining.
      * @throws {TypeError} If the listener is not a function.
      */
@@ -143,22 +218,9 @@ export function getEventableMethods(aClass) {
       const args = r.args
       const listeners = r.listeners
       const evt = Event(this, r.type)
-      const errs = []
+      const options = Object.assign({}, this._emitterOptions, this._eeRuntimeOptions)
       try {
-        for (const listener of listeners) {
-          try {
-            await _notify(listener, evt, args);
-            if (evt.stopped) {break}
-          } catch(err) {
-            errs.push({err: err, listener: listener})
-          }
-        }
-        if (errs.length) {
-          for (let i=0;i<errs.length;i++) {
-            const it = errs[i]
-            this.emit('error', it.err, 'notify', r.type, it.listener, args)
-          }
-        }
+        await _executeAsync.call(this, listeners, evt, args, options)
       } finally {
         // eslint-disable-next-line no-unsafe-finally
         return evt.end()
@@ -243,10 +305,16 @@ export function getEventableMethods(aClass) {
           if (candidate === listener || candidate.listener === listener) {break}
         }
         if (i < 0) {return this}
+
+        if (listeners._headCount && i < listeners._headCount) {
+          listeners._headCount--
+        } else if (listeners._tailCount && i >= listeners.length - listeners._tailCount) {
+          listeners._tailCount--
+        }
+
         if (listeners.length === 1) {
-          listeners.length = 0
           delete data[type]
-        } else if (listeners.length === 2) {
+        } else if (listeners.length === 2 && !listeners._headCount && !listeners._tailCount) {
           data[type] = listeners[(i ? 0 : 1)]
           listeners.length = 1
         } else {
@@ -381,3 +449,68 @@ function _notify(listener, evt, args) {
   }
   return result
 }
+
+async function _executeAsync(listeners, evt, args, options) {
+  const asyncMode = options.asyncMode || 'serial'
+  const resultMode = options.resultMode || 'last'
+  const errs = []
+
+  if (resultMode === 'collect') {
+    evt.result = []
+  }
+
+  const notifyListener = async (listener) => {
+    try {
+      const result = await _notify(listener, evt, args)
+      if (result !== undefined) {
+        if (resultMode === 'first' && !evt.resolved) {
+          evt.result = result
+          evt.resolved = true
+        } else if (resultMode === 'last') {
+          evt.result = result
+        }
+      }
+      return result
+    } catch (err) {
+      errs.push({err, listener})
+      throw err
+    }
+  }
+
+  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
+      }
+    } else {
+      await Promise.all(promises.map(p => p.catch(() => undefined)))
+    }
+  } else {
+    // Serial mode (default)
+    for (const listener of listeners) {
+      try {
+        const result = await notifyListener(listener)
+        if (resultMode === 'collect') {
+          evt.result.push(result)
+        }
+        if (evt.stopped || (resultMode === 'first' && evt.resolved)) break
+      } catch (err) {
+        if (resultMode === 'collect') {
+          evt.result.push(undefined)
+        }
+      }
+    }
+  }
+
+  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)
+    }
+  }
+}

package/src/event-emitter.d.ts

@@ -10,18 +10,28 @@ export class EventEmitter {
    * 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.
+   *        - 'first' or -Infinity: adds to the beginning of the listeners (stay at the front).
+   *        - 'last' or Infinity: adds to the end of the listeners (stay at the back).
+   *        - number: inserts at the specified index within the normal listeners zone.
+   *        If not specified, the listener will be added at the end of the normal listeners.
    * @returns {EventEmitter} The EventEmitter instance to allow chaining.
    * @throws {TypeError} If the listener is not a function.
    */
-  on(eventName: string|RegExp, listener: ListenerCallbackFunc): EventEmitter;
+  on(eventName: string|RegExp, listener: ListenerCallbackFunc, index?: number|'first'|'last'): EventEmitter;
   /**
    * Adds a one-time 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 once when the event is emitted.
+   * @param {number|'first'|'last'} [index] - The index at which to insert the listener.
+   *        - 'first' or -Infinity: adds to the beginning of the listeners (stay at the front).
+   *        - 'last' or Infinity: adds to the end of the listeners (stay at the back).
+   *        - number: inserts at the specified index within the normal listeners zone.
+   *        If not specified, the listener will be added at the end of the normal listeners.
    * @returns {EventEmitter} The EventEmitter instance to allow chaining.
    * @throws {TypeError} If the listener is not a function.
    */
-  once(eventName: string|RegExp, listener: ListenerCallbackFunc): EventEmitter;
+  once(eventName: string|RegExp, listener: ListenerCallbackFunc, index?: number|'first'|'last'): EventEmitter;
   /**
    * Removes a listener function from the specified event type.
    * @param {string|RegExp} type - The event type to remove the listener from.

package/src/event.js

@@ -30,6 +30,12 @@ Event.prototype.init = function(target, type) {
    * @public
    */
   this.stopped = false
+  /**
+   * Whether a result has been resolved (for 'first' result mode)
+   * @type {boolean}
+   * @public
+   */
+  this.resolved = false
   /**
    * Keep your event result here if any.
    * @type {*}

package/src/eventable.js

@@ -25,6 +25,9 @@ function getEventableClass(aClass) {
   Eventable.prototype.listenerCount = methods.listenerCount;
   Eventable.prototype.emit = methods.emit;
   Eventable.prototype.emitAsync = methods.emitAsync;
+  Eventable.prototype.configure = methods.configure;
+  Eventable.prototype.parallel = methods.parallel;
+  Eventable.prototype.setEmitterOptions = methods.setEmitterOptions;
   Eventable.prototype.on = methods.on;
   Eventable.prototype.addListener = methods.on;
   Eventable.prototype.off = methods.off;

package/src/pipe-async.js

@@ -15,39 +15,73 @@ const emit           = methods.emitAsync
  * @param {import('./event-emitter').EventEmitter} e1 - The first event emitter.
  * @param {import('./event-emitter').EventEmitter} e2 - The second event emitter.
  * @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').
  * @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.
  */
-export function pipeAsync(e1, e2/* , name */) {
-	let pipes
-
-	(validObject(e1) && validObject(e2))
-	let name = arguments[2]
-	if (name === undefined) {name = 'emitAsync'}
-
-	const result = {
-		close() { arrRemove.call(pipes, e2) }
-	};
-	if (hasOwnProperty.call(e1, '__eePipes__')) {
-		(pipes = e1.__eePipes__).push(e2)
-		return result
-	}
-	defineProperty(e1, '__eePipes__', pipes = [e2])
-	let desc = getOwnPropertyDescriptor(e1, name)
-	if (!desc) {
-		desc = {}
-	} else {
-		delete desc.get
-		delete desc.set
-	}
-	desc.value = async function () {
-		const data = arrFrom(pipes)
-		await emit.apply(this, arguments)
-		let emitter
-		for (let i = 0; (emitter = data[i]); ++i) await emit.apply(emitter, arguments)
-	}
-	defineProperty(e1, name, desc.value, desc)
-	return result
+export function pipeAsync(e1, e2/* , name, options */) {
+  let pipes
+
+  (validObject(e1) && validObject(e2))
+  let name = arguments[2]
+  let options = arguments[3]
+  if (typeof name === 'object') {
+    options = name
+    name = undefined
+  }
+  if (name === undefined) {name = 'emitAsync'}
+  if (!options) {options = {}}
+
+  const result = {
+    close() { arrRemove.call(pipes, e2) }
+  };
+  if (hasOwnProperty.call(e1, '__eePipes__')) {
+    (pipes = e1.__eePipes__).push(e2)
+    return result
+  }
+  defineProperty(e1, '__eePipes__', pipes = [e2])
+  let desc = getOwnPropertyDescriptor(e1, name)
+  if (!desc) {
+    desc = {}
+  } else {
+    delete desc.get
+    delete desc.set
+  }
+  desc.value = async function () {
+    const data = arrFrom(pipes)
+    const asyncMode = options.asyncMode || 'serial'
+    const resultMode = options.resultMode
+
+    const forward = async (target, args) => {
+      const fn = target[name] || target.emitAsync || emit
+      return fn.apply(target, args)
+    }
+
+    if (asyncMode === 'parallel') {
+      const promises = [emit.apply(this, arguments)]
+      for (let i = 0; i < data.length; ++i) {
+        promises.push(forward(data[i], arguments))
+      }
+      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
+    } else {
+      const mainResult = await emit.apply(this, arguments)
+      const allResults = [mainResult]
+      for (let i = 0; i < data.length; ++i) {
+        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
+    }
+  }
+  defineProperty(e1, name, desc.value, desc)
+  return result
 };
 
 export default pipeAsync

package/src/util/promise-any.js

@@ -0,0 +1,45 @@
+/**
+ * Simple polyfill for AggregateError if it doesn't exist.
+ */
+const _AggregateError = typeof AggregateError !== 'undefined'
+  ? AggregateError
+  : function AggregateError(errors, message) {
+    const error = new Error(message);
+    error.name = 'AggregateError';
+    error.errors = errors;
+    return error;
+  };
+
+/**
+ * Ensures Promise.any exists, or provides a polyfill.
+ */
+if (typeof Promise.any !== 'function') {
+  Promise.any = function (promises) {
+    return new Promise((resolve, reject) => {
+      promises = Array.from(promises);
+      const len = promises.length;
+      let errors = [];
+      let rejectedCount = 0;
+
+      if (len === 0) {
+        return reject(new _AggregateError(errors, 'All promises were rejected'));
+      }
+
+      promises.forEach((promise, index) => {
+        Promise.resolve(promise)
+          .then((value) => {
+            resolve(value);
+          })
+          .catch((error) => {
+            errors[index] = error;
+            rejectedCount++;
+            if (rejectedCount === len) {
+              reject(new _AggregateError(errors, 'All promises were rejected'));
+            }
+          });
+      });
+    });
+  };
+}
+
+export default Promise.any;

package/src/wrap-event-emitter.js

@@ -6,36 +6,41 @@ const defineProperties = Object.defineProperties;
 
 export const methods = eventable().methods;
 
+/**
+ * Minimal set of core methods to be injected into an existing object.
+ */
 const descriptors = {
-  on: {
-    value: methods.on
-  },
-  once: {
-    value: methods.once
-  },
-  off: {
-    value: methods.off
-  },
-  emit: {
-    value: methods.emit
-  },
-  emitAsync: {
-    value: methods.emitAsync
-  },
+  on: { value: methods.on },
+  once: { value: methods.once },
+  off: { value: methods.off },
+  emit: { value: methods.emit },
+  emitAsync: { value: methods.emitAsync },
+  setEmitterOptions: { value: methods.setEmitterOptions },
 };
 
-const base = defineProperties({}, descriptors);
+/**
+ * Full set of all available methods from eventable for standalone instances.
+ */
+const fullDescriptors = {};
+Object.keys(methods).forEach(key => {
+  fullDescriptors[key] = { value: methods[key] };
+});
+
+const base = defineProperties({}, fullDescriptors);
 
 /**
  * Create or inject the eventable instance into the object
  * @param {Object} [o] the optional instance to eventable
+ * @param {Object} [options] optional configuration for the emitter
  * @returns o or new Event instance
  */
-export function wrapEventEmitter(o) {
+export function wrapEventEmitter(o, options) {
   const result = o == null ? create(base) : defineProperties(Object(o), descriptors)
   defineProperty(result, '_events', {})
+  if (options && options.emitterOptions) {
+    result.setEmitterOptions(options.emitterOptions)
+  }
   return result
 };
 
-
 export default wrapEventEmitter

package/docs/.nojekyll

@@ -1 +0,0 @@
-TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.