@billjs/event-emitter/lib/index.d.ts

A simple and lightweight EventEmitter by TypeScript for Node.js or Browsers.

/**
 * A simple and lightweight EventEmitter by TypeScript for Node.js or Browsers.
 *
 * @author billjs
 * @see https://github.com/billjs/event-emitter
 * @license MIT(https://opensource.org/licenses/MIT)
 */
/**
 * EventHandler
 *
 * @export
 */
export declare type EventHandler = ((evt: Event) => void) & {
    _once?: boolean;
};
/**
 * Event Object
 *
 * @export
 * @interface Event
 */
export interface Event {
    /**
     * event type
     *
     * @type {string}
     * @memberof Event
     */
    type: string;
    /**
     * event data
     *
     * @type {*}
     * @memberof Event
     */
    data: any;
    /**
     * the timestamp when event fired
     *
     * @type {number}
     * @memberof Event
     */
    timestamp: number;
    /**
     * it is an once event, that meaning listen off after event fired
     *
     * @type {boolean}
     * @memberof Event
     */
    once: boolean;
}
/**
 * It's a class for managing events.
 * It can be extended to provide event functionality for other classes or object.
 *
 * @export
 * @class EventEmitter
 */
export declare class EventEmitter {
    /**
     * the all event handlers are added.
     * it's a Map data structure(key-value), the key is event type, and the value is event handler.
     *
     * @memberof EventEmitter
     */
    _eventHandlers: Record<string, EventHandler[] | undefined>;
    /**
     * event type validator.
     *
     * @param {string} type event type
     * @returns {boolean}
     * @memberof EventEmitter
     */
    isValidType(type: string): boolean;
    /**
     * event handler validator.
     *
     * @param {EventHandler} handler event handler
     * @returns {boolean}
     * @memberof EventEmitter
     */
    isValidHandler(handler: EventHandler): boolean;
    /**
     * listen on a new event by type and handler.
     * if listen on, the true is returned, otherwise the false.
     * The handler will not be listen if it is a duplicate.
     *
     * @param {string} type event type, it must be a unique string.
     * @param {EventHandler} handler event handler, when if the same handler is passed, listen it by only once.
     * @returns {boolean}
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  emitter.on('change:name', evt => {
     *    console.log(evt);
     *  });
     */
    on(type: string, handler: EventHandler): boolean;
    /**
     * listen on an once event by type and handler.
     * when the event is fired, that will be listen off immediately and automatically.
     * The handler will not be listen if it is a duplicate.
     *
     * @param {string} type event type, it must be a unique string.
     * @param {EventHandler} handler event handler, when if the same handler is passed, listen it by only once.
     * @returns {boolean}
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  emitter.once('change:name', evt => {
     *    console.log(evt);
     *  });
     */
    once(type: string, handler: EventHandler): boolean;
    /**
     * listen off an event by type and handler.
     * or listen off events by type, when if only type argument is passed.
     * or listen off all events, when if no arguments are passed.
     *
     * @param {string} [type] event type
     * @param {EventHandler} [handler] event handler
     * @returns
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  // listen off the specified event
     *  emitter.off('change:name', evt => {
     *    console.log(evt);
     *  });
     *  // listen off events by type
     *  emitter.off('change:name');
     *  // listen off all events
     *  emitter.off();
     */
    off(type?: string, handler?: EventHandler): void;
    /**
     * listen off all events, that means every event will be emptied.
     *
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  emitter.offAll();
     */
    offAll(): void;
    /**
     * fire the specified event, and you can to pass a data.
     * When fired, every handler attached to that event will be executed.
     * But, if it's an once event, listen off it immediately after called handler.
     *
     * @param {string} type event type
     * @param {*} [data] event data
     * @returns
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  emitter.fire('change:name', 'new name');
     */
    fire(type: string, data?: any): void;
    /**
     * check whether the specified event has been listen on.
     * or check whether the events by type has been listen on, when if only `type` argument is passed.
     *
     * @param {string} type event type
     * @param {EventHandler} [handler] event handler, optional
     * @returns {boolean}
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  const result = emitter.has('change:name');
     */
    has(type: string, handler?: EventHandler): boolean;
    /**
     * get the handlers for the specified event type.
     *
     * @param {string} type event type
     * @returns {EventHandler[]}
     * @memberof EventEmitter
     * @example
     *  const emitter = new EventEmitter();
     *  const handlers = emitter.getHandlers('change:name');
     *  console.log(handlers);
     */
    getHandlers(type: string): EventHandler[];
    /**
     * create event object.
     *
     * @param {string} type event type
     * @param {*} [data] event data
     * @param {boolean} [once=false] is it an once event?
     * @returns {Event}
     * @memberof EventEmitter
     */
    createEvent(type: string, data?: any, once?: boolean): Event;
}
/**
 * EventEmitter instance for global.
 * @type {EventEmitter}
 */
export declare const globalEvent: EventEmitter;