tiny-essentials 1.3.2 → 1.5.0

package/docs/basics/objFilter.md

@@ -40,6 +40,39 @@ Returns:
 
 ---
 
+### 🔍 `checkObj(obj)`
+
+Checks the type of a given object and returns the validation result if a known type is detected.
+
+```js
+checkObj('hello');
+// { valid: true, type: "string" }
+
+checkObj(123);
+// { valid: true, type: "number" }
+
+checkObj(undefined);
+// { valid: true, type: "undefined" }
+
+checkObj(Symbol('sym'));
+// { valid: true, type: "symbol" }
+
+checkObj(() => {});
+// { valid: true, type: "function" }
+
+checkObj(null);
+// { valid: true, type: "null" }
+
+checkObj(Object.create(null));
+// { valid: true, type: "object" }
+```
+
+Returns:
+- `{ valid: true, type: "<type>" }` if the type is recognized
+- `{ valid: null, type: null }` if no matching type is found
+
+---
+
 ### ➕ `extendObjType(newTypes, [index])`
 
 Add your own custom types. You can optionally define where in the check order they go.

package/docs/libs/TinyLevelUp.md

@@ -0,0 +1,108 @@
+
+### TinyLevelUp 🎮
+
+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.
+
+#### Constructor 🛠️
+
+- **`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.
+
+  - `giveExp` (`number`): The base experience value used for random experience generation. 🎲
+  - `expLevel` (`number`): The base experience required to level up for each level. 📈
+
+#### Methods 🔧
+
+- **`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. ⚖️
+
+  - `user` (`UserEditor`): The user object containing `exp` (experience), `level` (current level), and `totalExp` (total experience). 👤
+  
+  - **Returns**: `UserResult` - The updated user object. 🔄
+
+- **`getTotalExp(user: { exp: number, level: number })`**  
+  Calculates the total experience based on the user's level and experience. 📊
+
+  - `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. 🎲
+
+  - `multi` (`number`): A multiplier for experience generation. Default is `1`. 💯
+
+  - **Returns**: `number` - The generated experience points. 💥
+
+- **`progress(user: { level: number })`**  
+  Gets the experience points required to reach the next level. ⏩
+
+  - `user` (`Object`): The user object containing the `level`. 👤
+
+  - **Returns**: `number` - The experience required for the next level. 📈
+
+- **`getProgress(user: { level: number })`**  
+  An alias for `progress`. Returns the experience points required to reach the next level. ⏩
+
+  - `user` (`Object`): The user object containing the `level`. 👤
+
+  - **Returns**: `number` - The experience required for the next level. 📈
+
+- **`set(user: UserEditor, value: number)`**  
+  Sets the user's experience value and adjusts their level if necessary. 📝
+
+  - `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. 🔄
+
+- **`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. ➕
+
+  - `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`. 💥
+
+  - **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. ➖
+
+  - `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**: `UserResult` - The updated user object. 🔄
+
+### Type Definitions 📚
+
+- **`UserResult`**  
+  Represents the structure of a user object after level validation. 🧑‍💻
+
+  - `exp` (`number`): The user's experience. 🎯
+  - `level` (`number`): The user's current level. 🏆
+  - `totalExp` (`number`): The user's total experience. 📊
+
+- **`UserEditor`**  
+  Represents the user object before level validation. 🔧
+
+  - `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 💡
+
+```javascript
+const user = { exp: 50, level: 1, totalExp: 50 };
+const levelUpSystem = new TinyLevelUp(100, 1000);
+
+// Add experience and check updated user stats
+levelUpSystem.give(user);
+console.log(user); // { exp: 112, level: 1, totalExp: 112 }
+```
+
+---
+
+This class can be used to manage user experience points and level-ups in any system requiring user progression logic. 🚀

package/docs/libs/TinyPromiseQueue.md

@@ -0,0 +1,126 @@
+# `TinyPromiseQueue` Documentation 🎉
+
+`TinyPromiseQueue` is a queue system designed to manage and execute asynchronous tasks in a sequential, one-at-a-time order. Tasks are executed in the order they are added to the queue, with support for optional delays ⏳, task cancellation ❌, and task reordering 🔄.
+
+---
+
+## Properties 🏠
+
+- **`#queue`**: The internal queue array that holds all the tasks.
+- **`#running`**: A flag indicating whether the queue is currently processing a task.
+- **`#timeouts`**: An object storing timeouts for scheduled delays.
+- **`#blacklist`**: A set of task IDs that should be skipped if already being processed or canceled.
+
+---
+
+## Methods 🛠️
+
+### `isRunning()` 🏃‍♀️
+
+Returns whether the queue is currently processing a task.
+
+#### Returns:
+- `boolean`: `true` if the queue is processing a task, otherwise `false`.
+
+### `getIndexById(id)` 🔍
+
+Returns the index of a task in the queue by its ID.
+
+#### Parameters:
+- `id` (`string`): The ID of the task to locate.
+
+#### Returns:
+- `number`: The index of the task in the queue, or `-1` if not found.
+
+### `getQueuedIds()` 📋
+
+Returns a list of IDs for all tasks currently in the queue.
+
+#### Returns:
+- `Array<{ index: number, id: string }>`: An array of task IDs and their corresponding indices.
+
+### `reorderQueue(fromIndex, toIndex)` 🔄
+
+Reorders a task in the queue from one index to another.
+
+#### Parameters:
+- `fromIndex` (`number`): The current index of the task to move.
+- `toIndex` (`number`): The index where the task should be placed.
+
+#### Returns:
+- `void`: This method does not return anything.
+
+### `enqueue(task, delay, id)` ⏳
+
+Adds a new async task to the queue and ensures it runs in order after previous tasks. Optionally, a delay can be added before the task is executed.
+
+If the task is canceled before execution, it will be rejected with the message:
+**"The function was canceled on TinyPromiseQueue."**
+
+#### Parameters:
+- `task` (`Function`): A function that returns a `Promise` to be executed sequentially.
+- `delay` (`number|null`): Optional delay (in ms) before the task is executed.
+- `id` (`string`): 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.
+
+### `cancelTask(id)` ❌
+
+Cancels a scheduled delay and removes the task from the queue. Adds the ID to a blacklist so the task is skipped if already being processed.
+
+#### Parameters:
+- `id` (`string`): The ID of the task to cancel.
+
+#### Returns:
+- `boolean`: `true` if a delay was cancelled and the task was removed, otherwise `false`.
+
+---
+
+## Usage Example 💻
+
+```js
+import { TinyPromiseQueue } from './TinyPromiseQueue';
+
+const queue = new TinyPromiseQueue();
+
+// Helper function to create simple tasks with logs
+function createTask(name, duration = 500) {
+  return () => new Promise((resolve) => {
+    console.log(`Started task: ${name}`);
+    setTimeout(() => {
+      console.log(`Finished task: ${name}`);
+      resolve(name);
+    }, duration);
+  });
+}
+
+// Enqueue 3 tasks
+queue.enqueue(createTask('A'), 100, 'taskA');
+queue.enqueue(createTask('B'), 0, 'taskB');
+queue.enqueue(createTask('C'), 0, 'taskC');
+
+// Wait for 50ms and cancel taskB
+setTimeout(() => {
+  const success = queue.cancelTask('taskB');
+  console.log('Canceled taskB:', success); // true if cancelled
+}, 50);
+
+// List the remaining IDs in the queue
+setTimeout(() => {
+  const ids = queue.getQueuedIds();
+  console.log('Queued IDs:', ids);
+}, 60);
+```
+
+### Explanation 🧩:
+1. **Task Creation**: Tasks are created with a name and an optional duration (in ms). The task logs its start and finish times 🕰️.
+2. **Task Execution**: Tasks are enqueued one at a time, ensuring they run in the order they were added 🔁.
+3. **Cancellation**: After 50ms, taskB is canceled, demonstrating the ability to remove a task from the queue ❌.
+4. **Remaining Tasks**: The remaining tasks in the queue are logged after 60ms 📊.
+
+---
+
+## Conclusion 🎯
+
+`TinyPromiseQueue` provides a simple and effective way to manage a sequence of asynchronous tasks. With its support for delays ⏳, task cancellation ❌, and reordering 🔄, it allows for efficient control over task execution in JavaScript.

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "tiny-essentials",
-  "version": "1.3.2",
+  "version": "1.5.0",
   "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",
     "test:js": "npx babel-node test/index.js",
-    "test:mjs": "node test/index.mjs",
     "test:cjs": "node test/index.cjs",
+    "test:mjs": "node test/index.mjs",
+    "test:mjs:promisequeue": "node test/index.mjs promiseQueue",
+    "test:mjs:objtype": "node test/index.mjs objType",
     "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/*",