refactor: Biiig refactor to fix ALL jsdoc & tsd-jsdoc errors

eslint.config.mjs

@@ -4,10 +4,10 @@
  * Created Date: 2024-05-03 12:17:16
  * Author: 3urobeat
  *
- * Last Modified: 2024-05-04 22:00:04
+ * Last Modified: 2025-01-12 13:27:54
  * Modified By: 3urobeat
  *
- * Copyright (c) 2024 3urobeat <https://github.com/3urobeat>
+ * Copyright (c) 2024 - 2025 3urobeat <https://github.com/3urobeat>
  *
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -75,7 +75,7 @@ export default [
             // JsDoc - https://github.com/gajus/eslint-plugin-jsdoc
             "jsdoc/check-alignment": "warn",
             "jsdoc/check-indentation": "warn",
-            "jsdoc/check-types": "warn",
+            "jsdoc/check-types": "off", // We need to use syntax Object.<string, string> instead of shorthander {[key: string]: string} for jsdoc & tsd-jsdoc to work
             "jsdoc/informative-docs": "warn",
             "jsdoc/require-asterisk-prefix": "warn",
             "jsdoc/require-description": "warn",

jsdoc.config.json

@@ -0,0 +1,13 @@
+{
+    "source": {
+        "include": [ "./src" ],
+        "exclude": [ "./src/commands/core/", "./src/libraryPatches/" ]
+    },
+    "opts": {
+        "encoding": "utf8",
+        "destination": "out/",
+        "recurse": true,
+        "verbose": false
+    },
+    "plugins": [ "node_modules/jsdoc-tsimport-plugin/index.js" ]
+}

package.json

@@ -24,7 +24,7 @@
     "scripts": {
         "start": "node start.js",
         "dev": "node scripts/generateFileStructure.js && node start",
-        "types": "jsdoc -t node_modules/tsd-jsdoc/dist -r src/. -d types ; node scripts/generateFileStructure.js",
+        "types": "jsdoc -t node_modules/tsd-jsdoc/dist -c jsdoc.config.json -d types ; node scripts/generateFileStructure.js",
         "deps": "ncu -u && npm update"
     },
     "author": "3urobeat",
@@ -38,7 +38,11 @@
         "@eslint/js": "^9.15.0",
         "eslint": "^9.15.0",
         "eslint-plugin-jsdoc": "^50.5.0",
+        "jsdoc": "^4.0.4",
         "tsd-jsdoc": "^2.5.0"
     },
+    "overrides": {
+        "jsdoc": "^4.0.4"
+    },
     "types": "./types/types.d.ts"
 }

src/bot/EStatus.js

@@ -4,10 +4,10 @@
  * Created Date: 2023-05-29 16:55:46
  * Author: 3urobeat
  *
- * Last Modified: 2024-02-27 17:24:37
+ * Last Modified: 2025-01-12 15:46:53
  * Modified By: 3urobeat
  *
- * Copyright (c) 2023 - 2024 3urobeat <https://github.com/3urobeat>
+ * Copyright (c) 2023 - 2025 3urobeat <https://github.com/3urobeat>
  *
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -19,7 +19,7 @@
  * Status which a bot object can have
  * @enum EStatus
  */
