@creejs/commons-events
Version:
Commons EventEmitter
198 lines (196 loc) • 8.97 kB
TypeScript
/**
* 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<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;
/**
* Emits an event To the specified owner.
* @param {string} eventName - The name of the event to emit.
* @param {any} owner - The owner of listeners
* @param {...*} args - Additional arguments to pass with the event.
*/
emitOwner(eventName: string, owner: any, ...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;
}
export { EventEmitter as EventEmitterType };
export type EventEmitterLike = {
on(eventName: string, listener: Function, owner?: any): EventEmitterLike;
addListener(eventName: string, listener: Function, owner?: any): EventEmitterLike;
off(eventName: string, listener: Function): EventEmitterLike;
removeListener(eventName: string, listener: Function): EventEmitterLike;
offAll(eventName: string, owner: any): EventEmitterLike;
offOwner(owner: any): EventEmitterLike;
removeAllListeners(eventName: string): EventEmitterLike;
once(eventName: string, listener: Function, owner?: any): EventEmitterLike;
emit(eventName: string, ...args: any[]): EventEmitterLike;
emitOwner(eventName: string, owner: any, ...args: any[]): EventEmitterLike;
};
import Event from './event.js';
import Listener from './listener.js';