refactor: add list of possible disconnection reasons

Note: some disconnection reasons could be merged in the next major
release, i.e. the Deno impl does not have "forced server close" and
"server shutting down"

Related: #4387

Author: darrachequesne

lib/client.ts

@@ -18,6 +18,13 @@ interface WriteOptions {
   wsPreEncoded?: string;
 }
 
+type CloseReason =
+  | "transport error"
+  | "transport close"
+  | "forced close"
+  | "ping timeout"
+  | "parse error";
+
 export class Client<
   ListenEvents extends EventsMap,
   EmitEvents extends EventsMap,
@@ -306,7 +313,7 @@ export class Client<
    * @param reason
    * @private
    */
-  private onclose(reason: string): void {
+  private onclose(reason: CloseReason | "forced server close"): void {
     debug("client close with reason %s", reason);
 
     // ignore a potential subsequent `close` event

lib/socket.ts

@@ -25,9 +25,23 @@ const debug = debugModule("socket.io:socket");
 
 type ClientReservedEvents = "connect_error";
 
+// TODO for next major release: cleanup disconnect reasons
+export type DisconnectReason =
+  // Engine.IO close reasons
+  | "transport error"
+  | "transport close"
+  | "forced close"
+  | "ping timeout"
+  | "parse error"
+  // Socket.IO disconnect reasons
+  | "server shutting down"
+  | "forced server close"
+  | "client namespace disconnect"
+  | "server namespace disconnect";
+
 export interface SocketReservedEventsMap {
-  disconnect: (reason: string) => void;
-  disconnecting: (reason: string) => void;
+  disconnect: (reason: DisconnectReason) => void;
+  disconnecting: (reason: DisconnectReason) => void;
   error: (err: Error) => void;
 }
 
@@ -509,7 +523,7 @@ export class Socket<
    *
    * @private
    */
-  _onclose(reason: string): this | undefined {
+  _onclose(reason: DisconnectReason): this | undefined {
     if (!this.connected) return this;
     debug("closing socket - reason %s", reason);
     this.emitReserved("disconnecting", reason);

test/socket.io.test-d.ts

@@ -4,6 +4,7 @@ import type { DefaultEventsMap } from "../lib/typed-events";
 import { createServer } from "http";
 import { expectError, expectType } from "tsd";
 import { Adapter } from "socket.io-adapter";
+import type { DisconnectReason } from "../lib/socket";
 
 // This file is run by tsd, not mocha.
 
@@ -17,10 +18,10 @@ describe("server", () => {
           sio.on("connection", (s) => {
             expectType<Socket<DefaultEventsMap, DefaultEventsMap>>(s);
             s.on("disconnect", (reason) => {
-              expectType<string>(reason);
+              expectType<DisconnectReason>(reason);
             });
             s.on("disconnecting", (reason) => {
-              expectType<string>(reason);
+              expectType<DisconnectReason>(reason);
             });
           });
           sio.on("connect", (s) => {