-module.exports = {
+const EStatus = {
     "OFFLINE": 0,
     "ONLINE": 1,
     "ERROR": 2,
@@ -33,3 +33,5 @@ module.exports = {
     "3": "SKIPPED",
     "4": "POSTPONED"
 };
+
+module.exports = EStatus;

src/bot/bot.js

@@ -4,7 +4,7 @@
  * Created Date: 2021-07-09 16:26:00
  * Author: 3urobeat
  *
- * Last Modified: 2025-01-03 21:05:37
+ * Last Modified: 2025-01-12 15:46:23
  * Modified By: 3urobeat
  *
  * Copyright (c) 2021 - 2025 3urobeat <https://github.com/3urobeat>
@@ -67,13 +67,10 @@ const Bot = function(controller, index) {
 
     /**
      * Additional login related information for this bot account
+     * @type {{ logOnOptions: DataManager.logOnOptions, logOnTries: number, relogTries: number, pendingLogin: boolean, waitingFor2FA: boolean, proxyIndex: number, proxy: string }}
      */
     this.loginData = {
-        /**
-         * @type {{ index: number, accountName: string, password: string, sharedSecret?: string, steamGuardCode?: null, machineName?: string, deviceFriendlyName?: string }}
-         */
         logOnOptions:  controller.data.logininfo.find((e) => e.index == index), // TODO: This could be an issue later when the index could change at runtime
-
         logOnTries:    0,
         relogTries:    0, // Amount of times logOns have been retried after relogTimeout. handleRelog() attempts to cycle proxies after enough failures
         pendingLogin:  false,
@@ -90,6 +87,7 @@ const Bot = function(controller, index) {
 
     /**
      * Stores the timestamp and reason of the last disconnect. This is used by handleRelog() to take proper action
+     * @type {{ timestamp: number, reason: string }}
      */
     this.lastDisconnect = {
         timestamp: 0,
@@ -335,7 +333,7 @@ Bot.prototype.unlockFamilyView = function() {};
 
 /**
  * Internal - Attempts to get a cached family view code for this account from tokens.db
- * @param {function(string|null): void} callback Called with `familyViewCode` (String) on success or `null` on failure
+ * @param {function((string|null)): void} callback Called with `familyViewCode` (String) on success or `null` on failure
  */
 Bot.prototype._getFamilyViewCodeFromStorage = function(callback) {}; // eslint-disable-line
 
@@ -386,6 +384,6 @@ Bot.prototype.sendChatMessage = function(_this, resInfo, txt, retry, part = 0) {
  * Waits for a Steam Chat message from this user to this account and resolves their message content. The "normal" friendMessage event handler will be blocked for this user.
  * @param {string} steamID64 The steamID64 of the user to read a message from
  * @param {number} timeout Time in ms after which the Promise will be resolved if user does not respond. Pass 0 to disable (not recommended)
- * @returns {Promise.<string|null>} Resolved with `String` on response or `null` on timeout.
+ * @returns {Promise.<(string|null)>} Resolved with `String` on response or `null` on timeout.
  */
 Bot.prototype.readChatMessage = function(steamID64, timeout) {}; // eslint-disable-line

src/bot/helpers/handleFamilyView.js

@@ -4,10 +4,10 @@
  * Created Date: 2024-12-20 23:51:51
  * Author: 3urobeat
  *
- * Last Modified: 2024-12-27 14:07:39
+ * Last Modified: 2025-01-12 12:24:26
  * Modified By: 3urobeat
  *
- * Copyright (c) 2024 3urobeat <https://github.com/3urobeat>
+ * Copyright (c) 2024 - 2025 3urobeat <https://github.com/3urobeat>
  *
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -157,7 +157,7 @@ Bot.prototype.unlockFamilyView = function() {
 
 /**
  * Internal - Attempts to get a cached family view code for this account from tokens.db
- * @param {function(string|null): void} callback Called with `familyViewCode` (String) on success or `null` on failure
+ * @param {function((string|null)): void} callback Called with `familyViewCode` (String) on success or `null` on failure
  */
 Bot.prototype._getFamilyViewCodeFromStorage = function(callback) {
 

src/bot/helpers/steamChatInteraction.js

@@ -4,10 +4,10 @@
  * Created Date: 2023-04-01 21:09:00
  * Author: 3urobeat
  *
- * Last Modified: 2024-02-11 16:19:27
+ * Last Modified: 2025-01-12 12:24:26
  * Modified By: 3urobeat
  *
- * Copyright (c) 2023 - 2024 3urobeat <https://github.com/3urobeat>
+ * Copyright (c) 2023 - 2025 3urobeat <https://github.com/3urobeat>
  *
  * This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
@@ -116,7 +116,7 @@ Bot.prototype.sendChatMessage = function(_this, resInfo, txt, retry = 0, part =
  * Waits for a Steam Chat message from this user to this account and resolves their message content. The "normal" friendMessage event handler will be blocked for this user.
  * @param {string} steamID64 The steamID64 of the user to read a message from
  * @param {number} timeout Time in ms after which the Promise will be resolved if user does not respond. Pass 0 to disable (not recommended)
- * @returns {Promise.<string|null>} Resolved with `String` on response or `null` on timeout.
+ * @returns {Promise.<(string|null)>} Resolved with `String` on response or `null` on timeout.
  */
 Bot.prototype.readChatMessage = function(steamID64, timeout) {
     return new Promise((resolve) => {

src/commands/commandHandler.js

@@ -4,7 +4,7 @@
  * Created Date: 2023-04-01 21:54:21
  * Author: 3urobeat
  *
- * Last Modified: 2025-01-12 11:41:44
+ * Last Modified: 2025-01-12 15:48:21
  * Modified By: 3urobeat
  *
  * Copyright (c) 2023 - 2025 3urobeat <https://github.com/3urobeat>
@@ -23,7 +23,7 @@ const Controller = require("../controller/controller.js"); // eslint-disable-lin
 /**
  * @typedef Command Documentation of the Command structure
  * @type {object}
- * @property {[string]} names All names that should trigger this command
+ * @property {Array.<string>} names All names that should trigger this command
  * @property {string} description Description of what this command does
  * @property {Array.<CommandArg>} args Array of objects containing information about each parameter supported by this command
  * @property {boolean} ownersOnly Set to true to only allow owners to use this command.
@@ -282,6 +282,6 @@ module.exports = CommandHandler;
 /**
  * Calculates command suggestions using the Jaro Winkler distance of `input` to all registered commands
  * @param {string} input String to get the nearest registered commands of
- * @returns {{ name: string, closeness: number }[]} Returns a sorted Array of Objects, containing the command name and closeness in percent of name to `input` of every registered command
+ * @returns {Array.<{ name: string, closeness: number }>} Returns a sorted Array of Objects, containing the command name and closeness in percent of name to `input` of every registered command
  */
 CommandHandler.prototype.calculateCommandSuggestions = function(input) {}; // eslint-disable-line

src/commands/helpers/calculateSuggestion.js

@@ -4,7 +4,7 @@
  * Created Date: 2024-12-23 14:10:58
  * Author: 3urobeat
  *
- * Last Modified: 2025-01-12 11:41:33
+ * Last Modified: 2025-01-12 15:48:32
  * Modified By: 3urobeat
  *
  * Copyright (c) 2024 - 2025 3urobeat <https://github.com/3urobeat>
@@ -14,9 +14,6 @@
  * You should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.
  */
 
-/**
- * @module CommandHandler
- */
 
 const CommandHandler = require("../commandHandler.js");
 
@@ -102,7 +99,7 @@ function jaroWinkler(s1, s2) {
 /**
  * Calculates command suggestions using the Jaro Winkler distance of `input` to all registered commands
  * @param {string} input String to get the nearest registered commands of
- * @returns {{ name: string, closeness: number }[]} Returns a sorted Array of Objects, containing the command name and closeness in percent of name to `input` of every registered command
+ * @returns {Array.<{ name: string, closeness: number }>} Returns a sorted Array of Objects, containing the command name and closeness in percent of name to `input` of every registered command
  */
 CommandHandler.prototype.calculateCommandSuggestions = function(input) {
     const result = [];

src/controller/controller.js

@@ -4,7 +4,7 @@
  * Created Date: 2021-07-09 16:26:00
  * Author: 3urobeat
  *
- * Last Modified: 2025-01-11 16:48:21
+ * Last Modified: 2025-01-12 15:32:12
  * Modified By: 3urobeat
  *
  * Copyright (c) 2021 - 2025 3urobeat <https://github.com/3urobeat>
@@ -24,6 +24,11 @@ const { EventEmitter } = require("events");
  * @type {import("../bot/bot.js")}
  */
 
+/**
+ * @typedef EIdTypes
+ * @type {import("./helpers/handleSteamIdResolving.js")}
+ */
+
 
 /**
  * Constructor - Initializes the controller and starts all bot accounts
@@ -34,7 +39,7 @@ const Controller = function() {
 
     /**
      * Stores references to all bot account objects mapped to their accountName
-     * @type {{[key: string]: Bot}}
+     * @type {Object.<string, Bot>}
      */
     this.bots = {};
 
@@ -49,62 +54,14 @@ const Controller = function() {
 
     /**
      * Collection of miscellaneous functions for easier access
+     * @type {import("./helpers/misc.js")}
      */
-    this.misc = {
-        /**
-         * Implementation of a synchronous for loop in JS (Used as reference: https://whitfin.io/handling-synchronous-asynchronous-loops-javascriptnode-js/)
-         * @param {number} iterations The amount of iterations
-         * @param {function(object, number): void} func The function to run each iteration (Params: loop, index)
-         * @param {function(): void} exit This function will be called when the loop is finished
-         */
-        syncLoop: (iterations, func, exit) => {}, // eslint-disable-line
-
-        /**
-         * Rounds a number with x decimals
-         * @param {number} value Number to round
-         * @param {number} decimals Amount of decimals
-         * @returns {number} Rounded number
-         */
-        round: (value, decimals) => {}, // eslint-disable-line
-
-        /**
-         * Converts a timestamp to a human-readable "until from now" format. Does not care about past/future.
-         * @param {number} timestamp UNIX timestamp to convert
-         * @returns {string} "x seconds/minutes/hours/days"
-         */
-        timeToString: () => {},
-
-        /**
-         * Pings a *https* URL to check if the service and this internet connection is working
-         * @param {string} url The URL of the service to check
-         * @param {boolean} [throwTimeout=false] If true, the function will throw a timeout error if Steam can't be reached after 20 seconds
-         * @param {{ ip: string, port: number, username: string, password: string }} [proxy] Provide a proxy if the connection check should be made through a proxy instead of the local connection
-         * @returns {Promise.<{ statusMessage: string, statusCode: number|null }>} Resolves on response code 2xx and rejects on any other response code. Both are called with parameter `response` (Object) which has a `statusMessage` (String) and `statusCode` (Number) key. `statusCode` is `null` if request failed.
-         */
-        checkConnection: (url, throwTimeout = false, proxy) => {}, // eslint-disable-line
-
-        /**
-         * Splits a HTTP proxy URL into its parts
-         * @param {string} url The HTTP proxy URL
-         * @returns {{ ip: string, port: number, username: string, password: string }} Object containing the proxy parts
-         */
-        splitProxyString: (url) => {}, // eslint-disable-line
-
-        /**
-         * Helper function which attempts to cut Strings intelligently and returns all parts. It will attempt to not cut words & links in half.
-         * It is used by the steamChatInteraction helper but can be used in plugins as well.
-         * @param {string} txt The string to cut
-         * @param {number} limit Maximum length for each part. The function will attempt to cut txt into parts that don't exceed this amount.
-         * @param {Array.<string>} cutChars Optional: Custom chars to search after for cutting string in parts. Default: [" ", "\n", "\r"]
-         * @param {number} threshold Optional: Maximum amount that limit can be reduced to find the last space or line break. If no match is found within this limit a word will be cut. Default: 15% of total length
-         * @returns {Array} Returns all parts of the string in an array
-         */
-        cutStringsIntelligently: (txt, limit, cutChars, threshold) => {} // eslint-disable-line
-    };
+    this.misc = {};
 
 
     /**
      * Collection of various misc parameters
+     * @type {{ bootStartTimestamp: number, lastLoginTimestamp: object, steamGuardInputTime: number, startupWarnings: number, activeLogin: boolean, relogAfterDisconnect: boolean, readyAfter: number, skippedaccounts: string[], commentCounter: number }}
      */
     this.info = {
         bootStartTimestamp: Date.now(), // Save timestamp to be able to calculate startup time in ready event
@@ -120,7 +77,7 @@ const Controller = function() {
 
     /**
      * Stores all recent comment, vote etc. requests
-     * @type {{[key: string]: { status: string, type: string, amount: number, quotesArr?: Array.<string>, requestedby: string, accounts: Array.<Bot>, thisIteration: number, retryAttempt: number, amountBeforeRetry?: number, until: number, ipCooldownPenaltyAdded?: boolean, failed: object }}}
+     * @type {Object.<string, { status: string, type: string, amount: number, quotesArr: (Array.<string>|undefined), requestedby: string, accounts: Array.<Bot>, thisIteration: number, retryAttempt: number, amountBeforeRetry: (number|undefined), until: number, ipCooldownPenaltyAdded: (boolean|undefined), failed: object }>}
      */
     this.activeRequests = {};
 };
@@ -521,7 +478,7 @@ Controller.prototype.checkLastcommentDB = function(bot) {}; // eslint-disable-li
 /**
  * Checks the remaining space on the friendlist of a bot account, sends a warning message if it is less than 10 and force unfriends oldest lastcomment db user to always keep room for 1 friend.
  * @param {Bot} bot Bot object of the account to check
- * @param {function(number|null): void} callback Called with `remaining` (Number) on success or `null` on failure
+ * @param {function(((number|null))): void} callback Called with `remaining` (Number) on success or `null` on failure
  */
 Controller.prototype.friendListCapacityCheck = function(bot, callback) {}; // eslint-disable-line
 
@@ -551,24 +508,12 @@ Controller.prototype.getBotsPerProxy = function(filterOffline = false) {}; // es
  */
 Controller.prototype._handleErrors = function() {} // eslint-disable-line
 
-/**
- * ID types supported by this resolver
- */
-const EIdTypes = { // eslint-disable-line
-    "profile": "profile",
-    "group": "group",
-    "sharedfile": "sharedfile",
-    "discussion": "discussion",
-    "curator": "curator",
-    "review": "review"
-};
-
 /**
  * Handles converting URLs to steamIDs, determining their type if unknown and checking if it matches your expectation.
  * Note: You need to provide a full URL for discussions, curators & reviews. For discussions only type checking/determination is supported.
  * @param {string} str The profileID argument provided by the user
  * @param {EIdTypes} expectedIdType The type of SteamID expected or `null` if type should be assumed.
- * @param {function(string|null, string|null, EIdTypes|null): void} callback
+ * @param {function((string|null), (string|null), (EIdTypes|null)): void} callback
  * Called with `err` (String or null), `id` (String or null), `idType` (String or null) parameters on completion. The `id` param has the format `userID/appID` for type review and full input url for type discussion.
  */
 Controller.prototype.handleSteamIdResolving = (str, expectedIdType, callback) => {} // eslint-disable-line