[e29cc2e] | 1 | /// <reference types="node" />
|
---|
| 2 | import { EventEmitter } from "events";
|
---|
| 3 | /**
|
---|
| 4 | * An events map is an interface that maps event names to their value, which
|
---|
| 5 | * represents the type of the `on` listener.
|
---|
| 6 | */
|
---|
| 7 | export interface EventsMap {
|
---|
| 8 | [event: string]: any;
|
---|
| 9 | }
|
---|
| 10 | /**
|
---|
| 11 | * The default events map, used if no EventsMap is given. Using this EventsMap
|
---|
| 12 | * is equivalent to accepting all event names, and any data.
|
---|
| 13 | */
|
---|
| 14 | export interface DefaultEventsMap {
|
---|
| 15 | [event: string]: (...args: any[]) => void;
|
---|
| 16 | }
|
---|
| 17 | /**
|
---|
| 18 | * Returns a union type containing all the keys of an event map.
|
---|
| 19 | */
|
---|
| 20 | export declare type EventNames<Map extends EventsMap> = keyof Map & (string | symbol);
|
---|
| 21 | /** The tuple type representing the parameters of an event listener */
|
---|
| 22 | export declare type EventParams<Map extends EventsMap, Ev extends EventNames<Map>> = Parameters<Map[Ev]>;
|
---|
| 23 | /**
|
---|
| 24 | * The event names that are either in ReservedEvents or in UserEvents
|
---|
| 25 | */
|
---|
| 26 | export declare type ReservedOrUserEventNames<ReservedEventsMap extends EventsMap, UserEvents extends EventsMap> = EventNames<ReservedEventsMap> | EventNames<UserEvents>;
|
---|
| 27 | /**
|
---|
| 28 | * Type of a listener of a user event or a reserved event. If `Ev` is in
|
---|
| 29 | * `ReservedEvents`, the reserved event listener is returned.
|
---|
| 30 | */
|
---|
| 31 | export declare type ReservedOrUserListener<ReservedEvents extends EventsMap, UserEvents extends EventsMap, Ev extends ReservedOrUserEventNames<ReservedEvents, UserEvents>> = FallbackToUntypedListener<Ev extends EventNames<ReservedEvents> ? ReservedEvents[Ev] : Ev extends EventNames<UserEvents> ? UserEvents[Ev] : never>;
|
---|
| 32 | /**
|
---|
| 33 | * Returns an untyped listener type if `T` is `never`; otherwise, returns `T`.
|
---|
| 34 | *
|
---|
| 35 | * This is a hack to mitigate https://github.com/socketio/socket.io/issues/3833.
|
---|
| 36 | * Needed because of https://github.com/microsoft/TypeScript/issues/41778
|
---|
| 37 | */
|
---|
| 38 | declare type FallbackToUntypedListener<T> = [T] extends [never] ? (...args: any[]) => void | Promise<void> : T;
|
---|
| 39 | /**
|
---|
| 40 | * Interface for classes that aren't `EventEmitter`s, but still expose a
|
---|
| 41 | * strictly typed `emit` method.
|
---|
| 42 | */
|
---|
| 43 | export interface TypedEventBroadcaster<EmitEvents extends EventsMap> {
|
---|
| 44 | emit<Ev extends EventNames<EmitEvents>>(ev: Ev, ...args: EventParams<EmitEvents, Ev>): boolean;
|
---|
| 45 | }
|
---|
| 46 | /**
|
---|
| 47 | * Strictly typed version of an `EventEmitter`. A `TypedEventEmitter` takes type
|
---|
| 48 | * parameters for mappings of event names to event data types, and strictly
|
---|
| 49 | * types method calls to the `EventEmitter` according to these event maps.
|
---|
| 50 | *
|
---|
| 51 | * @typeParam ListenEvents - `EventsMap` of user-defined events that can be
|
---|
| 52 | * listened to with `on` or `once`
|
---|
| 53 | * @typeParam EmitEvents - `EventsMap` of user-defined events that can be
|
---|
| 54 | * emitted with `emit`
|
---|
| 55 | * @typeParam ReservedEvents - `EventsMap` of reserved events, that can be
|
---|
| 56 | * emitted by socket.io with `emitReserved`, and can be listened to with
|
---|
| 57 | * `listen`.
|
---|
| 58 | */
|
---|
| 59 | export declare abstract class StrictEventEmitter<ListenEvents extends EventsMap, EmitEvents extends EventsMap, ReservedEvents extends EventsMap = {}> extends EventEmitter implements TypedEventBroadcaster<EmitEvents> {
|
---|
| 60 | /**
|
---|
| 61 | * Adds the `listener` function as an event listener for `ev`.
|
---|
| 62 | *
|
---|
| 63 | * @param ev Name of the event
|
---|
| 64 | * @param listener Callback function
|
---|
| 65 | */
|
---|
| 66 | on<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(ev: Ev, listener: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
|
---|
| 67 | /**
|
---|
| 68 | * Adds a one-time `listener` function as an event listener for `ev`.
|
---|
| 69 | *
|
---|
| 70 | * @param ev Name of the event
|
---|
| 71 | * @param listener Callback function
|
---|
| 72 | */
|
---|
| 73 | once<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(ev: Ev, listener: ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>): this;
|
---|
| 74 | /**
|
---|
| 75 | * Emits an event.
|
---|
| 76 | *
|
---|
| 77 | * @param ev Name of the event
|
---|
| 78 | * @param args Values to send to listeners of this event
|
---|
| 79 | */
|
---|
| 80 | emit<Ev extends EventNames<EmitEvents>>(ev: Ev, ...args: EventParams<EmitEvents, Ev>): boolean;
|
---|
| 81 | /**
|
---|
| 82 | * Emits a reserved event.
|
---|
| 83 | *
|
---|
| 84 | * This method is `protected`, so that only a class extending
|
---|
| 85 | * `StrictEventEmitter` can emit its own reserved events.
|
---|
| 86 | *
|
---|
| 87 | * @param ev Reserved event name
|
---|
| 88 | * @param args Arguments to emit along with the event
|
---|
| 89 | */
|
---|
| 90 | protected emitReserved<Ev extends EventNames<ReservedEvents>>(ev: Ev, ...args: EventParams<ReservedEvents, Ev>): boolean;
|
---|
| 91 | /**
|
---|
| 92 | * Emits an event.
|
---|
| 93 | *
|
---|
| 94 | * This method is `protected`, so that only a class extending
|
---|
| 95 | * `StrictEventEmitter` can get around the strict typing. This is useful for
|
---|
| 96 | * calling `emit.apply`, which can be called as `emitUntyped.apply`.
|
---|
| 97 | *
|
---|
| 98 | * @param ev Event name
|
---|
| 99 | * @param args Arguments to emit along with the event
|
---|
| 100 | */
|
---|
| 101 | protected emitUntyped(ev: string, ...args: any[]): boolean;
|
---|
| 102 | /**
|
---|
| 103 | * Returns the listeners listening to an event.
|
---|
| 104 | *
|
---|
| 105 | * @param event Event name
|
---|
| 106 | * @returns Array of listeners subscribed to `event`
|
---|
| 107 | */
|
---|
| 108 | listeners<Ev extends ReservedOrUserEventNames<ReservedEvents, ListenEvents>>(event: Ev): ReservedOrUserListener<ReservedEvents, ListenEvents, Ev>[];
|
---|
| 109 | }
|
---|
| 110 | export {};
|
---|