fix(typings): add return types and general-case overload signatures (#3776)

See also: https://stackoverflow.com/questions/52760509/typescript-returntype-of-overloaded-function/52760599#52760599

Author: david-fong

lib/client.ts

@@ -77,7 +77,7 @@ export class Client {
    * @param {Object} auth - the auth parameters
    * @private
    */
-  private connect(name: string, auth: object = {}) {
+  private connect(name: string, auth: object = {}): void {
     if (this.server._nsps.has(name)) {
       debug("connecting to namespace %s", name);
       return this.doConnect(name, auth);
@@ -112,7 +112,7 @@ export class Client {
    *
    * @private
    */
-  private doConnect(name: string, auth: object) {
+  private doConnect(name: string, auth: object): void {
     const nsp = this.server.of(name);
 
     const socket = nsp._add(this, auth, () => {
@@ -131,7 +131,7 @@ export class Client {
    *
    * @private
    */
-  _disconnect() {
+  _disconnect(): void {
     for (const socket of this.sockets.values()) {
       socket.disconnect();
     }
@@ -144,7 +144,7 @@ export class Client {
    *
    * @private
    */
-  _remove(socket: Socket) {
+  _remove(socket: Socket): void {
     if (this.sockets.has(socket.id)) {
       const nsp = this.sockets.get(socket.id)!.nsp.name;
       this.sockets.delete(socket.id);
@@ -159,7 +159,7 @@ export class Client {
    *
    * @private
    */
-  private close() {
+  private close(): void {
     if ("open" === this.conn.readyState) {
       debug("forcing transport close");
       this.conn.close();
@@ -174,12 +174,13 @@ export class Client {
    * @param {Object} opts
    * @private
    */
-  _packet(packet, opts?) {
+  _packet(packet: Packet, opts?: any): void {
     opts = opts || {};
     const self = this;
 
     // this writes to the actual connection
-    function writeToEngine(encodedPackets) {
+    function writeToEngine(encodedPackets: any) {
+      // TODO clarify this.
       if (opts.volatile && !self.conn.transport.writable) return;
       for (let i = 0; i < encodedPackets.length; i++) {
         self.conn.write(encodedPackets[i], { compress: opts.compress });
@@ -205,7 +206,7 @@ export class Client {
    *
    * @private
    */
-  private ondata(data) {
+  private ondata(data): void {
     // try/catch is needed for protocol violations (GH-1880)
     try {
       this.decoder.add(data);
@@ -219,7 +220,7 @@ export class Client {
    *
    * @private
    */
-  private ondecoded(packet: Packet) {
+  private ondecoded(packet: Packet): void {
     if (PacketType.CONNECT === packet.type) {
       this.connect(packet.nsp, packet.data);
     } else {
@@ -240,7 +241,7 @@ export class Client {
    * @param {Object} err object
    * @private
    */
-  private onerror(err) {
+  private onerror(err): void {
     for (const socket of this.sockets.values()) {
       socket._onerror(err);
     }
@@ -253,7 +254,7 @@ export class Client {
    * @param reason
    * @private
    */
-  private onclose(reason: string) {
+  private onclose(reason: string): void {
     debug("client close with reason %s", reason);
 
     // ignore a potential subsequent `close` event
@@ -272,7 +273,7 @@ export class Client {
    * Cleans up event listeners.
    * @private
    */
-  private destroy() {
+  private destroy(): void {
     this.conn.removeListener("data", this.ondata);
     this.conn.removeListener("error", this.onerror);
     this.conn.removeListener("close", this.onclose);

lib/index.ts

@@ -191,6 +191,10 @@ export class Server extends EventEmitter {
    */
   constructor(opts?: Partial<ServerOptions>);
   constructor(srv?: http.Server | number, opts?: Partial<ServerOptions>);
+  constructor(
+    srv: undefined | Partial<ServerOptions> | http.Server | number,
+    opts?: Partial<ServerOptions>
+  );
   constructor(
     srv: undefined | Partial<ServerOptions> | http.Server | number,
     opts: Partial<ServerOptions> = {}
@@ -222,9 +226,10 @@ export class Server extends EventEmitter {
    * @return self when setting or value when getting
    * @public
    */
-  public serveClient(v: boolean): Server;
+  public serveClient(v: boolean): this;
   public serveClient(): boolean;
-  public serveClient(v?: boolean): Server | boolean {
+  public serveClient(v?: boolean): this | boolean;
+  public serveClient(v?: boolean): this | boolean {
     if (!arguments.length) return this._serveClient;
     this._serveClient = v!;
     return this;
@@ -234,7 +239,7 @@ export class Server extends EventEmitter {
    * Executes the middleware for an incoming namespace not already created on the server.
    *
    * @param name - name of incoming namespace
-   * @param {Object} auth - the auth parameters
+   * @param auth - the auth parameters
    * @param fn - callback
    *
    * @private
@@ -243,7 +248,7 @@ export class Server extends EventEmitter {
     name: string,
     auth: object,
     fn: (nsp: Namespace | false) => void
-  ) {
+  ): void {
     if (this.parentNsps.size === 0) return fn(false);
 
     const keysIterator = this.parentNsps.keys();
@@ -272,9 +277,10 @@ export class Server extends EventEmitter {
    * @return {Server|String} self when setting or value when getting
    * @public
    */
-  public path(v: string): Server;
+  public path(v: string): this;
   public path(): string;
-  public path(v?: string): Server | string {
+  public path(v?: string): this | string;
+  public path(v?: string): this | string {
     if (!arguments.length) return this._path;
 
     this._path = v!.replace(/\/$/, "");
@@ -293,9 +299,10 @@ export class Server extends EventEmitter {
    * @param v
    * @public
    */
-  public connectTimeout(v: number): Server;
+  public connectTimeout(v: number): this;
   public connectTimeout(): number;
-  public connectTimeout(v?: number): Server | number {
+  public connectTimeout(v?: number): this | number;
+  public connectTimeout(v?: number): this | number {
     if (v === undefined) return this._connectTimeout;
     this._connectTimeout = v;
     return this;
@@ -309,8 +316,9 @@ export class Server extends EventEmitter {
    * @public
    */
   public adapter(): typeof Adapter | undefined;
-  public adapter(v: typeof Adapter): Server;
-  public adapter(v?: typeof Adapter): typeof Adapter | undefined | Server {
+  public adapter(v: typeof Adapter): this;
+  public adapter(v?: typeof Adapter): typeof Adapter | undefined | this;
+  public adapter(v?: typeof Adapter): typeof Adapter | undefined | this {
     if (!arguments.length) return this._adapter;
     this._adapter = v;
     for (const nsp of this._nsps.values()) {
@@ -330,7 +338,7 @@ export class Server extends EventEmitter {
   public listen(
     srv: http.Server | number,
     opts: Partial<ServerOptions> = {}
-  ): Server {
+  ): this {
     return this.attach(srv, opts);
   }
 
@@ -345,7 +353,7 @@ export class Server extends EventEmitter {
   public attach(
     srv: http.Server | number,
     opts: Partial<ServerOptions> = {}
-  ): Server {
+  ): this {
     if ("function" == typeof srv) {
       const msg =
         "You are trying to attach socket.io to an express " +
@@ -385,7 +393,10 @@ export class Server extends EventEmitter {
    * @param opts - options passed to engine.io
    * @private
    */
-  private initEngine(srv: http.Server, opts: Partial<EngineAttachOptions>) {
+  private initEngine(
+    srv: http.Server,
+    opts: Partial<EngineAttachOptions>
+  ): void {
     // initialize engine
     debug("creating engine.io instance with opts %j", opts);
     this.eio = engine.attach(srv, opts);
@@ -406,7 +417,7 @@ export class Server extends EventEmitter {
    * @param srv http server
    * @private
    */
-  private attachServe(srv: http.Server) {
+  private attachServe(srv: http.Server): void {
     debug("attaching client serving req handler");
 
     const evs = srv.listeners("request").slice(0);
@@ -429,7 +440,7 @@ export class Server extends EventEmitter {
    * @param res
    * @private
    */
-  private serve(req: http.IncomingMessage, res: http.ServerResponse) {
+  private serve(req: http.IncomingMessage, res: http.ServerResponse): void {
     const filename = req.url!.replace(this._path, "");
     const isMap = dotMapRegex.test(filename);
     const type = isMap ? "map" : "source";
@@ -474,7 +485,7 @@ export class Server extends EventEmitter {
     filename: string,
     req: http.IncomingMessage,
     res: http.ServerResponse
-  ) {
+  ): void {
     const readStream = createReadStream(
       path.join(__dirname, "../client-dist/", filename)
     );
@@ -513,7 +524,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public bind(engine): Server {
+  public bind(engine): this {
     this.engine = engine;
     this.engine.on("connection", this.onconnection.bind(this));
     return this;
@@ -526,7 +537,7 @@ export class Server extends EventEmitter {
    * @return self
    * @private
    */
-  private onconnection(conn): Server {
+  private onconnection(conn): this {
     debug("incoming connection with id %s", conn.id);
     const client = new Client(this, conn);
     if (conn.protocol === 3) {
@@ -540,13 +551,13 @@ export class Server extends EventEmitter {
    * Looks up a namespace.
    *
    * @param {String|RegExp|Function} name nsp name
-   * @param [fn] optional, nsp `connection` ev handler
+   * @param fn optional, nsp `connection` ev handler
    * @public
    */
   public of(
     name: string | RegExp | ParentNspNameMatchFn,
     fn?: (socket: Socket) => void
-  ) {
+  ): Namespace {
     if (typeof name === "function" || name instanceof RegExp) {
       const parentNsp = new ParentNamespace(this);
       debug("initializing parent namespace %s", parentNsp.name);
@@ -605,7 +616,7 @@ export class Server extends EventEmitter {
    */
   public use(
     fn: (socket: Socket, next: (err?: ExtendedError) => void) => void
-  ): Server {
+  ): this {
     this.sockets.use(fn);
     return this;
   }
@@ -617,7 +628,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public to(name: Room): Server {
+  public to(name: Room): this {
     this.sockets.to(name);
     return this;
   }
@@ -629,7 +640,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public in(name: Room): Server {
+  public in(name: Room): this {
     this.sockets.in(name);
     return this;
   }
@@ -640,7 +651,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public send(...args: readonly any[]): Server {
+  public send(...args: readonly any[]): this {
     this.sockets.emit("message", ...args);
     return this;
   }
@@ -651,7 +662,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public write(...args: readonly any[]): Server {
+  public write(...args: readonly any[]): this {
     this.sockets.emit("message", ...args);
     return this;
   }
@@ -672,7 +683,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public compress(compress: boolean): Server {
+  public compress(compress: boolean): this {
     this.sockets.compress(compress);
     return this;
   }
@@ -685,7 +696,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public get volatile(): Server {
+  public get volatile(): this {
     this.sockets.volatile;
     return this;
   }
@@ -696,7 +707,7 @@ export class Server extends EventEmitter {
    * @return self
    * @public
    */
-  public get local(): Server {
+  public get local(): this {
     this.sockets.local;
     return this;
   }

lib/namespace.ts

@@ -67,7 +67,7 @@ export class Namespace extends EventEmitter {
    */
   public use(
     fn: (socket: Socket, next: (err?: ExtendedError) => void) => void
-  ): Namespace {
+  ): this {
     this._fns.push(fn);
     return this;
   }
@@ -106,7 +106,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public to(name: Room): Namespace {
+  public to(name: Room): this {
     this._rooms.add(name);
     return this;
   }
@@ -118,7 +118,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public in(name: Room): Namespace {
+  public in(name: Room): this {
     this._rooms.add(name);
     return this;
   }
@@ -222,7 +222,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public send(...args: readonly any[]): Namespace {
+  public send(...args: readonly any[]): this {
     this.emit("message", ...args);
     return this;
   }
@@ -233,7 +233,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public write(...args: readonly any[]): Namespace {
+  public write(...args: readonly any[]): this {
     this.emit("message", ...args);
     return this;
   }
@@ -262,7 +262,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public compress(compress: boolean): Namespace {
+  public compress(compress: boolean): this {
     this._flags.compress = compress;
     return this;
   }
@@ -275,7 +275,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public get volatile(): Namespace {
+  public get volatile(): this {
     this._flags.volatile = true;
     return this;
   }
@@ -286,7 +286,7 @@ export class Namespace extends EventEmitter {
    * @return self
    * @public
    */
-  public get local(): Namespace {
+  public get local(): this {
     this._flags.local = true;
     return this;
   }

lib/socket.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from "events";
-import { PacketType } from "socket.io-parser";
+import { Packet, PacketType } from "socket.io-parser";
 import url = require("url");
 import debugModule from "debug";
 import type { Server } from "./index";
@@ -190,7 +190,7 @@ export class Socket extends EventEmitter {
    * @return self
    * @public
    */
-  public to(name: Room): Socket {
+  public to(name: Room): this {
     this._rooms.add(name);
     return this;
   }
@@ -202,7 +202,7 @@ export class Socket extends EventEmitter {
    * @return self
    * @public
    */
-  public in(name: Room): Socket {
+  public in(name: Room): this {
     this._rooms.add(name);
     return this;
   }
@@ -213,7 +213,7 @@ export class Socket extends EventEmitter {
    * @return self
    * @public
    */
-  public send(...args: readonly any[]): Socket {
+  public send(...args: readonly any[]): this {
     this.emit("message", ...args);
     return this;
   }
@@ -224,7 +224,7 @@ export class Socket extends EventEmitter {
    * @return self
    * @public
    */
-  public write(...args: readonly any[]): Socket {
+  public write(...args: readonly any[]): this {
     this.emit("message", ...args);
     return this;
   }
@@ -236,10 +236,13 @@ export class Socket extends EventEmitter {
    * @param {Object} opts - options
    * @private
    */
-  private packet(packet, opts: any = {}) {
+  private packet(
+    packet: Omit<Packet, "nsp"> & Partial<Pick<Packet, "nsp">>,
+    opts: any = {}
+  ): void {
     packet.nsp = this.nsp.name;
     opts.compress = false !== opts.compress;
-    this.client._packet(packet, opts);
+    this.client._packet(packet as Packet, opts);
   }
 
   /**
@@ -304,7 +307,7 @@ export class Socket extends EventEmitter {
    * @param {Object} packet
    * @private
    */
-  _onpacket(packet) {
+  _onpacket(packet: Packet): void {
     debug("got packet %j", packet);
     switch (packet.type) {
       case PacketType.EVENT:
@@ -335,10 +338,10 @@ export class Socket extends EventEmitter {
   /**
    * Called upon event packet.
    *
-   * @param {Object} packet - packet object
+   * @param {Packet} packet - packet object
    * @private
    */
-  private onevent(packet): void {
+  private onevent(packet: Packet): void {
     const args = packet.data || [];
     debug("emitting event %j", args);
 
@@ -362,7 +365,7 @@ export class Socket extends EventEmitter {
    * @param {Number} id - packet id
    * @private
    */
-  private ack(id: number) {
+  private ack(id: number): () => void {
     const self = this;
     let sent = false;
     return function () {
@@ -386,12 +389,12 @@ export class Socket extends EventEmitter {
    *
    * @private
    */
-  private onack(packet): void {
-    const ack = this.acks.get(packet.id);
+  private onack(packet: Packet): void {
+    const ack = this.acks.get(packet.id!);
     if ("function" == typeof ack) {
       debug("calling ack %s with %j", packet.id, packet.data);
       ack.apply(this, packet.data);
-      this.acks.delete(packet.id);
+      this.acks.delete(packet.id!);
     } else {
       debug("bad ack %s", packet.id);
     }
@@ -429,7 +432,7 @@ export class Socket extends EventEmitter {
    *
    * @private
    */
-  _onclose(reason: string): Socket | undefined {
+  _onclose(reason: string): this | undefined {
     if (!this.connected) return this;
     debug("closing socket - reason %s", reason);
     super.emit("disconnecting", reason);
@@ -449,7 +452,7 @@ export class Socket extends EventEmitter {
    *
    * @private
    */
-  _error(err) {
+  _error(err): void {
     this.packet({ type: PacketType.CONNECT_ERROR, data: err });
   }
 
@@ -461,7 +464,7 @@ export class Socket extends EventEmitter {
    *
    * @public
    */
-  public disconnect(close = false): Socket {
+  public disconnect(close = false): this {
     if (!this.connected) return this;
     if (close) {
       this.client._disconnect();
@@ -479,7 +482,7 @@ export class Socket extends EventEmitter {
    * @return {Socket} self
    * @public
    */
-  public compress(compress: boolean): Socket {
+  public compress(compress: boolean): this {
     this.flags.compress = compress;
     return this;
   }
@@ -492,7 +495,7 @@ export class Socket extends EventEmitter {
    * @return {Socket} self
    * @public
    */
-  public get volatile(): Socket {
+  public get volatile(): this {
     this.flags.volatile = true;
     return this;
   }
@@ -504,7 +507,7 @@ export class Socket extends EventEmitter {
    * @return {Socket} self
    * @public
    */
-  public get broadcast(): Socket {
+  public get broadcast(): this {
     this.flags.broadcast = true;
     return this;
   }
@@ -515,7 +518,7 @@ export class Socket extends EventEmitter {
    * @return {Socket} self
    * @public
    */
-  public get local(): Socket {
+  public get local(): this {
     this.flags.local = true;
     return this;
   }
@@ -526,7 +529,7 @@ export class Socket extends EventEmitter {
    * @param {Array} event - event that will get emitted
    * @private
    */
-  private dispatch(event): void {
+  private dispatch(event: [eventName: string, ...args: any[]]): void {
     debug("dispatching an event %j", event);
     this.run(event, (err) => {
       process.nextTick(() => {
@@ -547,7 +550,7 @@ export class Socket extends EventEmitter {
    */
   public use(
     fn: (event: Array<any>, next: (err: Error) => void) => void
-  ): Socket {
+  ): this {
     this.fns.push(fn);
     return this;
   }
@@ -559,11 +562,14 @@ export class Socket extends EventEmitter {
    * @param {Function} fn - last fn call in the middleware
    * @private
    */
-  private run(event: Array<any>, fn: (err: Error | null) => void) {
+  private run(
+    event: [eventName: string, ...args: any[]],
+    fn: (err: Error | null) => void
+  ): void {
     const fns = this.fns.slice(0);
     if (!fns.length) return fn(null);
 
-    function run(i) {
+    function run(i: number) {
       fns[i](event, function (err) {
         // upon error, short-circuit
         if (err) return fn(err);
@@ -611,7 +617,7 @@ export class Socket extends EventEmitter {
    * @param listener
    * @public
    */
-  public onAny(listener: (...args: any[]) => void): Socket {
+  public onAny(listener: (...args: any[]) => void): this {
     this._anyListeners = this._anyListeners || [];
     this._anyListeners.push(listener);
     return this;
@@ -624,7 +630,7 @@ export class Socket extends EventEmitter {
    * @param listener
    * @public
    */
-  public prependAny(listener: (...args: any[]) => void): Socket {
+  public prependAny(listener: (...args: any[]) => void): this {
     this._anyListeners = this._anyListeners || [];
     this._anyListeners.unshift(listener);
     return this;
@@ -636,7 +642,7 @@ export class Socket extends EventEmitter {
    * @param listener
    * @public
    */
-  public offAny(listener?: (...args: any[]) => void): Socket {
+  public offAny(listener?: (...args: any[]) => void): this {
     if (!this._anyListeners) {
       return this;
     }