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