pkg: add type defs for type lints.

.github/workflows/build.yml

@@ -16,14 +16,17 @@ jobs:
         node-version: 20.x
 
     - name: Install tools
-      run: npm install --location=global bslint
+      run: npm install --location=global bslint typescript
 
     - name: Install dependencies
       run: npm install
 
     - name: Lint
       run: npm run lint
 
+    - name: Lint
+      run: npm run lint-types
+
   test:
     name: Test
     runs-on: ${{ matrix.os }}

lib/socks.js

@@ -12,6 +12,28 @@ const net = require('net');
 const {format} = require('util');
 const IP = require('binet');
 
+/**
+ * @typedef {Object} ServerOptions
+ * @property {string} host
+ * @property {number} port
+ * @property {string} [username]
+ * @property {string} [password]
+ */
+
+/**
+ * @typedef {Object} NameOption
+ * @property {string} [name]
+ */
+
+/**
+ * @typedef {Object} DestinationOptions
+ * @property {string} destHost
+ * @property {number} destPort
+ */
+
+/** @typedef {ServerOptions & NameOption} ResolveOptions */
+/** @typedef {ResolveOptions & DestinationOptions} ProxyOptions */
+
 /**
  * SOCKS State Machine
  * @extends EventEmitter
@@ -91,6 +113,11 @@ class SOCKS extends EventEmitter {
     }
   }
 
+  /**
+   * @param {number} port
+   * @param {string} host
+   */
+
   connect(port, host) {
     assert(typeof port === 'number');
     assert(typeof host === 'string');
@@ -123,6 +150,10 @@ class SOCKS extends EventEmitter {
     });
   }
 
