ts-typed-events/dist/index.d.ts

Zero dependency strongly typed event emitters for TypeScript

/**
 * This is a very simple strongly typed event emitter class, see README.md
 * for more details.
 */
/** Checks if a type extends undefined, without a discriminator. */
declare type HasUndefined<T, C = [T extends undefined ? true : false]> = C extends [
    true
] ? true : C extends [false] ? false : true;
/** An emitter function for a ts-typed-events Event. */
declare type BaseEmitterFunc<T = undefined> = HasUndefined<T> extends true ? Exclude<T, undefined> extends never ? () => boolean : (emitting?: T) => boolean : (emitting: T) => boolean;
/**
 * A ts-typed-events event to register callbacks on to be invoked when they are
 * emitted.
 */
export declare abstract class BaseEvent<T = undefined> {
    /** All the current listeners for this event. */
    private listeners;
    /**
     * Marked as protected to discourage creation outside of
     * createEventEmitter().
     */
    protected constructor();
    /**
     * Attaches a callback to trigger on all emits for this event.
     *
     * @param callback - The callback to invoke on all emits.
     */
    on(callback: (data: T) => void): void;
    /**
     * Attaches a callback to trigger on only the first emit for this event.
     * After that event is emitted this callback will automatically be
     * removed.
     *
     * @param callback - The callback to invoke only the next time this event
     * emits, then that callback is removed from this event.
     */
    once(callback: (emitted: T) => void): void;
    /**
     * Attaches a callback to trigger on only the first emit for this event.
     *
     * Returns a promise that resolves with the emitted data the next time this
     * event is triggered (only once).
     *
     * @returns A promise that resolves with the emitted data the next time this
     * event is triggered (only once).
     */
    once(): Promise<T>;
    /**
     * Removes a callback from this event (regardless of once vs on).
     *
     * Returns true if a callback was removed, false otherwise.
     *
     * @param listener - The callback to remove.
     * @returns True if a callback was removed, false otherwise.
     */
    off(listener: ((emitted: T) => void) | Promise<T>): boolean;
    /**
     * Removes ALL callbacks from this event, regardless of once vs on.
     *
     * Returns the number of listeners removed.
     *
     * @returns The number of listeners removed.
     */
    offAll(): number;
}
/**
 * A ts-typed-events event to register callbacks on to be invoked when they are
 * emitted.
 *
 * This Event class signifies the event is "sealed" from the outside and cannot
 * be emitted through itself. The emitter function is separated.
 */
export declare class SealedEvent<T = undefined> extends BaseEvent<T> {
}
/** An emitter function with itself and its event as properties keyed on it. */
export declare type Emitter<T, TEvent extends BaseEvent<T>> = BaseEmitterFunc<T> & {
    /** The Event this emitter emits to. */
    readonly event: TEvent;
    /** A cyclical reference to the same emitter function. */
    readonly emit: Emitter<T, TEvent>;
};
/**
 * Creates and returns an emitter for a SealedEvent, with the event keyed off
 * the emitter via `.event`.
 *
 * @returns An emitter function that will emit to the `.event` SealedEvent.
 */
export declare function createEmitter<T = undefined>(): Emitter<T, SealedEvent<T>>;
/**
 * A specialized Event that holds a reference to its own emit function.
 * This allows any code with access to the Event to also trigger emits.
 */
export declare class Event<T = undefined> extends BaseEvent<T> {
    /**
     * Emits a value to all the listeners, triggering their callbacks.
     * Returns true if the event had listeners emitted to,
     * false otherwise.
     * Because this exists on the event, any code with access to this event
     * can trigger the callback for all listeners.
     *
     * @param emitting - If the Event has a type, this is the data of that type
     * to emit to all listeners. If no type (undefined) this argument should
     * be omitted.
     * @returns True if the event had listeners emitted to, false otherwise.
     */
    emit: Emitter<T, Event<T>>;
    /**
     * Creates a new Event, with its emit accessible as a member function.
     */
    constructor();
}
/**
 * Creates and returns an emitter for an Event, with the event keyed off
 * the emitter via `.event`.
 * **Note**: The `event` here is will have a member function `.emit` that emits
 * to the same function as the emitter returned here.
 *
 * @returns An emitter function that will emit to the `.event` Event.
 */
export declare function createEventEmitter<T = undefined>(): Emitter<T, Event<T>>;
export {};