@creejs/commons-events 1.0.3 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@creejs/commons-events",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Commons EventEmitter",
   "main": "index.js",
   "private": false,

package/types/constants.d.ts

@@ -0,0 +1 @@
+export const DefaultOwner: "DOwner$#$";

package/types/event-emitter.d.ts

@@ -0,0 +1,178 @@
+export = EventEmitter;
+/**
+ * 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.
+ */
+declare 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<T>(obj: T): T;
+    static set defaultMaxListeners(maxListeners: number);
+    static get defaultMaxListeners(): number;
+    /**
+     * @type {Map<string|Symbol, Event>}
+     */
+    _name2Event: Map<string | Symbol, Event>;
+    _maxListeners: number;
+    /**
+     * Alias of {@linkcode EventEmitter.addListener}
+     * @param {string|Symbol} eventName
+     * @param {function} listener
+     * @param {*} [owner]
+     * @returns {this}
+     */
+    addListener(eventName: string | Symbol, listener: Function, owner?: any): this;
+    /**
+     * 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: string | Symbol, listener: Function, owner?: any): 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: string | Symbol, listener: Function, owner?: any): 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: string | Symbol, ...args: any[]): boolean;
+    /**
+     * Returns an array listing the events for which the emitter has registered listeners.
+     * @returns {Array<string|Symbol>} An array of event names.
+     */
+    eventNames(): Array<string | Symbol>;
+    getMaxListeners(): number;
+    /**
+     * 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: string | Symbol, listener?: Function): number;
+    /**
+     * 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: string): Array<Function>;
+    /**
+     * 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: string, callback: Function): EventEmitter;
+    /**
+     * 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: string | Symbol, owner: any): EventEmitter;
+    /**
+     * Removes all event listeners belonging to the specified owner.
+     * @param {*} owner - The owner whose listeners should be removed.
+     * @returns {this}
+     */
+    offOwner(owner: any): 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: string | Symbol, callback: Function, owner?: any): 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}
+     */
+    private _checkMaxListeners;
+    /**
+     * 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: string, callback: Function, owner?: any): EventEmitter;
+    /**
+     * 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: string): Listener[];
+    /**
+     * 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: string | Symbol, owner: any): EventEmitter;
+    /**
+     * 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: string, callback: Function): EventEmitter;
+    /**
+     * 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: number): 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.
+     */
+    private _getOrCreateEvent;
+    /**
+     * 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: Object): boolean;
+}
+import Event = require("./event");
+import Listener = require("./listener");

package/types/event.d.ts

@@ -0,0 +1,142 @@
+export = Event;
+/**
+ * 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
+ */
+declare class Event {
+    static get DefaultOwner(): string;
+    /**
+     * Creates a new Event instance with the specified name.
+     * @param {string|Symbol} eventName - The name of the event.
+     */
+    constructor(eventName: string | Symbol);
+    _name: string | Symbol;
+    /**
+     * use Set to store unique listeners
+     * @type {Set<function>}
+     */
+    _callbacks: Set<Function>;
+    /**
+     * @type {Array<Listener>}
+     */
+    _listeners: Array<Listener>;
+    /**
+     * @type {Map<function, Set<Listener>>}
+     */
+    _callback2Listeners: Map<Function, Set<Listener>>;
+    /**
+     * use listener to index owners. One Listener Instance only belongs to one owner
+     * @type {Map<Listener, *>}
+    */
+    _listener2Owner: Map<Listener, any>;
+    /**
+     * use "owner" to group listeners; one owner may have multiple listeners
+     * @type {Map<*, Set<Listener>>}
+     */
+    _owner2Listeners: Map<any, Set<Listener>>;
+    /**
+     * Name of the event.
+     * @returns {string|Symbol}
+     */
+    get name(): string | Symbol;
+    isEmpty(): boolean;
+    /**
+     * Returns a copy of the raw listeners array.
+     * @returns {Array<Listener>} A shallow copy of the listeners array.
+     */
+    rawListeners(): Array<Listener>;
+    /**
+     * 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?: Function): number;
+    /**
+     * 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(): Array<Function>;
+    /**
+     * 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: any[]): boolean;
+    /**
+     * 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: Function): boolean;
+    /**
+     * 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: any): boolean;
+    /**
+     * 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: Function, owner?: any): boolean;
+    /**
+     * 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: Function, owner: Object): boolean;
+    /**
+     * 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: Function, owner?: Object): boolean;
+    /**
+     * 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: Function, owner: Object): boolean;
+    /**
+     * 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
+     */
+    protected _addListener(callback: Function, owner?: any, isOnce?: boolean, isPrepend?: boolean): boolean;
+    /**
+     * Removes a callback
+     * @param {Function} callback - The callback function to remove.
+     * @returns {boolean} true if removed, false otherwise.
+     */
+    removeListener(callback: Function): boolean;
+    /**
+     * Removes a listener from both global and owner indexes.
+     * @param {Listener} listener - The listener function to remove
+     */
+    _remove(listener: Listener): void;
+    /**
+     * 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?: any): this;
+}
+import Listener = require("./listener");

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export { EventEmitter };
+import EventEmitter = require("./event-emitter");

package/types/listener.d.ts

@@ -0,0 +1,46 @@
+export = Listener;
+/**
+ * Wraps a function to be called when an event is fired.
+ * @class Listener
+ */
+declare 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: Event, callback: Function, isOnce?: boolean);
+    _event: Event;
+    _callback: Function;
+    _isOnce: boolean;
+    _owner: any;
+    /**
+     * Sets the owner of this listener.
+     * @param {*} owner - The owner object to be associated with this listener.
+     */
+    set owner(owner: any);
+    get owner(): any;
+    get event(): Event;
+    get isOnce(): boolean;
+    /**
+     * 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: Function): boolean;
+    get callback(): Function;
+    /**
+     * 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: any[]): any;
+    /**
+     * 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: any[]): any;
+}
+import Event = require("./event");