From 9baba151c67ee2bcdd1b05763d4ad04f7eae3a7e Mon Sep 17 00:00:00 2001 From: Valere Fedronic Date: Thu, 3 Jul 2025 14:26:10 +0200 Subject: [PATCH] Move `ClientEvent` docs to the event itself instead of the type map (#4894) * doc: Add ClientEvent doc on the event enum * Cleanup: Remove useless doc on EventHandlerMap * quick format --- src/client.ts | 251 +++++++++++++++++++++++++------------------------- 1 file changed, 127 insertions(+), 124 deletions(-) diff --git a/src/client.ts b/src/client.ts index bee940028..3c08b12e1 100644 --- a/src/client.ts +++ b/src/client.ts @@ -888,78 +888,6 @@ interface IWhoamiResponse { const EVENT_ID_PREFIX = "$"; export enum ClientEvent { - Sync = "sync", - Event = "event", - /** @deprecated Use {@link ReceivedToDeviceMessage}. */ - ToDeviceEvent = "toDeviceEvent", - ReceivedToDeviceMessage = "receivedToDeviceMessage", - AccountData = "accountData", - Room = "Room", - DeleteRoom = "deleteRoom", - SyncUnexpectedError = "sync.unexpectedError", - ClientWellKnown = "WellKnown.client", - ReceivedVoipEvent = "received_voip_event", - UndecryptableToDeviceEvent = "toDeviceEvent.undecryptable", - TurnServers = "turnServers", - TurnServersError = "turnServers.error", -} - -type RoomEvents = - | RoomEvent.Name - | RoomEvent.Redaction - | RoomEvent.RedactionCancelled - | RoomEvent.Receipt - | RoomEvent.Tags - | RoomEvent.LocalEchoUpdated - | RoomEvent.HistoryImportedWithinTimeline - | RoomEvent.AccountData - | RoomEvent.MyMembership - | RoomEvent.Timeline - | RoomEvent.TimelineReset; - -type RoomStateEvents = - | RoomStateEvent.Events - | RoomStateEvent.Members - | RoomStateEvent.NewMember - | RoomStateEvent.Update - | RoomStateEvent.Marker; - -type CryptoEvents = (typeof CryptoEvent)[keyof typeof CryptoEvent]; - -type MatrixEventEvents = MatrixEventEvent.Decrypted | MatrixEventEvent.Replaced | MatrixEventEvent.VisibilityChange; - -type RoomMemberEvents = - | RoomMemberEvent.Name - | RoomMemberEvent.Typing - | RoomMemberEvent.PowerLevel - | RoomMemberEvent.Membership; - -type UserEvents = - | UserEvent.AvatarUrl - | UserEvent.DisplayName - | UserEvent.Presence - | UserEvent.CurrentlyActive - | UserEvent.LastPresenceTs; - -export type EmittedEvents = - | ClientEvent - | RoomEvents - | RoomStateEvents - | CryptoEvents - | MatrixEventEvents - | RoomMemberEvents - | UserEvents - | CallEvent // re-emitted by call.ts using Object.values - | CallEventHandlerEvent.Incoming - | GroupCallEventHandlerEvent.Incoming - | GroupCallEventHandlerEvent.Outgoing - | GroupCallEventHandlerEvent.Ended - | GroupCallEventHandlerEvent.Participants - | HttpApiEvent.SessionLoggedOut - | HttpApiEvent.NoConsent - | BeaconEvent; - -export type ClientEventHandlerMap = { /** * Fires whenever the SDK's syncing state is updated. The state can be one of: * * - * @param state - An enum representing the syncing state. One of "PREPARED", + * The payloads consits of the following 3 parameters: + * + * - state - An enum representing the syncing state. One of "PREPARED", * "SYNCING", "ERROR", "STOPPED". * - * @param prevState - An enum representing the previous syncing state. + * - prevState - An enum representing the previous syncing state. * One of "PREPARED", "SYNCING", "ERROR", "STOPPED" or null. * - * @param data - Data about this transition. + * - data - Data about this transition. * * @example * ``` @@ -1068,14 +998,14 @@ export type ClientEventHandlerMap = { * }); * ``` */ - [ClientEvent.Sync]: (state: SyncState, prevState: SyncState | null, data?: ISyncStateData) => void; + Sync = "sync", /** * Fires whenever the SDK receives a new event. *

* This is only fired for live events received via /sync - it is not fired for * events received over context, search, or pagination APIs. * - * @param event - The matrix event which caused this event to fire. + * The payload is the matrix event which caused this event to fire. * @example * ``` * matrixClient.on("event", function(event){ @@ -1083,10 +1013,10 @@ export type ClientEventHandlerMap = { * }); * ``` */ - [ClientEvent.Event]: (event: MatrixEvent) => void; - /** + Event = "event", + /** @deprecated Use {@link ReceivedToDeviceMessage}. * Fires whenever the SDK receives a new to-device event. - * @param event - The matrix event which caused this event to fire. + * The payload is the matrix event ({@link MatrixEvent}) which caused this event to fire. * @example * ``` * matrixClient.on("toDeviceEvent", function(event){ @@ -1094,10 +1024,10 @@ export type ClientEventHandlerMap = { * }); * ``` */ - [ClientEvent.ToDeviceEvent]: (event: MatrixEvent) => void; + ToDeviceEvent = "toDeviceEvent", /** - * Fires whenever the SDK receives a new to-device message. - * @param payload - The message and encryptionInfo for this message (See {@link ReceivedToDeviceMessage}) which caused this event to fire. + * Fires whenever the SDK receives a new (potentially decrypted) to-device message. + * The payload is the to-device message and the encryption info for that message ({@link ReceivedToDeviceMessage}). * @example * ``` * matrixClient.on("receivedToDeviceMessage", function(payload){ @@ -1106,10 +1036,57 @@ export type ClientEventHandlerMap = { * var isVerified = encryptionInfo ? encryptionInfo.verified : false; * var type = message.type; * }); + */ + ReceivedToDeviceMessage = "receivedToDeviceMessage", + /** + * Fires whenever new user-scoped account_data is added. + * The payload is a pair of event ({@link MatrixEvent}) describing the account_data just added, and the previous event, if known: + * - event: The event describing the account_data just added + * - oldEvent: The previous account data, if known. + * @example + * ``` + * matrixClient.on("accountData", function(event, oldEvent){ + * myAccountData[event.type] = event.content; + * }); * ``` */ - [ClientEvent.ReceivedToDeviceMessage]: (payload: ReceivedToDeviceMessage) => void; + AccountData = "accountData", /** + * Fires whenever a new Room is added. This will fire when you are invited to a + * room, as well as when you join a room. This event is experimental and + * may change. + * + * The payload is the newly created room, fully populated. + * @example + * ``` + * matrixClient.on("Room", function(room){ + * var roomId = room.roomId; + * }); + * ``` + */ + Room = "Room", + /** + * Fires whenever a Room is removed. This will fire when you forget a room. + * This event is experimental and may change. + * The payload is the roomId of the deleted room. + * @example + * ``` + * matrixClient.on("deleteRoom", function(roomId){ + * // update UI from getRooms() + * }); + * ``` + */ + DeleteRoom = "deleteRoom", + SyncUnexpectedError = "sync.unexpectedError", + /** + * Fires when the client .well-known info is fetched. + * The payload is the JSON object (see {@link IClientWellKnown}) returned by the server + */ + ClientWellKnown = "WellKnown.client", + ReceivedVoipEvent = "received_voip_event", + /** + * @deprecated This event is not supported anymore. + * * Fires if a to-device event is received that cannot be decrypted. * Encrypted to-device events will (generally) use plain Olm encryption, * in which case decryption failures are fatal: the event will never be @@ -1118,52 +1095,78 @@ export type ClientEventHandlerMap = { * * An undecryptable to-device event is therefore likely to indicate problems. * - * @param event - The undecyptable to-device event + * The payload is the undecyptable to-device event */ + UndecryptableToDeviceEvent = "toDeviceEvent.undecryptable", + TurnServers = "turnServers", + TurnServersError = "turnServers.error", +} + +type RoomEvents = + | RoomEvent.Name + | RoomEvent.Redaction + | RoomEvent.RedactionCancelled + | RoomEvent.Receipt + | RoomEvent.Tags + | RoomEvent.LocalEchoUpdated + | RoomEvent.HistoryImportedWithinTimeline + | RoomEvent.AccountData + | RoomEvent.MyMembership + | RoomEvent.Timeline + | RoomEvent.TimelineReset; + +type RoomStateEvents = + | RoomStateEvent.Events + | RoomStateEvent.Members + | RoomStateEvent.NewMember + | RoomStateEvent.Update + | RoomStateEvent.Marker; + +type CryptoEvents = (typeof CryptoEvent)[keyof typeof CryptoEvent]; + +type MatrixEventEvents = MatrixEventEvent.Decrypted | MatrixEventEvent.Replaced | MatrixEventEvent.VisibilityChange; + +type RoomMemberEvents = + | RoomMemberEvent.Name + | RoomMemberEvent.Typing + | RoomMemberEvent.PowerLevel + | RoomMemberEvent.Membership; + +type UserEvents = + | UserEvent.AvatarUrl + | UserEvent.DisplayName + | UserEvent.Presence + | UserEvent.CurrentlyActive + | UserEvent.LastPresenceTs; + +export type EmittedEvents = + | ClientEvent + | RoomEvents + | RoomStateEvents + | CryptoEvents + | MatrixEventEvents + | RoomMemberEvents + | UserEvents + | CallEvent // re-emitted by call.ts using Object.values + | CallEventHandlerEvent.Incoming + | GroupCallEventHandlerEvent.Incoming + | GroupCallEventHandlerEvent.Outgoing + | GroupCallEventHandlerEvent.Ended + | GroupCallEventHandlerEvent.Participants + | HttpApiEvent.SessionLoggedOut + | HttpApiEvent.NoConsent + | BeaconEvent; + +export type ClientEventHandlerMap = { + [ClientEvent.Sync]: (state: SyncState, prevState: SyncState | null, data?: ISyncStateData) => void; + [ClientEvent.Event]: (event: MatrixEvent) => void; + [ClientEvent.ToDeviceEvent]: (event: MatrixEvent) => void; + [ClientEvent.ReceivedToDeviceMessage]: (payload: ReceivedToDeviceMessage) => void; [ClientEvent.UndecryptableToDeviceEvent]: (event: MatrixEvent) => void; - /** - * Fires whenever new user-scoped account_data is added. - * @param event - The event describing the account_data just added - * @param event - The previous account data, if known. - * @example - * ``` - * matrixClient.on("accountData", function(event, oldEvent){ - * myAccountData[event.type] = event.content; - * }); - * ``` - */ [ClientEvent.AccountData]: (event: MatrixEvent, lastEvent?: MatrixEvent) => void; - /** - * Fires whenever a new Room is added. This will fire when you are invited to a - * room, as well as when you join a room. This event is experimental and - * may change. - * @param room - The newly created, fully populated room. - * @example - * ``` - * matrixClient.on("Room", function(room){ - * var roomId = room.roomId; - * }); - * ``` - */ [ClientEvent.Room]: (room: Room) => void; - /** - * Fires whenever a Room is removed. This will fire when you forget a room. - * This event is experimental and may change. - * @param roomId - The deleted room ID. - * @example - * ``` - * matrixClient.on("deleteRoom", function(roomId){ - * // update UI from getRooms() - * }); - * ``` - */ [ClientEvent.DeleteRoom]: (roomId: string) => void; [ClientEvent.SyncUnexpectedError]: (error: Error) => void; - /** - * Fires when the client .well-known info is fetched. - * - * @param data - The JSON object returned by the server - */ [ClientEvent.ClientWellKnown]: (data: IClientWellKnown) => void; [ClientEvent.ReceivedVoipEvent]: (event: MatrixEvent) => void; [ClientEvent.TurnServers]: (servers: ITurnServer[]) => void;