@creejs/commons-events 2.0.2 → 2.0.3

package/lib/event-emitter.js

@@ -1,373 +0,0 @@
-// 3rd
-// internal
-import { TypeUtils, TypeAssert } from '@creejs/commons-lang'
-
-// owned
-import Event from './event.js'
-// eslint-disable-next-line no-unused-vars
-import Listener from './listener.js'
-
-// module vars
-const { isNil } = TypeUtils
-const {
-  assertString, assertFunction, assertNumber,
-  assertStringOrSymbol, assertNotNil
-} = TypeAssert
-
-/**
- * methods allowed to mixin other objects
- */
-const MixinMethods = [
-  'on', 'once', 'addListener', 'prependListener', 'prependOnceListener',
-  'off', 'offAll', 'offOwner', 'removeAllListeners', 'removeListener',
-  'emit', 'setMaxListeners', 'getMaxListeners', 'hasOwner',
-  'listeners', 'listenerCount', 'eventNames', 'rawListeners'
-]
-let DefaultMaxListeners = 10
-/**
- * 1. An EventEmitter follows the API of NodeJS EventEmitter.
- * 2. Enhancement:
- *    * Listeners are grouped by "owner".
- *    * Operation via "owner"
- *    * Duplicate listeners are filtered out. Only unique One kept.
- */
-export default class EventEmitter {
-  /**
-   * Mixes EventEmitter methods into the given object.
-   * @template T
-   * @param {T} obj - The target object to mix methods into.
-   * @returns {T} The modified object with EventEmitter methods.
-   */
-  static mixin (obj) {
-    const emitter = new EventEmitter()
-    // @ts-ignore
-    obj.__emitter = emitter
-    for (const name of MixinMethods) {
-      // @ts-ignore
-      const method = emitter[name]
-      // @ts-ignore
-      obj[name] = method.bind(emitter)
-    }
-    return obj
-  }
-
-  static get defaultMaxListeners () {
-    return DefaultMaxListeners
-  }
-
-  static set defaultMaxListeners (maxListeners) {
-    assertNumber(maxListeners)
-    DefaultMaxListeners = maxListeners ?? 10
-  }
-
-  /**
-   */
-  constructor () {
-    /**
-     * @type {Map<string|Symbol, Event>}
-     */
-    this._name2Event = new Map()
-    this._maxListeners = DefaultMaxListeners
-  }
-
-  /**
-   * Alias of {@linkcode EventEmitter.addListener}
-   * @param {string|Symbol} eventName
-   * @param {function} listener
-   * @param {*} [owner]
-   * @returns {this}
-   */
-  addListener (eventName, listener, owner) {
-    return this.on(eventName, listener, owner)
-  }
-
-  /**
-   * Adds the listener function to the beginning of the listeners array for the event named eventName.
-   * @param {string|Symbol} eventName
-   * @param {function} listener
-   * @param {*} [owner]
-   * @returns {this}
-   */
-  prependListener (eventName, listener, owner) {
-    assertString(eventName)
-    assertFunction(listener)
-    this._checkMaxListeners(eventName)
-
-    const event = this._getOrCreateEvent(eventName)
-    event.prependListener(listener, owner)
-    return this
-  }
-
-  /**
-   * Adds a one-time listener function for the event named eventName to the beginning of the listeners array.
-   * @param {string|Symbol} eventName
-   * @param {function} listener
-   * @param {*} [owner]
-   * @returns {this}
-   */
-  prependOnceListener (eventName, listener, owner) {
-    assertString(eventName)
-    assertFunction(listener)
-    this._checkMaxListeners(eventName)
-
-    const event = this._getOrCreateEvent(eventName)
-    event.prependOnceListener(listener, owner)
-    return this
-  }
-
-  /**
-   * Synchronously calls each of the listeners registered for the event named eventName,
-   * in the order they were registered, passing the supplied arguments to each.
-   * Returns true if the event had listeners, false otherwise.
-   * @param {string|Symbol} eventName - The name of the event.
-   * @param {...*} args arguments to pass to the listeners.
-   * @returns {boolean}
-   */
-  emit (eventName, ...args) {
-    const event = this._name2Event.get(eventName)
-    if (event == null || event.isEmpty()) {
-      return false
-    }
-    event.emit(...args)
-    return true
-  }
-
-  /**
-   * Returns an array listing the events for which the emitter has registered listeners.
-   * @returns {Array<string|Symbol>} An array of event names.
-   */
-  eventNames () {
-    return [...this._name2Event.keys()]
-  }
-
-  getMaxListeners () {
-    return this._maxListeners
-  }
-
-  /**
-   * Returns the number of listeners listening for the event named eventName.
-   * If listener is provided, it will return how many times the listener is found
-   * in the list of the listeners of the event.
-   * @param {string|Symbol} eventName - The name of the event to check
-   * @param {function} [listener] - Optional specific listener to count
-   * @returns {number} The number of listeners for the event
-   */
-  listenerCount (eventName, listener) {
-    assertStringOrSymbol(eventName, 'eventName')
-    const event = this._name2Event.get(eventName)
-    if (event == null || event.isEmpty()) {
-      return 0
-    }
-    return event.listenerCount(listener)
-  }
-
-  /**
-   * Returns a copy of the array of listeners for the event named eventName.
-   * 1. if a callback function added multiple times, it will be returned multiple times.
-   * @param {string} eventName
-   * @returns {Array<function>}
-   */
-  listeners (eventName) {
-    assertStringOrSymbol(eventName, 'eventName')
-    const event = this._name2Event.get(eventName)
-    if (event == null || event.isEmpty()) {
-      return []
-    }
-    return event.callbacks()
-  }
-
-  /**
-   * Removes a callback function from a specific event.
-   * 1. If the event doesn't exist or has no listeners, do nothing
-   * 2. if one callback function added multiple times, all of them will be removed.
-   *    * !!! This is different from the behavior of Node.js EventEmitter.
-   *
-   * @param {string} eventName - The name of the event to remove callback from
-   * @param {function} callback - The callback function to remove
-   * @returns {EventEmitter} Returns the emitter instance for chaining
-   */
-  off (eventName, callback) {
-    const event = this._name2Event.get(eventName)
-    if (event == null) {
-      return this
-    }
-    event.removeListener(callback)
-    if (event.isEmpty()) {
-      this._name2Event.delete(eventName)
-      return this
-    }
-    return this
-  }
-
-  /**
-   * Removes all listeners for the specified event.
-   * if owner is limited, only the listeners of the owner will be removed.
-   *
-   * @param {string|Symbol} eventName - The name of the event to clear listeners for.
-   * @param {*} owner - The owner whose listeners should be removed.
-   * @returns {EventEmitter} The emitter instance for chaining.
-   */
-  offAll (eventName, owner) {
-    assertStringOrSymbol(eventName, 'eventName')
-    const event = this._name2Event.get(eventName)
-    if (event == null) {
-      return this
-    }
-    event.removeAllListeners(owner)
-    if (event.isEmpty()) {
-      this._name2Event.delete(eventName)
-      return this
-    }
-    return this
-  }
-
-  /**
-   * Removes all event listeners belonging to the specified owner.
-   * @param {*} owner - The owner whose listeners should be removed.
-   * @returns {this}
-   */
-  offOwner (owner) {
-    assertNotNil(owner, 'owner')
-    const events = [...this._name2Event.values()]
-    for (const event of events) {
-      event.removeAllListeners(owner)
-      if (event.isEmpty()) {
-        this._name2Event.delete(event.name)
-      }
-    }
-    return this
-  }
-
-  /**
-   * Adds the listener function to the end of the listeners array for the event named eventName.
-   * @param {string|Symbol} eventName
-   * @param {function} callback
-   * @param {*} [owner]
-   * @returns {this}
-   */
-  on (eventName, callback, owner) {
-    assertString(eventName)
-    assertFunction(callback)
-    this._checkMaxListeners(eventName)
-
-    const event = this._getOrCreateEvent(eventName)
-    event.addListener(callback, owner)
-    return this
-  }
-
-  /**
-   * Checks if the number of listeners for the given event exceeds the maximum allowed.
-   * Emits a warning if the listener count reaches or exceeds the maxListeners threshold.
-   * @private
-   * @param {string|Symbol} eventName - The name of the event to check
-   * @returns {void}
-   */
-  _checkMaxListeners (eventName) {
-    let listenerCount = 0
-    if (this._maxListeners !== 0 && this._maxListeners !== Infinity && (listenerCount = this.listenerCount(eventName)) >= this._maxListeners) {
-      console.warn(`maxlistenersexceededwarning: Possible EventEmitter memory leak detected. ${listenerCount} ${eventName} listeners added to [${this}]. Use emitter.setMaxListeners() to increase limit`)
-    }
-  }
-
-  /**
-   * Adds a listener that will be invoked only once for the event named eventName.SIGINT listeners added to [process]. Use emitter.setMaxListeners() to increase limit`)
-    }
-  }
-
-  /**
-   * Adds a one-time callback function for the specified event.
-   * The callback is invoked only once and then automatically removed.
-   *
-   * @param {string} eventName - The name of the event to listen for.
-   * @param {Function} callback - The callback function to execute when the event is emitted.
-   * @param {*} [owner] - Optional owner used to group listener callbacks.
-   * @returns {EventEmitter} Returns the emitter instance for chaining.
-   */
-  once (eventName, callback, owner) {
-    assertString(eventName)
-    assertFunction(callback)
-
-    const event = this._getOrCreateEvent(eventName)
-    event.addOnceListener(callback, owner)
-    return this
-  }
-
-  /**
-   * Returns a copy of the array of listeners for the event named eventName,
-   * including any wrappers (such as those created by .once()).
-   * @param {string} eventName - The name of the event.
-   * @returns {Listener[]} An array of raw listener functions, or empty array if none exist.
-   */
-  rawListeners (eventName) {
-    return this._name2Event.get(eventName)?.rawListeners() || []
-  }
-
-  /**
-   * Alias of {@linkcode EventEmitter.offAll}
-   * @param {string|Symbol} eventName - The name of the event to remove listeners for.
-   * @param {*} owner - The owner of the listeners to be removed.
-   * @returns {EventEmitter} The emitter instance for chaining.
-   */
-  removeAllListeners (eventName, owner) {
-    return this.offAll(eventName, owner)
-  }
-
-  /**
-   * Alias of {@linkcode EventEmitter.off}
-   * @param {string} eventName - The name of the event.
-   * @param {Function} callback - The callback function to remove.
-   * @returns {EventEmitter} The emitter instance for chaining.
-   */
-  removeListener (eventName, callback) {
-    return this.off(eventName, callback)
-  }
-
-  /**
-   * Sets the maximum number of listeners that can be added to this event emitter.
-   * @param {number} max - The maximum number of listeners.
-   * @returns {this} The set maximum number of listeners.
-   */
-  setMaxListeners (max) {
-    assertNumber(max)
-    if (max < 0) {
-      throw new RangeError('maxListeners must >=0')
-    }
-    this._maxListeners = max
-    return this
-  }
-
-  /**
-   * Gets an existing event by name or creates a new one if it doesn't exist.
-   * @private
-   * @param {string|Symbol} eventName - The name of the event to get or create.
-   * @returns {Event} The existing or newly created Event instance.
-   */
-  _getOrCreateEvent (eventName) {
-    if (this._name2Event.has(eventName)) {
-      // @ts-ignore
-      return this._name2Event.get(eventName)
-    }
-    const event = new Event(eventName)
-    this._name2Event.set(eventName, event)
-    return event
-  }
-
-  /**
-   * Checks if the specified owner has any registered events.
-   * @param {Object} owner - The owner object to check for registered events.
-   * @returns {boolean} True if the owner has any registered events, false otherwise.
-   */
-  hasOwner (owner) {
-    if (isNil(owner)) {
-      return false
-    }
-    for (const event of this._name2Event.values()) {
-      if (event.hasOwner(owner)) {
-        return true
-      }
-    }
-    return false
-  }
-}
-
-export { EventEmitter as EventEmitterType }