hola-server 1.0.10 → 2.0.1

package/core/number.js

@@ -1,179 +1,181 @@
+/**
+ * @fileoverview Number manipulation and mathematical utility functions.
+ * @module core/number
+ */
+
 const { has_value } = require('./validate');
 const { is_object } = require('./obj');
 
 /**
- * Parse String value to number
- * @param {String value to parse to number} str 
- * @returns 
+ * Parse string value to number, returns 0 if invalid.
+ * @param {string|number} str - Value to parse.
+ * @returns {number} Parsed number or 0.
  */
-const parse_num = function (str) {
+const parse_num = (str) => {
     const value = parseFloat(str);
     return value ? value : 0;
 };
 
 /**
- * Parse String value to fixed2 number
- * @param {String value to parse to number} str 
- * @returns 
+ * Parse string value to number with 2 decimal places.
+ * @param {string|number} str - Value to parse.
+ * @returns {number} Parsed number rounded to 2 decimal places.
  */
-const to_fixed2 = function (str) {
+const to_fixed2 = (str) => {
     const value = parse_num(str);
     return value ? parseFloat(value.toFixed(2)) : 0;
 };
 
 /**
- * Round the number to fixed 2
- * @param {number to be rounded to fixed2} num 
- * @returns 
+ * Round number to 2 decimal places.
+ * @param {number} num - Number to round.
+ * @returns {number} Rounded number.
  */
-const round_to_fixed2 = function (num) {
-    return Math.round(num * 100) / 100;
-};
+const round_to_fixed2 = (num) => Math.round(num * 100) / 100;
 
 /**
- * Generate range array, for example: range(3) = [0,1,2]
- * @param {start index} start 
- * @param {end index} end 
- * @param {stepping} step 
- * @returns 
+ * Generate range array. Example: range(3) = [0,1,2], range(1,5) = [1,2,3,4,5]
+ * @param {number} start - Start value or length if end not provided.
+ * @param {number} [end] - End value (inclusive).
+ * @param {number} [step=1] - Step increment.
+ * @returns {number[]} Array of numbers in the range.
  */
-const range = (start, end, step = 1) => end ? [...Array(Math.floor((end - start) / step) + 1)].map((_, i) => start + i * step) : Array.from({ length: start }, (_, key) => key);
+const range = (start, end, step = 1) => {
+    if (!end) return Array.from({ length: start }, (_, key) => key);
+    return [...Array(Math.floor((end - start) / step) + 1)].map((_, i) => start + i * step);
+};
 
 /**
- * Generate scale array, for example: scale(2,10) = [2,4,8]
- * @param {start index} start 
- * @param {end index} end 
- * @param {scale ratio} scale 
- * @returns 
+ * Generate scale array with exponential growth. Example: scale(2,10) = [2,4,8]
+ * @param {number} start - Start value.
+ * @param {number} end - End value.
+ * @param {number} [ratio=2] - Scale multiplier.
+ * @returns {number[]} Array of scaled numbers.
  */
-const scale = (start, end, scale = 2) => [...Array(Math.floor(Math.log(end / start) / Math.log(scale)) + 1)].map((_, i) => start * Math.pow(scale, i));
+const scale = (start, end, ratio = 2) => {
+    const length = Math.floor(Math.log(end / start) / Math.log(ratio)) + 1;
+    return [...Array(length)].map((_, i) => start * Math.pow(ratio, i));
+};
 
 /**
- * Create a space 
- * @param {min value} min 
- * @param {max value} max 
- * @returns 
+ * Create a space object representing a min-max range.
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @returns {{min: number, max: number}} Space object.
+ * @throws {Error} If min or max not provided.
  */
 const space = (min, max) => {
-    if (has_value(min) && has_value(max)) {
-        return { ["min"]: min, ["max"]: max };
-    }
-
-    throw new Error("min and max not provide for space");
-}
+    if (!has_value(min) || !has_value(max)) throw new Error("min and max not provided for space");
+    return { min, max };
+};
 
 /**
- * Check this value is space object
- * @param {value to be checked} value 
- * @returns true if it is space otherwise return false
+ * Check if value is a space object (has min and max properties).
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if value is a space object.
  */
-const is_space = (value) => {
-    return is_object(value) && has_value(value.min) && has_value(value.max);
-}
+const is_space = (value) => is_object(value) && has_value(value.min) && has_value(value.max);
 
 /**
- * check the object is integer or not
- * @param {string need to check} str 
- * @returns 
+ * Check if value is an integer.
+ * @param {*} value - Value to check.
+ * @returns {boolean} True if value is an integer.
  */
-const is_integer = (value) => {
-    const regex_pattern = /^-?[0-9]+$/;
-    return regex_pattern.test(value);
-}
+const is_integer = (value) => /^-?[0-9]+$/.test(value);
 
 /**
- * Check the object attr contains space object or not
- * @param {object need to check} obj 
- * @returns true if contains space
+ * Check if object contains any space objects as property values.
+ * @param {Object} obj - Object to check.
+ * @returns {boolean} True if any property is a space object.
  */
 const contains_space = (obj) => {
     for (const key in obj) {
-        const value = obj[key];
-        if (is_space(value)) {
-            return true;
-        }
+        if (is_space(obj[key])) return true;
     }
     return false;
-}
+};
 
 /**
- * Generate the random number
- * @param {min value} min 
- * @param {max value} max 
- * @returns 
+ * Generate random number between min and max.
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @returns {number} Random number (integer if both bounds are integers).
  */
 const random_number = (min, max) => {
     const random = Math.random() * (max - min) + min;
-    return is_integer(min) && is_integer(max) ? Math.floor(random) : to_fixed(random);
-}
+    return is_integer(min) && is_integer(max) ? Math.floor(random) : to_fixed2(random);
+};
 
 /**
- * Use LHS method to generate sample ranges
- * @param {min value} min 
- * @param {max value} max 
- * @param {sample number} n 
- * @returns 
+ * Generate Latin Hypercube Sampling ranges for a given range.
+ * @param {number} min - Minimum value.
+ * @param {number} max - Maximum value.
+ * @param {number} n - Number of samples.
+ * @returns {{min: number, max: number}[]} Array of sample ranges.
  */
 const lhs_samples = (min, max, n) => {
     const all_int = is_integer(min + "") && is_integer(max + "");
     const interval = (max - min) / n;
     const ranges = [];
+
     for (let i = 0; i < n; i++) {
         const start = i * interval + min;
-        let end = start + interval;
-        if (i == n - 1) {
-            end = max;
-        }
-
-        const min_value = start < end ? start : end;
-        const max_value = start > end ? start : end;
-
-        let obj = {};
-        if (all_int) {
-            obj = { min: Math.floor(min_value), max: Math.floor(max_value) };
-        } else {
-            obj = { min: to_fixed2(min_value), max: to_fixed2(max_value) };
-        }
-        ranges.push(obj);
+        const end = (i === n - 1) ? max : start + interval;
+        const min_val = Math.min(start, end);
+        const max_val = Math.max(start, end);
+
+        ranges.push(all_int
+            ? { min: Math.floor(min_val), max: Math.floor(max_val) }
+            : { min: to_fixed2(min_val), max: to_fixed2(max_val) }
+        );
     }
     return ranges;
-}
+};
 
 /**
- * Create an random sample object
- * @param {object } sample configuration 
- * @returns a sample object
+ * Create random sample object from configuration with arrays or space objects.
+ * @param {Object} obj - Configuration object with arrays or space values.
+ * @returns {Object} Sample object with randomly selected values.
  */
 const random_sample = (obj) => {
     const sample_obj = {};
     for (const key in obj) {
         const value = obj[key];
         if (Array.isArray(value)) {
-            const random = Math.floor(random_number(0, value.length));
-            sample_obj[key] = value[random];
+            sample_obj[key] = value[Math.floor(random_number(0, value.length))];
         } else if (is_space(value)) {
-            const random = random_number(value.min, value.max);
-            sample_obj[key] = random;
+            sample_obj[key] = random_number(value.min, value.max);
         } else {
             sample_obj[key] = value;
         }
     }
     return sample_obj;
-}
+};
 
 /**
- * Extract number from string
- * @param {contain number value} value 
- * @returns 
+ * Extract numeric value from string containing numbers.
+ * @param {string} value - String to extract number from.
+ * @returns {number} Extracted number or 0 if not found.
  */
 const extract_number = (value) => {
     const numbers = value.match(/([+\-0-9\\.]+)/g);
-    if (!numbers) {
-        return 0;
-    }
-
-    const values = numbers.map(Number).filter(v => has_value(v));
-    return values.length == 1 ? values[0] : 0;
-}
+    if (!numbers) return 0;
+    const values = numbers.map(Number).filter((v) => has_value(v));
+    return values.length === 1 ? values[0] : 0;
+};
 
