@creejs/commons-events 2.0.2 → 2.0.3

package/lib/event.js

@@ -1,362 +0,0 @@
-// 3rd
-// internal
-import { TypeUtils, TypeAssert } from '@creejs/commons-lang'
-
-// owned
-// eslint-disable-next-line no-unused-vars
-import Listener from './listener.js'
-import { DefaultOwner } from './constants.js'
-
-// module vars
-const { isFunction, isNil } = TypeUtils
-const { assertStringOrSymbol, assertFunction } = TypeAssert
-
-/**
- * An Event definition
- * 1. listeners are grouped by owner
- *    * if not specified, group it into one Default owner
- * 2. one listener may belong to multiple owners
- * 3. one owner may have multiple listeners
- */
-export default class Event {
-  static get DefaultOwner () {
-    return DefaultOwner
-  }
-
-  /**
-   * Creates a new Event instance with the specified name.
-   * @param {string|Symbol} eventName - The name of the event.
-   */
-  constructor (eventName) {
-    assertStringOrSymbol(eventName, 'eventName')
-    this._name = eventName
-    /**
-     * use Set to store unique listeners
-     * @type {Set<function>}
-     */
-    this._callbacks = new Set()
-    /**
-     * @type {Array<Listener>}
-     */
-    this._listeners = [] // user array to keep order
-    /**
-     * @type {Map<function, Set<Listener>>}
-     */
-    this._callback2Listeners = new Map()
-    /**
-     * use listener to index owners. One Listener Instance only belongs to one owner
-     * @type {Map<Listener, *>}
-    */
-    this._listener2Owner = new Map()
-    /**
-     * use "owner" to group listeners; one owner may have multiple listeners
-     * @type {Map<*, Set<Listener>>}
-     */
-    this._owner2Listeners = new Map()
-  }
-
-  /**
-   * Name of the event.
-   * @returns {string|Symbol}
-   */
-  get name () {
-    return this._name
-  }
-
-  isEmpty () {
-    return this._callbacks.size === 0
-  }
-
-  /**
-   * Returns a copy of the raw listeners array.
-   * @returns {Array<Listener>} A shallow copy of the listeners array.
-   */
-  rawListeners () {
-    return [...this._listeners]
-  }
-
-  /**
-   * Returns the number of listeners listening for the event.
-   * If callback is provided, it will return how many times the callback is found in the list of the listeners
-   * @param {Function} [callback] - The callback function to count
-   * @returns {number}
-   */
-  listenerCount (callback) {
-    if (callback == null) {
-      return this._listeners.length
-    }
-    return this._callback2Listeners.get(callback)?.size ?? 0
-  }
-
-  /**
-   * Returns a shallow copy of the registered callbacks array.
-   * if one callback function is added multiple times, it will be returned multiple times.
-   * @returns {Array<function>} A new array containing all registered callbacks.
-   */
-  callbacks () {
-    return [...this.rawListeners().map(listener => listener.callback)]
-  }
-
-  /**
-   * Emits current event, invoking all registered listeners by order.
-   * @param {...*} args - Arguments to be passed to each listener.
-   * @returns {boolean} True if the event had listeners, false otherwise.
-   */
-  emit (...args) {
-    if (this._listeners.length === 0) {
-      return false
-    }
-    // Clone _listeners, it may be changed during call listener
-    for (const listener of [...this._listeners]) {
-      listener.invoke(...args)
-    }
-    return true
-  }
-
-  /**
-   * Checks if listener is registered with this event.
-   * @param {function} callback - The listener function to check.
-   * @returns {boolean} True if the listener is registered, false otherwise.
-   */
-  hasListener (callback) {
-    if (!isFunction(callback)) {
-      return false
-    }
-    return this._callbacks.has(callback)
-  }
-
-  /**
-   * Checks if owner has any registered listeners.
-   * @param {*} owner - The owner to check for registered listeners.
-   * @returns {boolean} True if the owner has listeners, false otherwise.
-   */
-  hasOwner (owner) {
-    if (isNil(owner)) {
-      return false
-    }
-    return this._owner2Listeners.has(owner)
-  }
-
-  /**
-   * Adds an event listener
-   * @param {function} callback - The callback function to be invoked when the event occurs.
-   * @param {*} [owner] - use "owner" to group listeners, then can remove all listeners for an owner.
-   * @returns {boolean} true if added, false otherwise.
-   */
-  addListener (callback, owner) {
-    return this._addListener(callback, owner, false, false)
-  }
-
-  /**
-   * Prepends a listener callback to the beginning of the listeners array.
-   * No checks are made to see if the listener has already been added.
-   * Multiple calls passing the same combination of eventName and listener will result in the listener being added,
-   * and called, multiple times.
-   * @param {Function} callback - The callback function to be executed when the event is emitted.
-   * @param {Object} owner - The owner object to which the listener belongs.
-   * @returns {boolean}
-   */
-  prependListener (callback, owner) {
-    return this._addListener(callback, owner, false, true)
-  }
-
-  /**
-   * Adds a one-time listener for the event. The listener is automatically removed after being invoked once.
-   * @param {Function} callback - The function to call when the event is triggered.
-   * @param {Object} [owner] - The object that owns the callback (used for binding `this` context).
-   * @returns {boolean}
-   */
-  addOnceListener (callback, owner) {
-    return this._addListener(callback, owner, true, false)
-  }
-
-  /**
-   * Adds a one-time event listener that will be automatically removed after being triggered once.
-   * The listener will only be triggered if the event is pretended (simulated).
-   * @param {Function} callback - The function to call when the event is triggered.
-   * @param {Object} owner - The object that owns the listener (used for reference tracking).
-   * @returns {boolean} The listener function that was added.
-   */
-  prependOnceListener (callback, owner) {
-    return this._addListener(callback, owner, true, true)
-  }
-
-  /**
-   * Adds a listener for the event.
-   * @param {Function} callback - The callback function to be executed when the event occurs
-   * @param {*} [owner] - The owner object that the listener belongs to (defaults to DeaultOwner)
-   * @param {boolean} [isOnce=false] - Whether the listener should be removed after first invocation
-   * @param {boolean} [isPrepend=false] - Whether the listener should be inert at the beginning of the listeners array
-   * @returns {boolean} Returns true if listener was added successfully, false if callback is nil or duplicate
-   * @protected
-   */
-  _addListener (callback, owner, isOnce, isPrepend) {
-    if (isNil(callback)) {
-      return false
-    }
-    assertFunction(callback)
-    if (!this._callbacks.has(callback)) {
-      this._callbacks.add(callback)
-    }
-    // a listener must belong to an owner
-    owner = owner ?? DefaultOwner
-
-    // use Listener to wrap callback
-    const listener = new Listener(this, callback, isOnce)
-    listener.owner = owner
-    if (isPrepend) {
-      this._listeners.unshift(listener)
-    } else {
-      this._listeners.push(listener)
-    }
-
-    // index, rapadly find one listener's owner
-    this._listener2Owner.set(listener, owner)
-
-    // one callback function may be registered many times
-    let callbackListeners = this._callback2Listeners.get(callback)
-    if (callbackListeners == null) {
-      callbackListeners = new Set()
-      this._callback2Listeners.set(callback, callbackListeners)
-    }
-    callbackListeners.add(listener)
-
-    // group by owner
-    let ownerListeners = this._owner2Listeners.get(owner)
-    if (ownerListeners == null) {
-      ownerListeners = new Set()
-      this._owner2Listeners.set(owner, ownerListeners)
-    }
-    ownerListeners.add(listener)
-
-    return true
-  }
-
-  /**
-   * Removes a callback
-   * @param {Function} callback - The callback function to remove.
-   * @returns {boolean} true if removed, false otherwise.
-   */
-  removeListener (callback) {
-    if (isNil(callback)) {
-      return false
-    }
-    if (!this._callbacks.has(callback)) {
-      return false
-    }
-    this._callbacks.delete(callback)
-
-    const listeners = this._callback2Listeners.get(callback)
-    if (listeners == null) { // should not happen
-      return false
-    }
-    this._callback2Listeners.delete(callback)
-    for (const listener of listeners) {
-      // remove from global index
-      const index = this._listeners.indexOf(listener)
-      index !== -1 && this._listeners.splice(this._listeners.indexOf(listener), 1)
-
-      // remove from owner index
-      const owner = this._listener2Owner.get(listener)
-      if (owner == null) {
-        continue
-      }
-      this._listener2Owner.delete(listener)
-      const ownerListeners = this._owner2Listeners.get(owner)
-      if (ownerListeners == null) {
-        continue
-      }
-      ownerListeners.delete(listener)
-      if (ownerListeners.size === 0) {
-        this._owner2Listeners.delete(owner)
-      }
-    }
-    return true
-  }
-
-  /**
-   * Removes a listener from both global and owner indexes.
-   * @param {Listener} listener - The listener function to remove
-   */
-  _remove (listener) {
-    // remove from global index
-    const index = this._listeners.indexOf(listener)
-    index !== -1 && this._listeners.splice(index, 1)
-
-    // clean callback index
-    const { callback } = listener
-    const callbackListeners = this._callback2Listeners.get(callback)
-    if (callbackListeners != null) {
-      callbackListeners.delete(listener)
-      if (callbackListeners.size === 0) {
-        this._callback2Listeners.delete(callback)
-        this._callbacks.delete(callback)
-      }
-    }
-
-    // remove from owner index
-    const owner = this._listener2Owner.get(listener)
-    if (owner == null) {
-      return
-    }
-    this._listener2Owner.delete(listener)
-    const ownerListeners = this._owner2Listeners.get(owner)
-    if (ownerListeners == null) {
-      return
-    }
-    ownerListeners.delete(listener)
-    if (ownerListeners.size === 0) {
-      this._owner2Listeners.delete(owner)
-    }
-  }
-
-  /**
-   * Removes all event listeners
-   * @param {*} [owner] - Without owner, all listeners will be removed; otherwise, only listeners of "owner" will be removed.
-   * @returns {this}
-   */
-  removeAllListeners (owner) {
-    // remove listeners of owner
-    if (isNil(owner)) {
-      // remove all Listeners
-      this._callbacks.clear()
-      this._listeners.length = 0
-      this._callback2Listeners.clear()
-      this._listener2Owner.clear()
-      this._owner2Listeners.clear()
-      return this
-    }
-    // all listeners of the owner
-    const ownerListeners = this._owner2Listeners.get(owner)
-    // no owner
-    if (ownerListeners == null) {
-      return this
-    }
-    // clear owner index
-    this._owner2Listeners.delete(owner)
-    // clearn listeners of owner one by one
-    for (const listener of ownerListeners) {
-      // remove from global index
-      const index = this._listeners.indexOf(listener)
-      index !== -1 && this._listeners.splice(this._listeners.indexOf(listener), 1)
-
-      // clean listener-owner index
-      this._listener2Owner.delete(listener)
-
-      // one callback function may be registered many times, has many Listeners
-      const { callback } = listener
-      const callbackListeners = this._callback2Listeners.get(callback)
-      if (callbackListeners == null) {
-        continue
-      }
-      callbackListeners.delete(listener)
-      if (callbackListeners.size === 0) {
-        this._callback2Listeners.delete(callback)
-        this._callbacks.delete(callback)
-      }
-    }
-    return this
-  }
-}
-
-export { Event as EventType }

