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 {};
|