+  /**
+   * @param {ResolveOptions} options
+   */
+
   open(options) {
     assert(this.state === SOCKS.states.INIT);
 
@@ -144,6 +175,10 @@ class SOCKS extends EventEmitter {
     this.connect(options.port, options.host);
   }
 
+  /**
+   * @param {ProxyOptions} options
+   */
+
   proxy(options) {
     assert(options);
     assert(typeof options.destHost === 'string');
@@ -156,6 +191,10 @@ class SOCKS extends EventEmitter {
     this.open(options);
   }
 
+  /**
+   * @param {ResolveOptions} options
+   */
+
   resolve(options) {
     assert(options);
     assert(typeof options.name === 'string');
@@ -336,13 +375,13 @@ class SOCKS extends EventEmitter {
     let ip, len, type, name;
 
     switch (IP.getStringType(host)) {
-      case IP.types.IPV4:
+      case IP.types.INET4:
         ip = IP.toBuffer(host);
         type = 0x01;
         name = ip.slice(12, 16);
         len = 4;
         break;
-      case IP.types.IPV6:
+      case IP.types.INET6:
         ip = IP.toBuffer(host);
         type = 0x04;
         name = ip;
@@ -471,6 +510,11 @@ class SOCKS extends EventEmitter {
     this.emit('resolve', [addr.host]);
   }
 
+  /**
+   * @param {ResolveOptions} options
+   * @returns {Promise<string[]>}
+   */
+
   static resolve(options) {
     const socks = new SOCKS();
     return new Promise((resolve, reject) => {
@@ -480,6 +524,11 @@ class SOCKS extends EventEmitter {
     });
   }
 
+  /**
+   * @param {ProxyOptions} options
+   * @returns {Promise<net.Socket>}
+   */
+
   static proxy(options) {
     const socks = new SOCKS();
     return new Promise((resolve, reject) => {
@@ -531,13 +580,16 @@ SOCKS.errors = [
  */
 
 class ProxySocket extends EventEmitter {
+  /** @type {net.Socket} */
+  socket;
+
   /**
    * Create a proxy socket.
    * @constructor
-   * @param {String} host
-   * @param {Number} port
-   * @param {String?} user
-   * @param {String?} pass
+   * @param {string} host
+   * @param {number} port
+   * @param {string} [user]
+   * @param {string} [pass]
    */
 
   constructor(host, port, user, pass) {
@@ -557,12 +609,6 @@ class ProxySocket extends EventEmitter {
     this.ops = [];
   }
 
-  get encrypted() {
-    if (!this.socket)
-      return false;
-    return this.socket.encrypted || false;
-  }
-
   get readable() {
     if (!this.socket)
       return false;
@@ -617,6 +663,12 @@ class ProxySocket extends EventEmitter {
     return this.socket.localPort;
   }
 
+  /**
+   * @param {number} port
+   * @param {string} host
+   * @returns {Promise}
+   */
+
   async connect(port, host) {
     assert(!this.socket, 'Already connected.');
 
@@ -635,7 +687,7 @@ class ProxySocket extends EventEmitter {
     const type = IP.getStringType(host);
 
     this.remoteAddress = host;
-    this.remoteFamily = type === IP.types.IPV6 ? 'IPv6' : 'IPv4';
+    this.remoteFamily = type === IP.types.INET6 ? 'IPv6' : 'IPv4';
     this.remotePort = port;
 
     let socket;
@@ -801,6 +853,11 @@ class ProxySocket extends EventEmitter {
  * Helpers
  */
 
+/**
+ * @param {string} host
+ * @returns {ServerOptions}
+ */
+
 function parseProxy(host) {
   const index = host.indexOf('@');
 
@@ -828,6 +885,19 @@ function parseProxy(host) {
   };
 }
 
+/**
+ * @typedef {Object} AddrInfo
+ * @property {string} host
+ * @property {number} port
+ * @property {number} type
+ */
+
+/**
+ * @param {Buffer} data
+ * @param {number} off
+ * @returns {AddrInfo}
+ */
+
 function parseAddr(data, off) {
   if (data.length - off < 2)
     throw new Error('Bad SOCKS address length.');
@@ -885,6 +955,13 @@ function parseAddr(data, off) {
 
 exports.unsupported = false;
 
+/**
+ * @param {string} proxy
+ * @param {number} destPort
+ * @param {string} destHost
+ * @returns {ProxySocket}
+ */
+
 exports.connect = function connect(proxy, destPort, destHost) {
   const addr = parseProxy(proxy);
   const host = addr.host;
@@ -898,6 +975,12 @@ exports.connect = function connect(proxy, destPort, destHost) {
   return socket;
 };
 
+/**
+ * @param {string} proxy
+ * @param {string} name
+ * @returns {Promise<string[]>}
+ */
+
 exports.resolve = function resolve(proxy, name) {
   const addr = parseProxy(proxy);
   return SOCKS.resolve({

package.json

@@ -16,14 +16,17 @@
   "main": "./lib/bsocks.js",
   "scripts": {
     "lint": "eslint lib/ test/",
+    "lint-types": "tsc -p .",
     "test": "bmocha --reporter spec test/*-test.js"
   },
   "dependencies": {
-    "binet": "~0.3.8",
+    "binet": "~0.3.9",
     "bsert": "~0.0.12"
   },
   "devDependencies": {
-    "bmocha": "^2.1.8"
+    "bmocha": "^2.1.8",
+    "bts-type-deps": "^0.0.3",
+    "bufio": "^1.2.1"
   },
   "engines": {
     "node": ">=8.0.0"

tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "include": [
+    "lib/**/*.js"
+  ],
+  "compilerOptions": {
+    "rootDir": ".",
+    "target": "ES2020",
+    "lib": [
+      "ES2020"
+    ],
+
+    "noEmit": true,
+
+    "allowJs": true,
+    "checkJs": true,
+    "maxNodeModuleJsDepth": 10,
+
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "resolveJsonModule": true,
+
+    "stripInternal": true,
+    "noImplicitThis": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": false,
+
+    "typeRoots": [
+      "node_modules/bts-type-deps/types"
+    ]
+  }
+}