-module.exports = { parse_num, extract_number, to_fixed2, round_to_fixed2, range, scale, space, is_space, contains_space, is_integer, random_number, random_sample, lhs_samples }
+module.exports = {
+    parse_num,
+    extract_number,
+    to_fixed2,
+    round_to_fixed2,
+    range,
+    scale,
+    space,
+    is_space,
+    contains_space,
+    is_integer,
+    random_number,
+    random_sample,
+    lhs_samples
+};

package/core/obj.js

@@ -1,22 +1,25 @@
 /**
- * Create a new object based on the attrs values of the object
- * @param {Object to be copied} obj 
- * @param {attributes to be copied} attrs 
- * @returns 
+ * @fileoverview Object manipulation utility functions.
+ * @module core/obj
+ */
+
+/**
+ * Create a new object by copying specified attributes from source object.
+ * @param {Object} obj - Source object to copy from.
+ * @param {string[]} attrs - Array of attribute names to copy.
+ * @returns {Object} New object containing only the specified attributes.
  */
 const copy_obj = (obj, attrs) => {
     const copied = {};
-    attrs.forEach(attr => copied[attr] = obj[attr]);
+    attrs.forEach((attr) => { copied[attr] = obj[attr]; });
     return copied;
 };
 
 /**
- * Check this is object or not
- * @param {Object to be checked} obj 
- * @returns 
+ * Check if a value is a plain object (not null, not array).
+ * @param {*} obj - Value to check.
+ * @returns {boolean} True if value is a plain object, false otherwise.
  */