package/lib/index.js

@@ -1,5 +0,0 @@
-import EventEmitter from './event-emitter.js'
-
-export default EventEmitter
-
-export { EventEmitter }

package/lib/listener.js

@@ -1,93 +0,0 @@
-// 3rd
-// internal
-import { TypeAssert } from '@creejs/commons-lang'
-
-// owned
-import { DefaultOwner } from './constants.js'
-
-// module vars
-const { assertFunction, assertNotNil } = TypeAssert
-/**
- * Wraps a function to be called when an event is fired.
- * @typedef {import('./event.js').default} Event
- * @class Listener
- */
-export default class Listener {
-  /**
-   * @param {Event} event
-   * @param {function} callback - The function to be called when event is fired
-   * @param {boolean} [isOnce=false] - is a one time listener?
-   */
-  constructor (event, callback, isOnce = false) {
-    assertNotNil(event, 'event')
-    assertFunction(callback, 'callback')
-    this._event = event
-    this._callback = callback
-    this._isOnce = !!isOnce // is Once Listener?
-    this._owner = undefined
-  }
-
-  /**
-   * Sets the owner of this listener.
-   * @param {*} owner - The owner object to be associated with this listener.
-   */
-  set owner (owner) {
-    this._owner = owner
-  }
-
-  get owner () {
-    return this._owner === DefaultOwner ? undefined : this._owner
-  }
-
-  get event () {
-    return this._event
-  }
-
-  get isOnce () {
-    return this._isOnce
-  }
-
-  /**
-   * Checks if the provided function is the same as the listener's wrapped function.
-   * @param {Function} callback - The function to compare against.
-   * @returns {boolean} True if the functions are the same, false otherwise.
-   */
-  isSameCallback (callback) {
-    return this._callback === callback
-  }
-
-  get callback () {
-    return this._callback
-  }
-
-  /**
-   * Invokes the stored function with the provided arguments.
-   * @param {...*} args - Arguments to pass to the function.
-   * @returns {*} The result of the function invocation.
-   */
-  invoke (...args) {
-    try {
-      return this._callback(...args)
-    } finally {
-      if (this._isOnce) {
-        try {
-          this._event._remove(this)
-        } catch (err) {
-          // do nothing
-          console.warn(err)
-        }
-      }
-    }
-  }
-
-  /**
-   * Invokes the listener with the provided arguments.
-   * Alias for {@linkcode Listener.invoke}
-   * @param {...*} args - Arguments to be passed to the listener.
-   * @returns {*} The result of the listener invocation.
-   */
-  listener (...args) {
-    return this.invoke(...args)
-  }
-}
-export { Listener as ListenerType }