tiny-essentials 1.3.2 → 1.5.0

package/dist/v1/basics/objFilter.mjs

@@ -19,45 +19,45 @@ import { Buffer } from 'buffer';
  */
 const typeValidator = {
     items: {
-        /** Checks if the value is undefined. */
+        /** @param {*} val @returns {val is undefined} */
         undefined: (val) => typeof val === 'undefined',
-        /** Checks if the value is null. */
+        /** @param {*} val @returns {val is null} */
         null: (val) => val === null,
-        /** Checks if the value is a boolean. */
+        /** @param {*} val @returns {val is boolean} */
         boolean: (val) => typeof val === 'boolean',
-        /** Checks if the value is a number. */
+        /** @param {*} val @returns {val is number} */
         number: (val) => typeof val === 'number' && !isNaN(val),
-        /** Checks if the value is a bigint. */
+        /** @param {*} val @returns {val is bigint} */
         bigint: (val) => typeof val === 'bigint',
-        /** Checks if the value is a string. */
+        /** @param {*} val @returns {val is string} */
         string: (val) => typeof val === 'string',
-        /** Checks if the value is a symbol. */
+        /** @param {*} val @returns {val is symbol} */
         symbol: (val) => typeof val === 'symbol',
-        /** Checks if the value is a function. */
+        /** @param {*} val @returns {val is Function} */
         function: (val) => typeof val === 'function',
-        /** Checks if the value is an array. */
+        /** @param {*} val @returns {val is Array<any>} */
         array: (val) => Array.isArray(val),
-        /** Checks if the value is a Date object. */
+        /** @param {*} val @returns {val is Date} */
         date: (val) => val instanceof Date,
-        /** Checks if the value is a regular expression. */
+        /** @param {*} val @returns {val is RegExp} */
         regexp: (val) => val instanceof RegExp,
-        /** Checks if the value is a Map. */
+        /** @param {*} val @returns {val is Map<any, any>} */
         map: (val) => val instanceof Map,
-        /** Checks if the value is a Set. */
+        /** @param {*} val @returns {val is Set<any>} */
         set: (val) => val instanceof Set,
-        /** Checks if the value is a WeakMap. */
+        /** @param {*} val @returns {val is WeakMap<object, any>} */
         weakmap: (val) => val instanceof WeakMap,
-        /** Checks if the value is a WeakSet. */
+        /** @param {*} val @returns {val is WeakSet<object>} */
         weakset: (val) => val instanceof WeakSet,
-        /** Checks if the value is a Promise. */
+        /** @param {*} val @returns {val is Promise<any>} */
         promise: (val) => val instanceof Promise,
-        /** Checks if the value is a Buffer. */
+        /** @param {*} val @returns {val is Buffer} */
         buffer: (val) => typeof Buffer !== 'undefined' && Buffer.isBuffer(val),
-        /** Checks if the value is a File. */
+        /** @param {*} val @returns {val is File} */
         file: (val) => typeof File !== 'undefined' && val instanceof File,
-        /** Checks if the value is a Html Element. */
+        /** @param {*} val @returns {val is HTMLElement} */
         htmlelement: (val) => typeof HTMLElement !== 'undefined' && val instanceof HTMLElement,
-        /** Checks if the value is a non-null plain object or instance of a class. */
+        /** @param {*} val @returns {val is object} */
         object: (val) => typeof val === 'object' && val !== null,
     },
     /** Evaluation order of the type checkers. */
@@ -172,7 +172,7 @@ const getType = (val) => {
     if (val === null)
         return 'null';
     for (const name of typeValidator.order)
-        if (!typeValidator.items[name] || typeValidator.items[name](val))
+        if (typeof typeValidator.items[name] !== 'function' || typeValidator.items[name](val))
             return name;
     return 'unknown';
 };
@@ -198,10 +198,31 @@ export function objType(obj, type) {
         return result === type.toLowerCase();
     return result;
 }
+/**
+ * Checks the type of a given object and returns the validation value if a known type is detected.
+ *
+ * @param {*} obj - The object to check or identify.
+ * @returns {{ valid:*; type: string | null }} - Returns the type result.
+ */
+export function checkObj(obj) {
+    /** @type {{ valid:*; type: string | null }} */
+    const data = { valid: null, type: null };
+    for (const name of typeValidator.order) {
+        if (typeof typeValidator.items[name] === 'function') {
+            const result = typeValidator.items[name](obj);
+            if (result) {
+                data.valid = result;
+                data.type = name;
+                break;
+            }
+        }
+    }
+    return data;
+}
 /**
  * Counts the number of elements in an array or the number of properties in an object.
  *
- * @param {*} obj - The array or object to count.
+ * @param {Array<*>|Record<string|number, any>} obj - The array or object to count.
  * @returns {number} - The count of items (array elements or object keys), or `0` if the input is neither an array nor an object.
  *
  * @example

package/dist/v1/basics/simpleMath.d.mts

@@ -52,3 +52,4 @@ export function getSimplePerc(price: number, percentage: number): number;
  * @returns {number|null} The age in years, or null if `timeData` is not provided or invalid.
  */
 export function getAge(timeData?: number | string | Date, now?: Date | null): number | null;
+//# sourceMappingURL=simpleMath.d.mts.map

package/dist/v1/basics/text.d.mts

@@ -18,3 +18,4 @@ export function toTitleCase(str: string): string;
  * @returns {string} The string converted to title case with the first letter in lowercase.
  */
 export function toTitleCaseLowerFirst(str: string): string;
+//# sourceMappingURL=text.d.mts.map

package/dist/v1/build/TinyLevelUp.d.mts

@@ -1,2 +1,3 @@
 export { TinyLevelUp };
 import TinyLevelUp from '../../legacy/libs/userLevel.mjs';
+//# sourceMappingURL=TinyLevelUp.d.mts.map

package/dist/v1/build/TinyPromiseQueue.cjs

@@ -0,0 +1,7 @@
+'use strict';
+
+var TinyPromiseQueue = require('../libs/TinyPromiseQueue.cjs');
+
+
+
+exports.TinyPromiseQueue = TinyPromiseQueue;

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

@@ -0,0 +1,3 @@
+export { TinyPromiseQueue };
+import TinyPromiseQueue from '../libs/TinyPromiseQueue.mjs';
+//# sourceMappingURL=TinyPromiseQueue.d.mts.map

package/dist/v1/build/TinyPromiseQueue.mjs

@@ -0,0 +1,2 @@
+import TinyPromiseQueue from '../libs/TinyPromiseQueue.mjs';
+export { TinyPromiseQueue };

package/dist/v1/index.cjs

@@ -7,6 +7,7 @@ var clock = require('./basics/clock.cjs');
 var objFilter = require('./basics/objFilter.cjs');
 var simpleMath = require('./basics/simpleMath.cjs');
 var text = require('./basics/text.cjs');
+var TinyPromiseQueue = require('./libs/TinyPromiseQueue.cjs');
 
 
 
@@ -17,6 +18,7 @@ exports.formatCustomTimer = clock.formatCustomTimer;
 exports.formatDayTimer = clock.formatDayTimer;
 exports.formatTimer = clock.formatTimer;
 exports.getTimeDuration = clock.getTimeDuration;
+exports.checkObj = objFilter.checkObj;
 exports.cloneObjTypeOrder = objFilter.cloneObjTypeOrder;
 exports.countObj = objFilter.countObj;
 exports.extendObjType = objFilter.extendObjType;
@@ -27,3 +29,4 @@ exports.getSimplePerc = simpleMath.getSimplePerc;
 exports.ruleOfThree = simpleMath.ruleOfThree;
 exports.toTitleCase = text.toTitleCase;
 exports.toTitleCaseLowerFirst = text.toTitleCaseLowerFirst;
+exports.TinyPromiseQueue = TinyPromiseQueue;

package/dist/v1/index.d.mts

@@ -1,8 +1,10 @@
+import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
 import { extendObjType } from './basics/objFilter.mjs';
 import { reorderObjTypeOrder } from './basics/objFilter.mjs';
 import { cloneObjTypeOrder } from './basics/objFilter.mjs';
 import { countObj } from './basics/objFilter.mjs';
+import { checkObj } from './basics/objFilter.mjs';
 import { objType } from './basics/objFilter.mjs';
 import { ruleOfThree } from './basics/simpleMath.mjs';
 import { getSimplePerc } from './basics/simpleMath.mjs';
@@ -15,4 +17,5 @@ import { getTimeDuration } from './basics/clock.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { toTitleCase } from './basics/text.mjs';
 import { toTitleCaseLowerFirst } from './basics/text.mjs';
-export { TinyLevelUp, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { TinyPromiseQueue, TinyLevelUp, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+//# sourceMappingURL=index.d.mts.map

package/dist/v1/index.mjs

@@ -2,7 +2,8 @@ import asyncReplace from '../legacy/libs/replaceAsync.mjs';
 import TinyLevelUp from '../legacy/libs/userLevel.mjs';
 import { shuffleArray } from './basics/array.mjs';
 import { formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, } from './basics/clock.mjs';
-import { countObj, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, } from './basics/objFilter.mjs';
+import { countObj, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, objType, checkObj, } from './basics/objFilter.mjs';
 import { getAge, getSimplePerc, ruleOfThree } from './basics/simpleMath.mjs';
 import { toTitleCase, toTitleCaseLowerFirst } from './basics/text.mjs';
-export { TinyLevelUp, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };
+import TinyPromiseQueue from './libs/TinyPromiseQueue.mjs';
+export { TinyPromiseQueue, TinyLevelUp, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/TinyPromiseQueue.cjs

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * A queue system for managing and executing asynchronous tasks sequentially, one at a time.
+ *
+ * Tasks can be delayed, reordered, canceled, and processed in strict order. The queue ensures that each task
+ * is executed after the previous one finishes, and any task can be skipped or canceled if needed.
+ *
+ * @class
+ */
+class TinyPromiseQueue {
+  /**
+   * @typedef {Object} QueuedTask
+   * @property {() => 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 {number|null|undefined} [delay] - Optional delay (in ms) before the task is executed.
+   */
+
+  /** @type {Array<QueuedTask>} */
+  #queue = [];
+  #running = false;
+  /** @type {Record<string, *>} */
+  #timeouts = {};
+  /** @type {Set<string>} */
+  #blacklist = new Set();
+
+  /**
+   * Returns whether the queue is currently processing a task.
+   *
+   * @returns {boolean}
+   */
+  isRunning() {
+    return this.#running;
+  }
+
+  /**
+   * Processes the next task in the queue if not already running.
+   * Ensures tasks are executed in order, one at a time.
+   *
+   * @returns {Promise<void>}
+   */
+  async #processQueue() {
+    if (this.#running || this.#queue.length === 0) return;
+    this.#running = true;
+    const data = this.#queue.shift();
+    if (
+      data &&
+      typeof data.task === 'function' &&
+      typeof data.resolve === 'function' &&
+      typeof data.reject === 'function'
+    ) {
+      const { task, resolve, reject, delay, id } = data;
+      try {
+        if (delay && id) {
+          await new Promise((resolveDelay) => {
+            const timeoutId = setTimeout(() => {
+              delete this.#timeouts[id];
+              resolveDelay(null);
+            }, delay);
+            this.#timeouts[id] = timeoutId;
+          });
+        }
+
+        if (id && this.#blacklist.has(id)) {
+          reject(new Error('The function was canceled on TinyPromiseQueue.'));
+          this.#blacklist.delete(id);
+          this.#running = false;
+          this.#processQueue();
+          return;
+        }
+
+        const result = await task();
+        resolve(result);
+      } catch (error) {
+        reject(error);
+      } finally {
+        this.#running = false;
+        this.#processQueue();
+      }
+    }
+  }
+
+  /**
+   * Returns the index of a task by its ID.
+   *
+   * @param {string} id The ID of the task to locate.
+   * @returns {number} The index of the task in the queue, or -1 if not found.
+   */
+  getIndexById(id) {
+    return this.#queue.findIndex((item) => item.id === id);
+  }
+
+  /**
+   * Returns a list of IDs for all tasks currently in the queue.
+   *
+   * @returns {{ index: number, id: string }[]} An array of task IDs currently queued.
+   */
+  getQueuedIds() {
+    // @ts-ignore
+    return this.#queue
+      .map((item, index) => ({ index, id: item.id }))
+      .filter((entry) => typeof entry.id === 'string');
+  }
+
+  /**
+   * Reorders a task in the queue from one index to another.
+   *
+   * @param {number} fromIndex The current index of the task to move.
+   * @param {number} toIndex The index where the task should be placed.
+   */
+  reorderQueue(fromIndex, toIndex) {
+    if (
+      typeof fromIndex !== 'number' ||
+      typeof toIndex !== 'number' ||
+      fromIndex < 0 ||
+      toIndex < 0 ||
+      fromIndex >= this.#queue.length ||
+      toIndex >= this.#queue.length
+    )
+      return;
+    const [item] = this.#queue.splice(fromIndex, 1);
+    this.#queue.splice(toIndex, 0, item);
+  }
+
+  /**
+   * 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."
+   *
+   * @param {(...args: any[]) => Promise<any>} task A function that returns a Promise to be executed sequentially.
+   * @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.
+   */
+  enqueue(task, delay, id) {
+    return new Promise((resolve, reject) => {
+      this.#queue.push({ task, resolve, reject, id, delay });
+      this.#processQueue();
+    });
+  }
+
+  /**
+   * 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.
+   *
+   * @param {string} id The ID of the task to cancel.
+   * @returns {boolean} True if a delay was cancelled and the task was removed.
+   */
+  cancelTask(id) {
+    if (!id) return false;
+    let cancelled = false;
+
+    if (id in this.#timeouts) {
+      clearTimeout(this.#timeouts[id]);
+      delete this.#timeouts[id];
+      cancelled = true;
+    }
+
+    const index = this.getIndexById(id);
+    if (index !== -1) {
+      this.#queue.splice(index, 1);
+      cancelled = true;
+    }
+
+    if (cancelled) this.#blacklist.add(id);
+
+    return cancelled;
+  }
+}
+
+module.exports = TinyPromiseQueue;

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

@@ -0,0 +1,63 @@
+export default TinyPromiseQueue;
+/**
+ * A queue system for managing and executing asynchronous tasks sequentially, one at a time.
+ *
+ * Tasks can be delayed, reordered, canceled, and processed in strict order. The queue ensures that each task
+ * is executed after the previous one finishes, and any task can be skipped or canceled if needed.
+ *
+ * @class
+ */
+declare class TinyPromiseQueue {
+    /**
+     * Returns whether the queue is currently processing a task.
+     *
+     * @returns {boolean}
+     */
+    isRunning(): boolean;
+    /**
+     * Returns the index of a task by its ID.
+     *
+     * @param {string} id The ID of the task to locate.
+     * @returns {number} The index of the task in the queue, or -1 if not found.
+     */
+    getIndexById(id: string): number;
+    /**
+     * Returns a list of IDs for all tasks currently in the queue.
+     *
+     * @returns {{ index: number, id: string }[]} An array of task IDs currently queued.
+     */
+    getQueuedIds(): {
+        index: number;
+        id: string;
+    }[];
+    /**
+     * Reorders a task in the queue from one index to another.
+     *
+     * @param {number} fromIndex The current index of the task to move.
+     * @param {number} toIndex The index where the task should be placed.
+     */
+    reorderQueue(fromIndex: number, toIndex: number): void;
+    /**
+     * 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."
+     *
+     * @param {(...args: any[]) => Promise<any>} task A function that returns a Promise to be executed sequentially.
+     * @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.
+     */
+    enqueue(task: (...args: any[]) => Promise<any>, delay?: number | null, id?: string): Promise<any>;
+    /**
+     * 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.
+     *
+     * @param {string} id The ID of the task to cancel.
+     * @returns {boolean} True if a delay was cancelled and the task was removed.
+     */
+    cancelTask(id: string): boolean;
+    #private;
+}
+//# sourceMappingURL=TinyPromiseQueue.d.mts.map

package/dist/v1/libs/TinyPromiseQueue.mjs

@@ -0,0 +1,159 @@
+/**
+ * A queue system for managing and executing asynchronous tasks sequentially, one at a time.
+ *
+ * Tasks can be delayed, reordered, canceled, and processed in strict order. The queue ensures that each task
+ * is executed after the previous one finishes, and any task can be skipped or canceled if needed.
+ *
+ * @class
+ */
+class TinyPromiseQueue {
+    /**
+     * @typedef {Object} QueuedTask
+     * @property {() => 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 {number|null|undefined} [delay] - Optional delay (in ms) before the task is executed.
+     */
+    /** @type {Array<QueuedTask>} */
+    #queue = [];
+    #running = false;
+    /** @type {Record<string, *>} */
+    #timeouts = {};
+    /** @type {Set<string>} */
+    #blacklist = new Set();
+    /**
+     * Returns whether the queue is currently processing a task.
+     *
+     * @returns {boolean}
+     */
+    isRunning() {
+        return this.#running;
+    }
+    /**
+     * Processes the next task in the queue if not already running.
+     * Ensures tasks are executed in order, one at a time.
+     *
+     * @returns {Promise<void>}
+     */
+    async #processQueue() {
+        if (this.#running || this.#queue.length === 0)
+            return;
+        this.#running = true;
+        const data = this.#queue.shift();
+        if (data &&
+            typeof data.task === 'function' &&
+            typeof data.resolve === 'function' &&
+            typeof data.reject === 'function') {
+            const { task, resolve, reject, delay, id } = data;
+            try {
+                if (delay && id) {
+                    await new Promise((resolveDelay) => {
+                        const timeoutId = setTimeout(() => {
+                            delete this.#timeouts[id];
+                            resolveDelay(null);
+                        }, delay);
+                        this.#timeouts[id] = timeoutId;
+                    });
+                }
+                if (id && this.#blacklist.has(id)) {
+                    reject(new Error('The function was canceled on TinyPromiseQueue.'));
+                    this.#blacklist.delete(id);
+                    this.#running = false;
+                    this.#processQueue();
+                    return;
+                }
+                const result = await task();
+                resolve(result);
+            }
+            catch (error) {
+                reject(error);
+            }
+            finally {
+                this.#running = false;
+                this.#processQueue();
+            }
+        }
+    }
+    /**
+     * Returns the index of a task by its ID.
+     *
+     * @param {string} id The ID of the task to locate.
+     * @returns {number} The index of the task in the queue, or -1 if not found.
+     */
+    getIndexById(id) {
+        return this.#queue.findIndex((item) => item.id === id);
+    }
+    /**
+     * Returns a list of IDs for all tasks currently in the queue.
+     *
+     * @returns {{ index: number, id: string }[]} An array of task IDs currently queued.
+     */
+    getQueuedIds() {
+        // @ts-ignore
+        return this.#queue
+            .map((item, index) => ({ index, id: item.id }))
+            .filter((entry) => typeof entry.id === 'string');
+    }
+    /**
+     * Reorders a task in the queue from one index to another.
+     *
+     * @param {number} fromIndex The current index of the task to move.
+     * @param {number} toIndex The index where the task should be placed.
+     */
+    reorderQueue(fromIndex, toIndex) {
+        if (typeof fromIndex !== 'number' ||
+            typeof toIndex !== 'number' ||
+            fromIndex < 0 ||
+            toIndex < 0 ||
+            fromIndex >= this.#queue.length ||
+            toIndex >= this.#queue.length)
+            return;
+        const [item] = this.#queue.splice(fromIndex, 1);
+        this.#queue.splice(toIndex, 0, item);
+    }
+    /**
+     * 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."
+     *
+     * @param {(...args: any[]) => Promise<any>} task A function that returns a Promise to be executed sequentially.
+     * @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.
+     */
+    enqueue(task, delay, id) {
+        return new Promise((resolve, reject) => {
+            this.#queue.push({ task, resolve, reject, id, delay });
+            this.#processQueue();
+        });
+    }
+    /**
+     * 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.
+     *
+     * @param {string} id The ID of the task to cancel.
+     * @returns {boolean} True if a delay was cancelled and the task was removed.
+     */
+    cancelTask(id) {
+        if (!id)
+            return false;
+        let cancelled = false;
+        if (id in this.#timeouts) {
+            clearTimeout(this.#timeouts[id]);
+            delete this.#timeouts[id];
+            cancelled = true;
+        }
+        const index = this.getIndexById(id);
+        if (index !== -1) {
+            this.#queue.splice(index, 1);
+            cancelled = true;
+        }
+        if (cancelled)
+            this.#blacklist.add(id);
+        return cancelled;
+    }
+}
+export default TinyPromiseQueue;

package/docs/README.md

@@ -17,6 +17,11 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🧠 **[objFilter.md](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
 - 🔢 **[simpleMath.md](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
 - ✍️ **[text.md](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
+- 🔄 **[asyncReplace.md](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
+
+### 2. **`libs/`**
+- 🗂️ **[TinyPromiseQueue.md](./libs/TinyPromiseQueue.md)** — A class that allows sequential execution of asynchronous tasks, supporting task delays, cancellation, and queue management.
+- 🏅 **[TinyLevelUp.md](./libs/TinyLevelUp.md)** — A class to manage user level-up logic based on experience points, providing methods for experience validation, addition, removal, and calculation.
 
 ---
 

package/docs/basics/asyncReplace.md

@@ -0,0 +1,39 @@
+## `asyncReplace(str, regex, asyncFn)` 🔄
+
+Asynchronously replaces matches in a string using a regular expression and an async function.
+
+This function performs replacements on a string, allowing each match to be asynchronously replaced by calling an asynchronous function for each match. The asynchronous function should return a replacement value for each match and will receive the same arguments as the standard `replace` callback.
+
+### Parameters:
+
+- `str` (`string`): The input string to perform replacements on.
+- `regex` (`RegExp`): The regular expression used to match substrings for replacement.
+- `asyncFn` (`Function`): An asynchronous function that returns a replacement for each match. 
+    - It receives the same arguments as the standard `replace` callback (the matched substring and the matched string's groups).
+    - The function should return a `Promise` that resolves to the replacement value for that match.
+
+### Returns:
+- `Promise<string>`: A promise that resolves to the resulting string with all async replacements applied.
+
+### Example:
+
+```javascript
+await asyncReplace("Hello @user1 and @user2!", /@\w+/g, async (mention) => {
+  return await getUserNameFromMention(mention);
+});
+```
+
+In this example, each `@user` mention is asynchronously replaced by the value returned from `getUserNameFromMention`.
+
+### Description:
+
+This function will:
+1. Use a regular expression (`regex`) to find all matches in the input string (`str`).
+2. For each match, it will invoke the provided asynchronous function (`asyncFn`), which should return the replacement value.
+3. Once all promises are resolved, it replaces the original matches in the string with the resolved values.
+
+This is useful for scenarios where you need to replace parts of a string based on dynamic data (like fetching usernames from a server for each mention in a message).
+
+### Notes:
+- The replacements are performed asynchronously, ensuring non-blocking behavior when dealing with large or external data sources.
+- The function utilizes `Promise.all` to handle multiple asynchronous operations concurrently before replacing the matches in the original string.