chore: add js docs

Author: BolverBlitz

lib/utils.js

@@ -41,25 +41,49 @@ const generateUrlPath = (length = 128) => {
     return result;
 }
 
+/**
+ * Get the true IP of the request, considering proxy headers and configuration.
+ * @param {Object} req - The HTTP request object.
+ * @returns {string} The determined IP address of the request.
+ */
 const warnedProxyIssues = new Set();
 
+/**
+ * Get the first value from a header, whether it's a string or an array.
+ * @param {String|Array} value - The header value(s) to process.
+ * @returns {String} The first header value.
+ */
 const firstHeaderValue = (value) => {
     if (Array.isArray(value)) return value[0];
     return value;
 }
 
+/**
+ * Get the first forwarded IP from a header value.
+ * @param {String|Array} value - The header value(s) to process.
+ * @returns {String} The first forwarded IP.
+ */
 const firstForwardedIp = (value) => {
     const header = firstHeaderValue(value);
     if (typeof header !== 'string') return header;
     return header.split(',')[0].trim();
 }
 
+/**
+ * Warns about a proxy issue only once.
+ * @param {string} key - The unique key for the warning.
+ * @param {string} message - The warning message to log.
+ */
 const warnProxyIssueOnce = (key, message) => {
     if (warnedProxyIssues.has(key)) return;
     warnedProxyIssues.add(key);
     process.log?.warn?.(message);
 }
 
+/**
+ * Get the configured proxy chain from environment variables.
+ * @returns {Array<string>} An array of configured proxy types.
+ */
 const getProxyChain = () => {
     const configuredProxy = String(process.env.PROXY || 'none')
         .toLowerCase()
@@ -82,8 +106,8 @@ const getProxyChain = () => {
 
 /**
  * Get the true IP of the request
- * @param {Object} req 
- * @returns 
+ * @param {Object} req - The HTTP request object.
+ * @returns {string} The determined IP address of the request.
  */
 const getIpOfRequest = (req) => {
     const headers = req.headers || {};