events-ex 2.1.0 → 2.2.0

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,6 +14,50 @@ 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.
@@ -143,22 +188,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()
@@ -381,3 +413,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

@@ -28,8 +28,18 @@ export class EventEmitter {
    * @param {Function} listener - The listener function to be removed.
    * @returns {EventEmitter} The EventEmitter instance to allow chaining.
    * @throws {TypeError} If the listener is not a function.
+   * @see {@link removeListener}
    */
   off(eventName: string|RegExp, listener: ListenerCallbackFunc): EventEmitter;
+  /**
+   * Removes a listener function from the specified event type.
+   * @param {string|RegExp} type - The event type to remove the listener from.
+   * @param {Function} listener - The listener function to be removed.
+   * @returns {EventEmitter} The EventEmitter instance to allow chaining.
+   * @throws {TypeError} If the listener is not a function.
+   * @see {@link off}
+   */
+  removeListener(eventName: string|RegExp, listener: ListenerCallbackFunc): EventEmitter;
   /**
    * Emits the specified event type with the given arguments.
    * @param {...*} args - The event type followed by any number of arguments to be passed to the listener functions.
@@ -49,6 +59,13 @@ export class EventEmitter {
    * @returns {EventEmitter} - The event emitter with all listeners removed.
    */
   removeAllListeners(eventName?: string|RegExp): EventEmitter;
+  /**
+   * Sets the maximum number of listeners allowed for the event emitter.
+   *
+   * @param {number} n - The maximum number of listeners to set. Must be a positive integer.
+   * @returns {EventEmitter} The {@link EventEmitter} instance for method chaining.
+   * @throws {TypeError} If `n` is not a positive integer.
+   */
   setMaxListeners(n: number): EventEmitter;
   /**
    * Returns an array of functions that are registered to listen for the specified event.

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.

package/docs/classes/event.Event.md

@@ -1,141 +0,0 @@
-[events-ex](../README.md) / [Exports](../modules.md) / [event](../modules/event.md) / Event
-
-# Class: Event
-
-[event](../modules/event.md).Event
-
-## Table of contents
-
-### Constructors
-
-- [constructor](event.Event.md#constructor)
-
-### Properties
-
-- [result](event.Event.md#result)
-- [stopped](event.Event.md#stopped)
-- [target](event.Event.md#target)
-- [type](event.Event.md#type)
-
-### Methods
-
-- [end](event.Event.md#end)
-- [init](event.Event.md#init)
-
-## Constructors
-
-### constructor
-
-• **new Event**(`target`, `type`): [`Event`](event.Event.md)
-
-Creates a new Event object instance that contains information about the event, such as the target element and the return value of the event.
-
-#### Parameters
-
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `target` | [`EventEmitter`](event_emitter.EventEmitter.md) | Who trigger the event |
-| `type` | `any` | - |
-
-#### Returns
-
-[`Event`](event.Event.md)
-
-- The new Event instance.
-
-**`Classdesc`**
-
-Event Object that contains information about the event, such as the target element and the return value of the event.
-
-#### Defined in
-
-[src/event.js:8](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L8)
-
-## Properties
-
-### result
-
-• **result**: `any`
-
-Keep your event result here if any.
-
-#### Defined in
-
-[src/event.js:38](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L38)
-
-___
-
-### stopped
-
-• **stopped**: `boolean`
-
-Whether stop the bubbling event
-
-#### Defined in
-
-[src/event.js:32](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L32)
-
-___
-
-### target
-
-• **target**: `any`
-
-Who trigger the event
-
-#### Defined in
-
-[src/event.js:26](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L26)
-
-___
-
-### type
-
-• **type**: `string`
-
-The type of the event.
-
-#### Defined in
-
-[src/event.js:44](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L44)
-
-## Methods
-
-### end
-
-▸ **end**(): `any`
-
-Ends the event and returns the result.
-
-#### Returns
-
-`any`
-
-The result of the event.
-
-#### Defined in
-
-[src/event.js:51](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L51)
-
-___
-
-### init
-
-▸ **init**(`target`, `type`): `void`
-
-Initializes the event with the target object.
-
-#### Parameters
-
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `target` | [`EventEmitter`](event_emitter.EventEmitter.md) | The target object for the event. |
-| `type` | `any` | - |
-
-#### Returns
-
-`void`
-
-#### Defined in
-
-[src/event.js:20](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event.js#L20)

package/docs/classes/event_emitter-1.EventEmitter.md

@@ -1,29 +0,0 @@
-[events-ex](../README.md) / [Exports](../modules.md) / [event-emitter](../modules/event_emitter-1.md) / EventEmitter
-
-# Class: EventEmitter
-
-[event-emitter](../modules/event_emitter-1.md).EventEmitter
-
-## Table of contents
-
-### Constructors
-
-- [constructor](event_emitter-1.EventEmitter.md#constructor)
-
-## Constructors
-
-### constructor
-
-• **new EventEmitter**(): [`EventEmitter`](event_emitter-1.EventEmitter.md)
-
-#### Returns
-
-[`EventEmitter`](event_emitter-1.EventEmitter.md)
-
-**`Classdesc`**
-
-Class that represents an event emitter.
-
-#### Defined in
-
-[src/event-emitter.js:8](https://github.com/snowyu/events-ex.js/blob/a6cce2d/src/event-emitter.js#L8)