[minor] Improve JSDoc-inferred types (#1912)

Refs: #1910
websockets · Jul 7, 2021 · ecb9d9e · ecb9d9e
1 parent 0ad1f9d
commit ecb9d9e
Show file tree

Hide file tree

Showing 5 changed files with 145 additions and 36 deletions.
diff --git a/lib/receiver.js b/lib/receiver.js
@@ -22,7 +22,7 @@ const INFLATING = 5;
 /**
  * HyBi Receiver implementation.
  *
- * @extends stream.Writable
+ * @extends Writable
  */
 class Receiver extends Writable {
   /**
@@ -586,7 +586,7 @@ module.exports = Receiver;
 /**
  * Builds an error object.
  *
- * @param {(Error|RangeError)} ErrorCtor The error constructor
+ * @param {function(new:Error|RangeError)} ErrorCtor The error constructor
  * @param {String} message The error message
  * @param {Boolean} prefix Specifies whether or not to add a default prefix to
  *     `message`

diff --git a/lib/sender.js b/lib/sender.js
@@ -1,5 +1,9 @@
+/* eslint no-unused-vars: ["error", { "varsIgnorePattern": "^net|tls$" }] */
+
 'use strict';
 
+const net = require('net');
+const tls = require('tls');
 const { randomFillSync } = require('crypto');
 
 const PerMessageDeflate = require('./permessage-deflate');
@@ -16,7 +20,7 @@ class Sender {
   /**
    * Creates a Sender instance.
    *
-   * @param {net.Socket} socket The connection socket
+   * @param {(net.Socket|tls.Socket)} socket The connection socket
    * @param {Object} [extensions] An object containing the negotiated extensions
    */
   constructor(socket, extensions) {

diff --git a/lib/stream.js b/lib/stream.js
@@ -5,7 +5,7 @@ const { Duplex } = require('stream');
 /**
  * Emits the `'close'` event on a stream.
  *
- * @param {stream.Duplex} The stream.
+ * @param {Duplex} stream The stream.
  * @private
  */
 function emitClose(stream) {
@@ -43,7 +43,7 @@ function duplexOnError(err) {
  *
  * @param {WebSocket} ws The `WebSocket` to wrap
  * @param {Object} [options] The options for the `Duplex` constructor
- * @return {stream.Duplex} The duplex stream
+ * @return {Duplex} The duplex stream
  * @public
  */
 function createWebSocketStream(ws, options) {

diff --git a/lib/websocket-server.js b/lib/websocket-server.js
@@ -1,8 +1,13 @@
+/* eslint no-unused-vars: ["error", { "varsIgnorePattern": "^net|tls|https$" }] */
+
 'use strict';
 
 const EventEmitter = require('events');
+const http = require('http');
+const https = require('https');
+const net = require('net');
+const tls = require('tls');
 const { createHash } = require('crypto');
-const { createServer, STATUS_CODES } = require('http');
 
 const PerMessageDeflate = require('./permessage-deflate');
 const WebSocket = require('./websocket');
@@ -34,7 +39,8 @@ class WebSocketServer extends EventEmitter {
    * @param {(Boolean|Object)} [options.perMessageDeflate=false] Enable/disable
    *     permessage-deflate
    * @param {Number} [options.port] The port where to bind the server
-   * @param {http.Server} [options.server] A pre-created HTTP/S server to use
+   * @param {(http.Server|https.Server)} [options.server] A pre-created HTTP/S
+   *     server to use
    * @param {Function} [options.verifyClient] A hook to reject connections
    * @param {Function} [callback] A listener for the `listening` event
    */
@@ -63,8 +69,8 @@ class WebSocketServer extends EventEmitter {
     }
 
     if (options.port != null) {
-      this._server = createServer((req, res) => {
-        const body = STATUS_CODES[426];
+      this._server = http.createServer((req, res) => {
+        const body = http.STATUS_CODES[426];
 
         res.writeHead(426, {
           'Content-Length': body.length,
@@ -173,7 +179,8 @@ class WebSocketServer extends EventEmitter {
    * Handle a HTTP Upgrade request.
    *
    * @param {http.IncomingMessage} req The request object
-   * @param {net.Socket} socket The network socket between the server and client
+   * @param {(net.Socket|tls.Socket)} socket The network socket between the
+   *     server and client
    * @param {Buffer} head The first packet of the upgraded stream
    * @param {Function} cb Callback
    * @public
@@ -252,7 +259,8 @@ class WebSocketServer extends EventEmitter {
    * @param {String} key The value of the `Sec-WebSocket-Key` header
    * @param {Object} extensions The accepted extensions
    * @param {http.IncomingMessage} req The request object
-   * @param {net.Socket} socket The network socket between the server and client
+   * @param {(net.Socket|tls.Socket)} socket The network socket between the
+   *     server and client
    * @param {Buffer} head The first packet of the upgraded stream
    * @param {Function} cb Callback
    * @throws {Error} If called more than once with the same socket
@@ -375,15 +383,15 @@ function socketOnError() {
 /**
  * Close the connection when preconditions are not fulfilled.
  *
- * @param {net.Socket} socket The socket of the upgrade request
+ * @param {(net.Socket|tls.Socket)} socket The socket of the upgrade request
  * @param {Number} code The HTTP response status code
  * @param {String} [message] The HTTP response body
  * @param {Object} [headers] Additional HTTP response headers
  * @private
  */
 function abortHandshake(socket, code, message, headers) {
   if (socket.writable) {
-    message = message || STATUS_CODES[code];
+    message = message || http.STATUS_CODES[code];
     headers = {
       Connection: 'close',
       'Content-Type': 'text/html',
@@ -392,7 +400,7 @@ function abortHandshake(socket, code, message, headers) {
     };
 
     socket.write(
-      `HTTP/1.1 ${code} ${STATUS_CODES[code]}\r\n` +
+      `HTTP/1.1 ${code} ${http.STATUS_CODES[code]}\r\n` +
         Object.keys(headers)
           .map((h) => `${h}: ${headers[h]}`)
           .join('\r\n') +

diff --git a/lib/websocket.js b/lib/websocket.js
@@ -36,7 +36,7 @@ class WebSocket extends EventEmitter {
   /**
    * Create a new `WebSocket`.
    *
-   * @param {(String|url.URL)} address The URL to which to connect
+   * @param {(String|URL)} address The URL to which to connect
    * @param {(String|String[])} [protocols] The subprotocols
    * @param {Object} [options] Connection options
    */
@@ -112,6 +112,50 @@ class WebSocket extends EventEmitter {
     return Object.keys(this._extensions).join();
   }
 
+  /**
+   * @type {Function}
+   */
+  /* istanbul ignore next */
+  get onclose() {
+    return undefined;
+  }
+
+  /* istanbul ignore next */
+  set onclose(listener) {}
+
+  /**
+   * @type {Function}
+   */
+  /* istanbul ignore next */
+  get onerror() {
+    return null;
+  }
+
+  /* istanbul ignore next */
+  set onerror(listener) {}
+
+  /**
+   * @type {Function}
+   */
+  /* istanbul ignore next */
+  get onopen() {
+    return undefined;
+  }
+
+  /* istanbul ignore next */
+  set onopen(listener) {}
+
+  /**
+   * @type {Function}
+   */
+  /* istanbul ignore next */
+  get onmessage() {
+    return undefined;
+  }
+
+  /* istanbul ignore next */
+  set onmessage(listener) {}
+
   /**
    * @type {String}
    */
@@ -136,7 +180,8 @@ class WebSocket extends EventEmitter {
   /**
    * Set up the socket and the internal resources.
    *
-   * @param {net.Socket} socket The network socket between the server and client
+   * @param {(net.Socket|tls.Socket)} socket The network socket between the
+   *     server and client
    * @param {Buffer} head The first packet of the upgraded stream
    * @param {Number} [maxPayload=0] The maximum allowed message size
    * @private
@@ -392,11 +437,76 @@ class WebSocket extends EventEmitter {
   }
 }
 
-readyStates.forEach((readyState, i) => {
-  const descriptor = { enumerable: true, value: i };
+/**
+ * @constant {Number} CONNECTING
+ * @memberof WebSocket
+ */
+Object.defineProperty(WebSocket, 'CONNECTING', {
+  enumerable: true,
+  value: readyStates.indexOf('CONNECTING')
+});
 
-  Object.defineProperty(WebSocket.prototype, readyState, descriptor);
-  Object.defineProperty(WebSocket, readyState, descriptor);
+/**
+ * @constant {Number} CONNECTING
+ * @memberof WebSocket.prototype
+ */
+Object.defineProperty(WebSocket.prototype, 'CONNECTING', {
+  enumerable: true,
+  value: readyStates.indexOf('CONNECTING')
+});
+
+/**
+ * @constant {Number} OPEN
+ * @memberof WebSocket
+ */
+Object.defineProperty(WebSocket, 'OPEN', {
+  enumerable: true,
+  value: readyStates.indexOf('OPEN')
+});
+
+/**
+ * @constant {Number} OPEN
+ * @memberof WebSocket.prototype
+ */
+Object.defineProperty(WebSocket.prototype, 'OPEN', {
+  enumerable: true,
+  value: readyStates.indexOf('OPEN')
+});
+
+/**
+ * @constant {Number} CLOSING
+ * @memberof WebSocket
+ */
+Object.defineProperty(WebSocket, 'CLOSING', {
+  enumerable: true,
+  value: readyStates.indexOf('CLOSING')
+});
+
+/**
+ * @constant {Number} CLOSING
+ * @memberof WebSocket.prototype
+ */
+Object.defineProperty(WebSocket.prototype, 'CLOSING', {
+  enumerable: true,
+  value: readyStates.indexOf('CLOSING')
+});
+
+/**
+ * @constant {Number} CLOSED
+ * @memberof WebSocket
+ */
+Object.defineProperty(WebSocket, 'CLOSED', {
+  enumerable: true,
+  value: readyStates.indexOf('CLOSED')
+});
+
+/**
+ * @constant {Number} CLOSED
+ * @memberof WebSocket.prototype
+ */
+Object.defineProperty(WebSocket.prototype, 'CLOSED', {
+  enumerable: true,
+  value: readyStates.indexOf('CLOSED')
 });
 
 [
@@ -416,14 +526,7 @@ readyStates.forEach((readyState, i) => {
 //
 ['open', 'error', 'close', 'message'].forEach((method) => {
   Object.defineProperty(WebSocket.prototype, `on${method}`, {
-    configurable: true,
     enumerable: true,
-    /**
-     * Return the listener of the event.
-     *
-     * @return {(Function|undefined)} The event listener or `undefined`
-     * @public
-     */
     get() {
       const listeners = this.listeners(method);
       for (let i = 0; i < listeners.length; i++) {
@@ -432,12 +535,6 @@ readyStates.forEach((readyState, i) => {
 
       return undefined;
     },
-    /**
-     * Add a listener for the event.
-     *
-     * @param {Function} listener The listener to add
-     * @public
-     */
     set(listener) {
       const listeners = this.listeners(method);
       for (let i = 0; i < listeners.length; i++) {
@@ -460,7 +557,7 @@ module.exports = WebSocket;
  * Initialize a WebSocket client.
  *
  * @param {WebSocket} websocket The client to initialize
- * @param {(String|url.URL)} address The URL to which to connect
+ * @param {(String|URL)} address The URL to which to connect
  * @param {String} [protocols] The subprotocols
  * @param {Object} [options] Connection options
  * @param {(Boolean|Object)} [options.perMessageDeflate=true] Enable/disable
@@ -744,8 +841,8 @@ function tlsConnect(options) {
  * Abort the handshake and emit an error.
  *
  * @param {WebSocket} websocket The WebSocket instance
- * @param {(http.ClientRequest|net.Socket)} stream The request to abort or the
- *     socket to destroy
+ * @param {(http.ClientRequest|net.Socket|tls.Socket)} stream The request to
+ *     abort or the socket to destroy
  * @param {String} message The error message
  * @private
  */