-const is_object = (obj) => {
-    return typeof obj === 'object' && obj !== null && !Array.isArray(obj);
-}
+const is_object = (obj) => typeof obj === 'object' && obj !== null && !Array.isArray(obj);
 
-module.exports = { copy_obj, is_object }
+module.exports = { copy_obj, is_object };

package/core/random.js

@@ -1,9 +1,12 @@
 /**
- * 
- * @returns Random code generated based on Math
+ * @fileoverview Random generation utility functions.
+ * @module core/random
  */
-const random_code = function () {
-    return Math.floor(Math.random() * 1000000);
-};
 
-module.exports = { random_code }
+/**
+ * Generate random 6-digit code.
+ * @returns {number} Random number between 0 and 999999.
+ */
+const random_code = () => Math.floor(Math.random() * 1000000);
+
+module.exports = { random_code };

package/core/role.js

@@ -1,116 +1,108 @@
+/**
+ * @fileoverview Role-based access control utility functions.
+ * @module core/role
+ */
+
 const { get_settings } = require("../setting");
 
 /**
- * Validate the role defination in meta config
- * @param {*} role_name 
- * @returns 
+ * Find a role by name from settings.
+ * @param {string} role_name - Role name to find.
+ * @returns {Object|undefined} Role object or undefined if not found.
  */
-const validate_meta_role = (role_name) => {
+const find_role = (role_name) => {
     const settings = get_settings();
-    //there is role defined in meta but no roles config in settings
-    if (!settings.roles) {
-        return false;
-    }
-    return is_valid_role(role_name);
-}
+    return settings.roles ? settings.roles.find((role) => role.name === role_name) : undefined;
+};
 
-const is_valid_role = (role_name) => {
+/**
+ * Validate role name exists in settings configuration.
+ * @param {string} role_name - Role name to validate.
+ * @returns {boolean} True if role is valid and configured.
+ */
+const validate_meta_role = (role_name) => {
     const settings = get_settings();
-    const roles = settings.roles.filter(role => role.name == role_name);
-    return roles.length == 1;
-}
+    if (!settings.roles) return false;
+    return find_role(role_name) !== undefined;
+};
 
-const is_root_role = (role_name) => {
-    const settings = get_settings();
-    //no role defined, then there is no role limition, so treat each user as root
-    if (!settings.roles) {
-        return true;
-    }
+/**
+ * Check if role name exists in settings.
+ * @param {string} role_name - Role name to check.
+ * @returns {boolean} True if role exists.
+ */
+const is_valid_role = (role_name) => find_role(role_name) !== undefined;
 
-    if (is_valid_role(role_name)) {
-        return settings.roles.filter(role => role.name == role_name)[0].root == true;
-    } else {
-        return false;
-    }
-}
+/**
+ * Check if role has root/admin privileges.
+ * @param {string} role_name - Role name to check.
+ * @returns {boolean} True if role is root.
+ */
+const is_root_role = (role_name) => {
+    const role = find_role(role_name);
+    return role ? role.root === true : true;
+};
 
 /**
- * get user's role from user session
- * @param {request} req 
- * @returns 
+ * Get user role from session.
+ * @param {Object} req - HTTP request object.
+ * @returns {string|null} User's role or null.
  */
 const get_session_user_role = (req) => {
     const user = req && req.session ? req.session.user : null;
     return user ? user.role : null;
-}
+};
 
 /**
- * get user from user session
- * @param {*} req 
- * @returns 
+ * Get user object from session.
+ * @param {Object} req - HTTP request object.
+ * @returns {Object|null} User object or null.
  */
