tiny-essentials 1.9.0 → 1.9.2

package/dist/v1/libs/TinyPromiseQueue.cjs

@@ -1,5 +1,15 @@
 'use strict';
 
+/**
+ * @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.
  *
@@ -9,20 +19,10 @@
  * @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();
@@ -185,8 +185,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 });
@@ -205,8 +210,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();
@@ -219,9 +232,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) {

package/dist/v1/libs/TinyPromiseQueue.d.mts

@@ -1,4 +1,39 @@
 export default TinyPromiseQueue;
+export type QueuedTask = {
+    /**
+     * - The async task to execute.
+     */
+    task: (...args: any[]) => Promise<any> | Promise<any>;
+    /**
+     * - The resolve function from the Promise.
+     */
+    resolve: (value: any) => any;
+    /**
+     * - The reject function from the Promise.
+     */
+    reject: (reason?: any) => any;
+    /**
+     * - Optional identifier for the task.
+     */
+    id?: string | undefined;
+    /**
+     * - Optional marker for the task.
+     */
+    marker?: string | null | undefined;
+    /**
+     * - Optional delay (in ms) before the task is executed.
+     */
+    delay?: number | null | undefined;
+};
+/**
+ * @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.
  *
@@ -44,6 +79,7 @@ declare 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.
      */
     enqueuePoint(task: (...args: any[]) => Promise<any> | Promise<any>, id?: string): Promise<any>;
     /**
@@ -57,6 +93,7 @@ declare 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: (...args: any[]) => Promise<any> | Promise<any>, delay?: number | null, id?: string): Promise<any>;
     /**
@@ -65,6 +102,7 @@ declare 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: string): boolean;
     #private;

package/dist/v1/libs/TinyPromiseQueue.mjs

@@ -1,3 +1,12 @@
+/**
+ * @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.
  *
@@ -7,19 +16,10 @@
  * @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();
@@ -165,8 +165,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) => {
@@ -185,8 +190,15 @@ 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();
@@ -198,10 +210,11 @@ 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) {
             clearTimeout(this.#timeouts[id]);

package/docs/basics/objFilter.md

@@ -83,6 +83,13 @@ extendObjType({
 });
 ```
 
+```js
+extendObjType([
+  [ 'alpha', val => typeof val === 'string' ],
+  [ 'beta', val => Array.isArray(val) ]
+]);
+```
+
 This will insert `customElement` before the built-in `object` type unless a position is specified.
 
 ---

package/docs/libs/TinyLevelUp.md

@@ -1,108 +1,248 @@
+# 📚 TinyLevelUp Documentation
 
-### TinyLevelUp 🎮
+A lightweight XP-based leveling system for managing user experience and levels. Great for games, communities, or reward-based applications! 🎮✨
 
-This class manages user level-up logic based on experience points. It provides methods to handle experience points (exp) adjustments, level progression, and random experience generation.
+---
+
+## 📐 Type Definitions
+
+### `UserEditor` ✍️
 
-#### Constructor 🛠️
+Represents the structure of a user object used in the leveling system.
 
-- **`constructor(giveExp: number, expLevel: number)`**  
-  Initializes the class with the base experience value for random experience generation and the base experience required to level up.
+```ts
+{
+  exp: number;       // Current experience points of the user
+  level: number;     // Current level of the user
+  totalExp: number;  // Total accumulated experience
+}
+```
+
+---
 
-  - `giveExp` (`number`): The base experience value used for random experience generation. 🎲
-  - `expLevel` (`number`): The base experience required to level up for each level. 📈
+## 🏗️ Class: `TinyLevelUp`
 
-#### Methods 🔧
+Handles experience logic, leveling up/down, validation, and XP generation.
 
-- **`expValidator(user: UserEditor)`**  
-  Validates and adjusts the user's level based on their current experience. If the user's experience is above or below the required threshold, their level is adjusted accordingly. ⚖️
+### 🆕 Constructor
 
-  - `user` (`UserEditor`): The user object containing `exp` (experience), `level` (current level), and `totalExp` (total experience). 👤
-  
-  - **Returns**: `UserResult` - The updated user object. 🔄
+```ts
+new TinyLevelUp(giveExp: number, expLevel: number)
+```
 
-- **`getTotalExp(user: { exp: number, level: number })`**  
-  Calculates the total experience based on the user's level and experience. 📊
+* `giveExp`: Base XP value for random XP generation 🎲
+* `expLevel`: Base XP required per level up 🔺
 
-  - `user` (`Object`): The user object containing `exp` (experience) and `level` (level). 👤
-  
-  - **Returns**: `number` - The total experience of the user. 🔢
+---
 
-- **`expGenerator(multi: number = 1)`**  
-  Generates random experience points based on a configured multiplier. 🎲
+## 🧰 Methods
 
-  - `multi` (`number`): A multiplier for experience generation. Default is `1`. 💯
+### ➕ `createUser()`
 
-  - **Returns**: `number` - The generated experience points. 💥
+Creates a fresh user at level 1 with no XP.
 
-- **`progress(user: { level: number })`**  
-  Gets the experience points required to reach the next level. ⏩
+```ts
+createUser(): UserEditor
+```
 
-  - `user` (`Object`): The user object containing the `level`. 👤
+---
 
-  - **Returns**: `number` - The experience required for the next level. 📈
+### 🔎 `validateUser(user)`
 
-- **`getProgress(user: { level: number })`**  
-  An alias for `progress`. Returns the experience points required to reach the next level. ⏩
+Throws an error if the user object is malformed or contains invalid values.
 
-  - `user` (`Object`): The user object containing the `level`. 👤
+```ts
+validateUser(user: UserEditor): void
+```
 
-  - **Returns**: `number` - The experience required for the next level. 📈
+🚨 Throws if:
 
-- **`set(user: UserEditor, value: number)`**  
-  Sets the user's experience value and adjusts their level if necessary. 📝
+* `exp`, `level`, or `totalExp` are not valid numbers.
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `value` (`number`): The new experience value to set for the user. 💡
+---
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+### ✅ `isValidUser(user)`
 
-- **`give(user: UserEditor, extraExp: number = 0, type: 'add' | 'extra' = 'add', multi: number = 1)`**  
-  Adds experience to the user and adjusts their level if necessary. Experience can be added with or without a multiplier. ➕
+Checks if the given user object is valid (without throwing errors).
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `extraExp` (`number`): Additional experience to be added. 💯
-  - `type` (`'add' | 'extra'`): Type of experience addition. `'add'` adds random experience, while `'extra'` adds specified experience. 🔧
-  - `multi` (`number`): Multiplier for experience generation. Default is `1`. 💥
+```ts
+isValidUser(user: UserEditor): boolean
+```
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+---
 
-- **`remove(user: UserEditor, extraExp: number = 0, type: 'add' | 'extra' = 'add', multi: number = 1)`**  
-  Removes experience from the user and adjusts their level if necessary. Experience can be removed with or without a multiplier. ➖
+### 🎁 `getGiveExpBase()`
 
-  - `user` (`UserEditor`): The user object containing `exp`, `level`, and `totalExp`. 👤
-  - `extraExp` (`number`): Additional experience to be removed. 💣
-  - `type` (`'add' | 'extra'`): Type of experience removal. `'add'` removes random experience, while `'extra'` removes specified experience. 🔧
-  - `multi` (`number`): Multiplier for experience generation. Default is `1`. 💥
+Returns the base XP value used for generating XP.
 
-  - **Returns**: `UserResult` - The updated user object. 🔄
+```ts
+getGiveExpBase(): number
+```
 
-### Type Definitions 📚
+---
 
-- **`UserResult`**  
-  Represents the structure of a user object after level validation. 🧑‍💻
+### 🧮 `getExpLevelBase()`
 
-  - `exp` (`number`): The user's experience. 🎯
-  - `level` (`number`): The user's current level. 🏆
-  - `totalExp` (`number`): The user's total experience. 📊
+Returns the base XP required per level.
 
-- **`UserEditor`**  
-  Represents the user object before level validation. 🔧
+```ts
+getExpLevelBase(): number
+```
 
-  - `exp` (`number`): The user's experience. 🎯
-  - `level` (`number`): The user's current level. 🏆
-  - `totalExp` (`any`): The user's total experience (can be calculated using `getTotalExp`). 📊
+---
 
-### Example Usage 💡
+### ⚖️ `expValidator(user)`
 
-```javascript
-const user = { exp: 50, level: 1, totalExp: 50 };
-const levelUpSystem = new TinyLevelUp(100, 1000);
+Validates and adjusts user level based on current XP.
 
-// Add experience and check updated user stats
-levelUpSystem.give(user);
-console.log(user); // { exp: 112, level: 1, totalExp: 112 }
+```ts
+expValidator(user: UserEditor): UserEditor
 ```
 
+* Levels up/down the user if needed.
+* Applies "extra" XP appropriately.
+
 ---
 
-This class can be used to manage user experience points and level-ups in any system requiring user progression logic. 🚀
+### 📊 `getTotalExp(user)`
+
+Calculates total accumulated XP (including current level and progress).
+
+```ts
+getTotalExp(user: UserEditor): number
+```
+
+---
+
+### 🎲 `expGenerator(multi = 1)`
+
+Generates a random XP value based on the multiplier.
+
+```ts
+expGenerator(multi?: number): number
+```
+
+---
+
+### ⏩ `progress(user)`
+
+Returns XP required to reach the next level.
+
+```ts
+progress(user: UserEditor): number
+```
+
+---
+
+### 📈 `getProgress(user)`
+
+Alias for `progress()`. Returns XP needed to reach the next level.
+
+```ts
+getProgress(user: UserEditor): number
+```
+
+---
+
+### ✍️ `set(user, value)`
+
+Sets the current XP for the user and updates their level if necessary.
+
+```ts
+set(user: UserEditor, value: number): UserEditor
+```
+
+---
+
+### ⬆️ `give(user, extraExp?, type?, multi?)`
+
+Adds experience to the user and auto-levels if needed.
+
+```ts
+give(
+  user: UserEditor,
+  extraExp?: number,
+  type?: 'add' | 'extra',
+  multi?: number
+): UserEditor
+```
+
+* `type = 'add'`: Adds generated XP + extra
+* `type = 'extra'`: Adds only extra
+
+---
+
+### ⬇️ `remove(user, extraExp?, type?, multi?)`
+
+Removes experience from the user and updates their level if necessary.
+
+```ts
+remove(
+  user: UserEditor,
+  extraExp?: number,
+  type?: 'add' | 'extra',
+  multi?: number
+): UserEditor
+```
+
+* `type = 'add'`: Removes generated XP + extra
+* `type = 'extra'`: Removes only extra
+
+---
+
+### 🔍 `getMissingExp(user)`
+
+**Description:**
+Calculates how much experience is missing for the user to reach the next level.
+
+---
+
+**Parameters:**
+
+* `user` (UserEditor) — The user object containing experience and level properties.
+
+---
+
+**Returns:**
+
+* `number` — The amount of experience points still needed to level up.
+
+---
+
+**Throws:**
+
+* `Error` — If any property (`exp`, `level`, or `totalExp`) in the `user` object is not a valid number. ⚠️
+
+---
+
+**Example usage:**
+
+```js
+const missing = tinyLevelUp.getMissingExp(user);
+console.log(`You need ${missing} more XP to level up! 🚀`);
+```
+
+---
+
+## 🌟 Example Usage
+
+```js
+import TinyLevelUp from './TinyLevelUp.js';
+
+const levelSystem = new TinyLevelUp(15, 10);
+const user = levelSystem.createUser();
+
+levelSystem.give(user); // Adds random XP
+console.log(user);
+
+levelSystem.set(user, 50); // Manually set XP
+console.log(user.level);
+```
+
+---
+
+## 💬 Notes
+
+* All methods throw if invalid values are passed ❗
+* You can use `isValidUser()` for safe checks without exceptions 🛡️
+* This system is deterministic and extendable!

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
@@ -11,6 +11,7 @@
     "test:mjs:objtype": "node test/index.mjs objType",
     "test:mjs:jsoncolor": "node test/index.mjs colorStringify",
     "test:mjs:ratelimit": "node test/index.mjs rateLimit",
+    "test:mjs:levelup": "node test/index.mjs levelUp",
     "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config",
     "fix:prettier:src": "prettier --write ./src/*",
     "fix:prettier:test": "prettier --write ./test/*",