UNPKG

5.07 kBTypeScriptView Raw
1/// <reference types="node" />
2import { 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 */
7export 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 */
14export interface DefaultEventsMap {
15 [event: string]: (...args: any[]) => void;
16}
17/**
18 * Returns a union type containing all the keys of an event map.
19 */
20export declare type EventNames<Map extends EventsMap> = keyof Map & (string | symbol);
21/** The tuple type representing the parameters of an event listener */
22export 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 */
26export 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 */
31export 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 */
38declare 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 */
43export 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 */
59export 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}
110export {};