tiny-essentials 1.9.0 → 1.9.2

package/dist/TinyEssentials.js

@@ -2202,6 +2202,15 @@ async function asyncReplace(str, regex, asyncFn) {
 }
 
 ;// ./src/legacy/libs/userLevel.mjs
+/**
+ * Represents a user object used.
+ *
+ * @typedef {Object} UserEditor
+ * @property {number} exp - Current experience points of the user.
+ * @property {number} level - Current level of the user.
+ * @property {number} totalExp - Total accumulated experience.
+ */
+
 /**
  * Class to manage user level-up logic based on experience points.
  */
@@ -2212,26 +2221,95 @@ class TinyLevelUp {
    * @param {number} expLevel - Base experience needed to level up (per level).
    */
   constructor(giveExp, expLevel) {
+    if (typeof giveExp !== 'number' || Number.isNaN(giveExp))
+      throw new Error('giveExp must be a valid number');
+    if (typeof expLevel !== 'number' || Number.isNaN(expLevel))
+      throw new Error('expLevel must be a valid number');
     this.giveExp = giveExp;
     this.expLevel = expLevel;
   }
 
   /**
-   * @typedef {{ exp: number, level: number, totalExp: number }} UserResult
+   * Creates a new user object starting at level 0 with 0 experience.
+   * @returns {UserEditor} A fresh user object.
+   */
+  createUser() {
+    return {
+      exp: 0,
+      level: 1,
+      totalExp: 0,
+    };
+  }
+
+  /**
+   * Validates if the given user object has valid numeric properties.
+   * Throws an error if any property is invalid.
+   *
+   * @param {UserEditor} user - The user object to validate.
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
+   */
+  validateUser(user) {
+    if (typeof user.exp !== 'number' || Number.isNaN(user.exp))
+      throw new Error('exp must be a valid number');
+    if (typeof user.level !== 'number' || Number.isNaN(user.level))
+      throw new Error('level must be a valid number');
+    if (user.level < 1) throw new Error('level must be at least 1');
+    if (typeof user.totalExp !== 'number' || Number.isNaN(user.totalExp))
+      throw new Error('totalExp must be a valid number');
+  }
+
+  /**
+   * Checks if the given user object is valid by verifying its numeric properties.
+   *
+   * @param {UserEditor} user - The user object to check.
+   * @returns {boolean} `true` if all properties (exp, level, totalExp) are valid numbers; otherwise `false`.
    */
+  isValidUser(user) {
+    if (typeof user.exp !== 'number' || Number.isNaN(user.exp)) return false;
+    if (typeof user.level !== 'number' || Number.isNaN(user.level)) return false;
+    if (user.level < 1) return false;
+    if (typeof user.totalExp !== 'number' || Number.isNaN(user.totalExp)) return false;
+    return true;
+  }
 
   /**
-   * @typedef {{ exp: number, level: number, totalExp: any }} UserEditor
+   * Returns the base experience value used for random experience generation.
+   * Throws an error if the internal giveExp value is not a valid number.
+   *
+   * @returns {number} The base experience value.
+   * @throws {Error} If giveExp is not a valid number.
    */
+  getGiveExpBase() {
+    if (typeof this.giveExp !== 'number' || Number.isNaN(this.giveExp))
+      throw new Error('giveExp must be a valid number');
+    return this.giveExp;
+  }
+
+  /**
+   * Returns the base experience required to level up.
+   * Throws an error if the internal expLevel value is not a valid number.
+   *
+   * @returns {number} The base experience needed per level.
+   * @throws {Error} If expLevel is not a valid number.
+   */
+  getExpLevelBase() {
+    if (typeof this.expLevel !== 'number' || Number.isNaN(this.expLevel))
+      throw new Error('expLevel must be a valid number');
+    return this.expLevel;
+  }
 
   /**
    * Validates and adjusts the user's level based on their current experience.
    * @param {UserEditor} user - The user object containing experience and level properties.
-   * @returns {UserResult} The updated user object.
+   * @returns {UserEditor} The updated user object.
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
    */
   expValidator(user) {
+    const expLevel = this.getExpLevelBase();
+    this.validateUser(user);
+
     let extraValue = 0;
-    const nextLevelExp = this.expLevel * user.level;
+    const nextLevelExp = expLevel * user.level;
 
     // Level Up
     if (user.exp >= nextLevelExp) {
@@ -2246,7 +2324,7 @@ class TinyLevelUp {
     if (user.exp < 1 && user.level > 1) {
       user.level--;
       extraValue = Math.abs(user.exp);
-      user.exp = this.expLevel * user.level;
+      user.exp = expLevel * user.level;
 
       if (extraValue > 0) return this.remove(user, extraValue, 'extra');
     }
@@ -2256,12 +2334,14 @@ class TinyLevelUp {
 
   /**
    * Calculates the total experience based on the user's level.
-   * @param {{ exp: number, level: number }} user - The user object containing experience and level properties.
+   * @param {UserEditor} user - The user object containing experience and level properties.
    * @returns {number} The total experience of the user.
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
    */
   getTotalExp(user) {
+    this.validateUser(user);
     let totalExp = 0;
-    for (let p = 1; p <= user.level; p++) totalExp += this.expLevel * p;
+    for (let p = 1; p <= user.level; p++) totalExp += this.getExpLevelBase() * p;
     totalExp += user.exp;
     return totalExp;
   }
@@ -2272,34 +2352,52 @@ class TinyLevelUp {
    * @returns {number} The generated experience points.
    */
   expGenerator(multi = 1) {
-    return Math.floor(Math.random() * this.giveExp) + 1 * multi;
+    if (typeof multi !== 'number' || Number.isNaN(multi))
+      throw new Error('multi must be a valid number');
+    return Math.floor(Math.random() * this.getGiveExpBase()) * multi;
+  }
+
+  /**
+   * Calculates how much experience is missing to next level.
+   * @param {UserEditor} user
+   * @returns {number}
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
+   */
+  getMissingExp(user) {
+    return this.getProgress(user) - user.exp;
   }
 
   /**
    * Gets the experience points required to reach the next level.
-   * @param {{ level: number }} user - The user object containing the level.
+   * @param {UserEditor} user - The user object containing the level.
    * @returns {number} The experience required for the next level.
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
    */
   progress(user) {
-    return this.expLevel * user.level;
+    return this.getProgress(user);
   }
 
   /**
    * Gets the experience points required to reach the next level.
-   * @param {{ level: number }} user - The user object containing the level.
+   * @param {UserEditor} user - The user object containing the level.
    * @returns {number} The experience required for the next level.
+   * @throws {Error} If any property (exp, level, totalExp) is not a valid number.
    */
   getProgress(user) {
-    return this.expLevel * user.level;
+    this.validateUser(user);
+    return this.getExpLevelBase() * user.level;
   }
 
   /**
    * Sets the experience value for the user, adjusting their level if necessary.
    * @param {UserEditor} user - The user object.
    * @param {number} value - The new experience value to set.
-   * @returns {UserResult} The updated user object.
+   * @returns {UserEditor} The updated user object.
    */
   set(user, value) {
+    if (typeof value !== 'number' || Number.isNaN(value))
+      throw new Error('value must be a valid number');
+
     user.exp = value;
     this.expValidator(user);
     user.totalExp = this.getTotalExp(user);
@@ -2312,9 +2410,15 @@ class TinyLevelUp {
    * @param {number} [extraExp] - Additional experience to be added.
    * @param {'add' | 'extra'} [type] - Type of addition ('add' or 'extra').
    * @param {number} [multi] - Multiplier for experience generation.
-   * @returns {UserResult} The updated user object.
+   * @returns {UserEditor} The updated user object.
    */
   give(user, extraExp = 0, type = 'add', multi = 1) {
+    if (typeof multi !== 'number' || Number.isNaN(multi))
+      throw new Error('multi must be a valid number');
+    if (typeof extraExp !== 'number' || Number.isNaN(extraExp))
+      throw new Error('extraExp must be a valid number');
+    if (typeof type !== 'string') throw new Error('type must be a valid string');
+
     if (type === 'add') user.exp += this.expGenerator(multi) + extraExp;
     else if (type === 'extra') user.exp += extraExp;
 
@@ -2329,9 +2433,15 @@ class TinyLevelUp {
    * @param {number} [extraExp] - Additional experience to remove.
    * @param {'add' | 'extra'} [type] - Type of removal ('add' or 'extra').
    * @param {number} [multi] - Multiplier for experience generation.
-   * @returns {UserResult} The updated user object.
+   * @returns {UserEditor} The updated user object.
    */
   remove(user, extraExp = 0, type = 'add', multi = 1) {
+    if (typeof multi !== 'number' || Number.isNaN(multi))
+      throw new Error('multi must be a valid number');
+    if (typeof extraExp !== 'number' || Number.isNaN(extraExp))
+      throw new Error('extraExp must be a valid number');
+    if (typeof type !== 'string') throw new Error('type must be a valid string');
+
     if (type === 'add') user.exp -= this.expGenerator(multi) + extraExp;
     else if (type === 'extra') user.exp -= extraExp;
 
@@ -2617,6 +2727,8 @@ var buffer = __webpack_require__(287);
 ;// ./src/v1/basics/objFilter.mjs
 
 
+const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+
 /**
  * An object containing type validation functions and their evaluation order.
  *
@@ -2626,111 +2738,27 @@ var buffer = __webpack_require__(287);
  * The `order` array defines the priority in which types should be checked,
  * which can be useful for functions that infer types in a consistent manner.
  *
- * @typedef {Object} TypeValidator
- * @property {Object.<string, (val: any) => boolean>} items - A dictionary of type validation functions.
- * @property {string[]} order - The order in which types should be evaluated.
- */
-
-/**
- * Validates values against specific types using predefined functions.
- *
- * @type {TypeValidator}
  */
 const typeValidator = {
-  items: {
-    /** @param {*} val @returns {val is undefined} */
-    undefined: (val) => typeof val === 'undefined',
-
-    /** @param {*} val @returns {val is null} */
-    null: (val) => val === null,
-
-    /** @param {*} val @returns {val is boolean} */
-    boolean: (val) => typeof val === 'boolean',
-
-    /** @param {*} val @returns {val is number} */
-    number: (val) => typeof val === 'number' && !isNaN(val),
-
-    /** @param {*} val @returns {val is bigint} */
-    bigint: (val) => typeof val === 'bigint',
-
-    /** @param {*} val @returns {val is string} */
-    string: (val) => typeof val === 'string',
-
-    /** @param {*} val @returns {val is symbol} */
-    symbol: (val) => typeof val === 'symbol',
-
-    /** @param {*} val @returns {val is Function} */
-    function: (val) => typeof val === 'function',
-
-    /** @param {*} val @returns {val is Array} */
-    array: (val) => Array.isArray(val),
-
-    /** @param {*} val @returns {val is Date} */
-    date: (val) => val instanceof Date,
-
-    /** @param {*} val @returns {val is RegExp} */
-    regexp: (val) => val instanceof RegExp,
-
-    /** @param {*} val @returns {val is Map} */
-    map: (val) => val instanceof Map,
-
-    /** @param {*} val @returns {val is Set} */
-    set: (val) => val instanceof Set,
-
-    /** @param {*} val @returns {val is WeakMap} */
-    weakmap: (val) => val instanceof WeakMap,
-
-    /** @param {*} val @returns {val is WeakSet} */
-    weakset: (val) => val instanceof WeakSet,
-
-    /** @param {*} val @returns {val is Promise} */
-    promise: (val) => val instanceof Promise,
-
-    /** @param {*} val @returns {val is Buffer} */
-    buffer: (val) => typeof buffer/* Buffer */.hp !== 'undefined' && buffer/* Buffer */.hp.isBuffer(val),
-
-    /** @param {*} val @returns {val is File} */
-    file: (val) => typeof File !== 'undefined' && val instanceof File,
-
-    /** @param {*} val @returns {val is HTMLElement} */
-    htmlelement: (val) => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement,
-
-    /** @param {*} val @returns {val is object} */
-    object: (val) => typeof val === 'object' && val !== null && !Array.isArray(val),
-  },
-
-  /** Evaluation order of the type checkers. */
-  order: [
-    'undefined',
-    'null',
-    'boolean',
-    'number',
-    'bigint',
-    'string',
-    'symbol',
-    'function',
-    'array',
-    'buffer',
-    'file',
-    'date',
-    'regexp',
-    'map',
-    'set',
-    'weakmap',
-    'weakset',
-    'promise',
-    'htmlelement',
-    'object',
-  ],
+  items: {},
+  /**
+   * Evaluation order of the type checkers.
+   * @type {string[]}
+   * */
+  order: [],
 };
 
+/** @typedef {Object.<string, (val: any) => *>} ExtendObjType */
+/** @typedef {Array<[string, (val: any) => *]>} ExtendObjTypeArray */
+
 /**
  * Adds new type checkers to the typeValidator without overwriting existing ones.
  *
- * Optionally, you can specify the index at which the new type should be inserted in the order.
+ * Accepts either an object with named functions or an array of [key, fn] arrays.
  * If no index is provided, the type is inserted just before 'object' (if it exists), or at the end.
  *
- * @param {Object.<string, (val: any) => boolean>} newItems - New type validators to be added.
+ * @param {ExtendObjType|ExtendObjTypeArray} newItems
+ *        - New type validators to be added.
  * @param {number} [index] - Optional. Position at which to insert each new type. Ignored if the type already exists.
  * @returns {string[]} - A list of successfully added type names.
  *
@@ -2738,12 +2766,20 @@ const typeValidator = {
  * extendObjType({
  *   htmlElement2: val => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement
  * });
+ *
+ * @example
+ * extendObjType([
+ *   ['alpha', val => typeof val === 'string'],
+ *   ['beta', val => Array.isArray(val)]
+ * ]);
  */
 function extendObjType(newItems, index) {
   const added = [];
 
-  for (const [key, fn] of Object.entries(newItems)) {
+  const entries = Array.isArray(newItems) ? newItems : Object.entries(newItems);
+  for (const [key, fn] of entries) {
     if (!typeValidator.items.hasOwnProperty(key)) {
+      // @ts-ignore
       typeValidator.items[key] = fn;
 
       let insertAt = typeof index === 'number' ? index : -1; // Default to -1 if index isn't provided
@@ -2821,9 +2857,12 @@ function cloneObjTypeOrder() {
  */
 const getType = (val) => {
   if (val === null) return 'null';
-  for (const name of typeValidator.order)
+  // @ts-ignore
+  for (const name of typeValidator.order) {
+    // @ts-ignore
     if (typeof typeValidator.items[name] !== 'function' || typeValidator.items[name](val))
       return name;
+  }
   return 'unknown';
 };
 
@@ -2858,7 +2897,9 @@ function checkObj(obj) {
   /** @type {{ valid:*; type: string | null }} */
   const data = { valid: null, type: null };
   for (const name of typeValidator.order) {
+    // @ts-ignore
     if (typeof typeValidator.items[name] === 'function') {
+      // @ts-ignore
       const result = typeValidator.items[name](obj);
       if (result) {
         data.valid = result;
@@ -2898,6 +2939,132 @@ function countObj(obj) {
   return 0;
 }
 
+// Insert obj types
+
+extendObjType([
+  [
+    'undefined',
+    /** @param {*} val @returns {val is undefined} */
+    (val) => typeof val === 'undefined',
+  ],
+  [
+    'null',
+    /** @param {*} val @returns {val is null} */
+    (val) => val === null,
+  ],
+  [
+    'boolean',
+    /** @param {*} val @returns {val is boolean} */
+    (val) => typeof val === 'boolean',
+  ],
+  [
+    'number',
+    /** @param {*} val @returns {val is number} */
+    (val) => typeof val === 'number' && !Number.isNaN(val),
+  ],
+  [
+    'bigint',
+    /** @param {*} val @returns {val is bigint} */
+    (val) => typeof val === 'bigint',
+  ],
+  [
+    'string',
+    /** @param {*} val @returns {val is string} */
+    (val) => typeof val === 'string',
+  ],
+  [
+    'symbol',
+    /** @param {*} val @returns {val is symbol} */
+    (val) => typeof val === 'symbol',
+  ],
+  [
+    'function',
+    /** @param {*} val @returns {val is Function} */
+    (val) => typeof val === 'function',
+  ],
+  [
+    'array',
+    /** @param {*} val @returns {val is any[]} */
+    (val) => Array.isArray(val),
+  ],
+]);
+
+if (!isBrowser) {
+  extendObjType([
+    [
+      'buffer',
+      /** @param {*} val @returns {val is Buffer} */
+      (val) => typeof buffer/* Buffer */.hp !== 'undefined' && buffer/* Buffer */.hp.isBuffer(val),
+    ],
+  ]);
+}
+
+if (isBrowser) {
+  extendObjType([
+    [
+      'file',
+      /** @param {*} val @returns {val is File} */
+      (val) => typeof File !== 'undefined' && val instanceof File,
+    ],
+  ]);
+}
+
+extendObjType([
+  [
+    'date',
+    /** @param {*} val @returns {val is Date} */
+    (val) => val instanceof Date,
+  ],
+  [
+    'regexp',
+    /** @param {*} val @returns {val is RegExp} */
+    (val) => val instanceof RegExp,
+  ],
+  [
+    'map',
+    /** @param {*} val @returns {val is Map<any, any>} */
+    (val) => val instanceof Map,
+  ],
+  [
+    'set',
+    /** @param {*} val @returns {val is Set<any>} */
+    (val) => val instanceof Set,
+  ],
+  [
+    'weakmap',
+    /** @param {*} val @returns {val is WeakMap<any, any>} */
+    (val) => val instanceof WeakMap,
+  ],
+  [
+    'weakset',
+    /** @param {*} val @returns {val is WeakSet<any>} */
+    (val) => val instanceof WeakSet,
+  ],
+  [
+    'promise',
+    /** @param {*} val @returns {val is Promise<any>} */
+    (val) => val instanceof Promise,
+  ],
+]);
+
+if (isBrowser) {
+  extendObjType([
+    [
+      'htmlelement',
+      /** @param {*} val @returns {val is HTMLElement} */
+      (val) => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement,
+    ],
+  ]);
+}
+
+extendObjType([
+  [
+    'object',
+    /** @param {*} val @returns {val is object} */
+    (val) => typeof val === 'object' && val !== null && !Array.isArray(val),
+  ],
+]);
+
 ;// ./src/v1/basics/simpleMath.mjs
 /**
  * Executes a Rule of Three calculation.
@@ -3311,6 +3478,16 @@ class ColorSafeStringify {
 /* harmony default export */ const libs_ColorSafeStringify = (ColorSafeStringify);
 
 ;// ./src/v1/libs/TinyPromiseQueue.mjs
+/**
+ * @typedef {Object} QueuedTask
+ * @property {(...args: any[]) => Promise<any>|Promise<any>} task - The async task to execute.
+ * @property {(value: any) => any} resolve - The resolve function from the Promise.
+ * @property {(reason?: any) => any} reject - The reject function from the Promise.
+ * @property {string|undefined} [id] - Optional identifier for the task.
+ * @property {string|null|undefined} [marker] - Optional marker for the task.
+ * @property {number|null|undefined} [delay] - Optional delay (in ms) before the task is executed.
+ */
+
 /**
  * A queue system for managing and executing asynchronous tasks sequentially, one at a time.
  *
@@ -3320,20 +3497,10 @@ class ColorSafeStringify {
  * @class
  */
 class TinyPromiseQueue {
-  /**
-   * @typedef {Object} QueuedTask
-   * @property {(...args: any[]) => Promise<any>|Promise<any>} task - The async task to execute.
-   * @property {(value: any) => any} resolve - The resolve function from the Promise.
-   * @property {(reason?: any) => any} reject - The reject function from the Promise.
-   * @property {string|undefined} [id] - Optional identifier for the task.
-   * @property {string|null|undefined} [marker] - Optional marker for the task.
-   * @property {number|null|undefined} [delay] - Optional delay (in ms) before the task is executed.
-   */
-
-  /** @type {Array<QueuedTask>} */
+  /** @type {QueuedTask[]} */
   #queue = [];
   #running = false;
-  /** @type {Record<string, *>} */
+  /** @type {Record<string, ReturnType<typeof setTimeout>>} */
   #timeouts = {};
   /** @type {Set<string>} */
   #blacklist = new Set();
@@ -3496,8 +3663,13 @@ class TinyPromiseQueue {
    * @param {(...args: any[]) => Promise<any>|Promise<any>} task A function that returns a Promise.
    * @param {string} [id] Optional ID to identify the task in the queue.
    * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+   * @throws {Error} Throws if param is invalid.
    */
   async enqueuePoint(task, id) {
+    if (typeof task !== 'function')
+      return Promise.reject(new Error('Task must be a function returning a Promise.'));
+    if (typeof id !== 'undefined' && typeof id !== 'string')
+      throw new Error('The "id" parameter must be a string.');
     if (!this.#running) return task();
     return new Promise((resolve, reject) => {
       this.#queue.push({ marker: 'POINT_MARKER', task, resolve, reject, id });
@@ -3516,8 +3688,16 @@ class TinyPromiseQueue {
    * @param {number|null} [delay] Optional delay (in ms) before the task is executed.
    * @param {string} [id] Optional ID to identify the task in the queue.
    * @returns {Promise<any>} A Promise that resolves or rejects with the result of the task once it's processed.
+   * @throws {Error} Throws if param is invalid.
    */
   enqueue(task, delay, id) {
+    if (typeof task !== 'function')
+      return Promise.reject(new Error('Task must be a function returning a Promise.'));
+    if (typeof delay !== 'undefined' && (typeof delay !== 'number' || delay < 0))
+      return Promise.reject(new Error('Delay must be a positive number or undefined.'));
+    if (typeof id !== 'undefined' && typeof id !== 'string')
+      throw new Error('The "id" parameter must be a string.');
+
     return new Promise((resolve, reject) => {
       this.#queue.push({ task, resolve, reject, id, delay });
       this.#processQueue();
@@ -3530,9 +3710,10 @@ class TinyPromiseQueue {
    *
    * @param {string} id The ID of the task to cancel.
    * @returns {boolean} True if a delay was cancelled and the task was removed.
+   * @throws {Error} Throws if `id` is not a string.
    */
   cancelTask(id) {
-    if (!id) return false;
+    if (typeof id !== 'string') throw new Error('The "id" parameter must be a string.');
     let cancelled = false;
 
     if (id in this.#timeouts) {