-const get_session_user = (req) => {
-    return req && req.session ? req.session.user : null;
-}
+const get_session_user = (req) => req && req.session ? req.session.user : null;
 
 /**
- * 
- * @param {*} req 
+ * Check if current user has root privileges.
+ * @param {Object} req - HTTP request object.
+ * @returns {boolean} True if user is root.
  */
-const is_root_user = (req) => {
-    return is_root_role(get_session_user_role(req));
-}
+const is_root_user = (req) => is_root_role(get_session_user_role(req));
 
 /**
- * Get the meta mode based on user's role
- * @param {request} req 
- * @param {meta} meta 
- * @returns 
+ * Get user's role permissions for a meta entity.
+ * @param {Object} req - HTTP request object.
+ * @param {Object} meta - Meta entity definition.
+ * @returns {[string, string]} Array of [mode, view] permissions.
  */
 const get_user_role_right = (req, meta) => {
     const settings = get_settings();
-    //no role defined in settings or no roles defined in meta, use meta mode
-    if (!settings.roles || !meta.roles) {
-        return [meta.mode, "*"];
-    }
+    if (!settings.roles || !meta.roles) return [meta.mode, "*"];
 
     const user_role = get_session_user_role(req);
-    if (!user_role) {
-        return ["", ""];
-    }
+    if (!user_role) return ["", ""];
+    if (!is_valid_role(user_role)) return ["", ""];
 
-    if (is_valid_role(user_role)) {
-        const roles = meta.roles;
-        for (let i = 0; i < roles.length; i++) {
-            const role = roles[i];
-            const role_settings = role.split(":");
-            const role_name = role_settings[0];
-            const role_mode = role_settings[1];
-            const role_view = role_settings.length == 3 ? role_settings[2] : "*";
-            if (user_role == role_name) {
-                // * stands to get the mode from meta definition
-                if (role_mode == "*") {
-                    return [meta.mode, role_view];
-                } else {
-                    return [role_mode, role_view];
-                }
-            }
+    for (const role of meta.roles) {
+        const role_settings = role.split(":");
+        const [role_name, role_mode] = role_settings;
+        const role_view = role_settings.length === 3 ? role_settings[2] : "*";
+        if (user_role === role_name) {
+            return role_mode === "*" ? [meta.mode, role_view] : [role_mode, role_view];
         }
     }
     return ["", ""];
-}
+};
 
 /**
- * Check whether the user has the mode right on the meta or not
- * @param {http request} req 
- * @param {meta defination} meta 
- * @param {meta mode} mode 
- * @param {view} view
- * @returns 
+ * Check if user has required mode permission on meta.
+ * @param {Object} req - HTTP request object.
+ * @param {Object} meta - Meta entity definition.
+ * @param {string} mode - Required mode (c/r/u/d).
+ * @param {string} view - Required view.
+ * @returns {boolean} True if user has permission.
  */
 const check_user_role = (req, meta, mode, view) => {
     const [role_mode, role_view] = get_user_role_right(req, meta);
-    return role_mode.includes(mode) && (role_view == "*" || role_view.includes(view));
-}
+    return role_mode.includes(mode) && (role_view === "*" || role_view.includes(view));
+};
 
 module.exports = { is_root_role, is_root_user, validate_meta_role, check_user_role, get_user_role_right, get_session_user };

package/core/thread.js

@@ -1,3 +1,13 @@
-const snooze = ms => new Promise(resolve => setTimeout(resolve, ms));
+/**
+ * @fileoverview Threading and async utility functions.
+ * @module core/thread
+ */
 
-module.exports = { snooze }
+/**
+ * Sleep for specified milliseconds.
+ * @param {number} ms - Milliseconds to sleep.
+ * @returns {Promise<void>} Promise that resolves after delay.
+ */
+const snooze = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+module.exports = { snooze };