refactor: improve type annotations and comments (#5364)

Author: jokester

packages/engine.io-parser/lib/commons.ts

@@ -32,7 +32,11 @@ export type RawData = any;
 
 export interface Packet {
   type: PacketType;
-  options?: { compress: boolean };
+  options?: {
+    compress: boolean;
+    wsPreEncoded?: string; // deprecated in favor of `wsPreEncodedFrame`
+    wsPreEncodedFrame?: any; // computed in the socket.io-adapter package (should be typed as Buffer)
+  };
   data?: RawData;
 }
 

packages/engine.io/lib/engine.io.ts

@@ -1,27 +1,36 @@
-import { createServer } from "http";
+import { createServer, Server as HttpServer } from "http";
 import { Server, AttachOptions, ServerOptions } from "./server";
 import transports from "./transports/index";
 import * as parser from "engine.io-parser";
 
 export { Server, transports, listen, attach, parser };
-export type { AttachOptions, ServerOptions, BaseServer } from "./server";
+export type {
+  AttachOptions,
+  ServerOptions,
+  BaseServer,
+  ErrorCallback,
+} from "./server";
 export { uServer } from "./userver";
 export { Socket } from "./socket";
 export { Transport } from "./transport";
 export const protocol = parser.protocol;
 
 /**
- * Creates an http.Server exclusively used for WS upgrades.
+ * Creates an http.Server exclusively used for WS upgrades, and starts listening.
  *
- * @param {Number} port
- * @param {Function} callback
- * @param {Object} options
- * @return {Server} websocket.io server
+ * @param port
+ * @param options
+ * @param listenCallback - callback for http.Server.listen()
+ * @return engine.io server
  */
 
-function listen(port, options: AttachOptions & ServerOptions, fn) {
+function listen(
+  port: number,
+  options?: AttachOptions & ServerOptions,
+  listenCallback?: () => void,
+): Server {
   if ("function" === typeof options) {
-    fn = options;
+    listenCallback = options;
     options = {};
   }
 
@@ -34,20 +43,23 @@ function listen(port, options: AttachOptions & ServerOptions, fn) {
   const engine = attach(server, options);
   engine.httpServer = server;
 
-  server.listen(port, fn);
+  server.listen(port, listenCallback);
 
   return engine;
 }
 
 /**
  * Captures upgrade requests for a http.Server.
  *
- * @param {http.Server} server
- * @param {Object} options
- * @return {Server} engine server
+ * @param server
+ * @param options
+ * @return engine.io server
  */
 
-function attach(server, options: AttachOptions & ServerOptions) {
+function attach(
+  server: HttpServer,
+  options: AttachOptions & ServerOptions,
+): Server {
   const engine = new Server(options);
   engine.attach(server, options);
   return engine;

packages/engine.io/lib/parser-v3/index.ts

@@ -59,8 +59,7 @@ const EMPTY_BUFFER = Buffer.concat([]);
  *
  * @api private
  */
-
-export function encodePacket (packet, supportsBinary, utf8encode, callback) {
+export function encodePacket (packet: any, supportsBinary?: any, utf8encode?: any, callback?: any) {
   if (typeof supportsBinary === 'function') {
     callback = supportsBinary;
     supportsBinary = null;
@@ -86,7 +85,7 @@ export function encodePacket (packet, supportsBinary, utf8encode, callback) {
   }
 
   return callback('' + encoded);
-};
+}
 
 /**
  * Encode Buffer data
@@ -120,16 +119,16 @@ export function encodeBase64Packet (packet, callback){
 /**
  * Decodes a packet. Data also available as an ArrayBuffer if requested.
  *
- * @return {Object} with `type` and `data` (if any)
+ * @return {import('engine.io-parser').Packet} with `type` and `data` (if any)
  * @api private
  */
 
-export function decodePacket (data, binaryType, utf8decode) {
+export function decodePacket (data: any, binaryType?: any, utf8decode?: any): any {
   if (data === undefined) {
     return err;
   }
 
-  var type;
+  let type: string | number;
 
   // String data
   if (typeof data === 'string') {
@@ -147,6 +146,7 @@ export function decodePacket (data, binaryType, utf8decode) {
       }
     }
 
+    // @ts-expect-error
     if (Number(type) != type || !packetslist[type]) {
       return err;
     }
@@ -274,7 +274,7 @@ function map(ary, each, done) {
  * @api public
  */
 
-export function decodePayload (data, binaryType, callback) {
+export function decodePayload (data: any, binaryType?: any, callback?: any) {
   if (typeof data !== 'string') {
     return decodePayloadAsBinary(data, binaryType, callback);
   }