tiny-essentials 1.18.0 → 1.19.0

package/dist/v1/libs/TinyTimeout.mjs

@@ -0,0 +1,179 @@
+/**
+ * A utility class to manage dynamically adjusted timeouts based on how often
+ * each unique ID is triggered. Also provides polling support for asynchronous conditions.
+ */
+class TinyTimeout {
+    /** @type {boolean} Whether this instance has been destroyed. */
+    #isDestroyed = false;
+    /** @type {boolean} Whether to allow auto-updating an ID's timeout config if `value` changes. */
+    #allowAutoConfigChange;
+    /** @type {number} The interval time (ms) used to decrement cooldown counters. */
+    #cooldownWatcherTime;
+    /** @type {NodeJS.Timeout|null} Reference to the internal cooldown interval. */
+    #cooldownWatcher = null;
+    /**
+     * Internal map that keeps track of how many times each ID has been triggered,
+     * along with the base multiplier used to calculate delays.
+     *
+     * @type {Map<string, { value: number, now: number }>}
+     */
+    #timeoutFixer = new Map();
+    /**
+     * Creates a new instance of TinyTimeout.
+     *
+     * @param {Object} [options={}] Optional configuration object.
+     * @param {number} [options.cooldownWatcherTime=5000] Interval in milliseconds for reducing `now` counters.
+     * @param {boolean} [options.allowAutoConfigChange=false] Whether to allow auto value changes for existing IDs.
+     */
+    constructor({ cooldownWatcherTime = 5000, allowAutoConfigChange = false } = {}) {
+        if (!Number.isFinite(cooldownWatcherTime) || cooldownWatcherTime <= 0)
+            throw new TypeError(`Expected 'cooldownWatcherTime' to be a positive number.`);
+        if (typeof allowAutoConfigChange !== 'boolean')
+            throw new TypeError(`Expected 'allowAutoConfigChange' to be a boolean.`);
+        this.#cooldownWatcherTime = cooldownWatcherTime;
+        this.#allowAutoConfigChange = allowAutoConfigChange;
+        this.setCooldownWatcherTime(cooldownWatcherTime);
+    }
+    /**
+     * Whether this instance has been destroyed and is no longer usable.
+     *
+     * @returns {boolean}
+     */
+    isDestroyed() {
+        return this.#isDestroyed;
+    }
+    /**
+     * Whether auto config change is enabled.
+     *
+     * @returns {boolean}
+     */
+    getAllowAutoConfigChange() {
+        return this.#allowAutoConfigChange;
+    }
+    /**
+     * Gets the interval time used for cooldown decrementing.
+     *
+     * @returns {number}
+     */
+    getCooldownWatcherTime() {
+        return this.#cooldownWatcherTime;
+    }
+    /**
+     * Sets whether to allow auto-updating an ID's timeout config if `value` changes.
+     *
+     * @param {boolean} value
+     */
+    setAllowAutoConfigChange(value) {
+        if (typeof value !== 'boolean')
+            throw new TypeError(`Expected 'value' to be a boolean.`);
+        this.#allowAutoConfigChange = value;
+    }
+    /**
+     * Sets the cooldown watcher interval time.
+     * Automatically resets the interval if it was already running.
+     *
+     * @param {number} value
+     */
+    setCooldownWatcherTime(value) {
+        if (this.#isDestroyed)
+            throw new Error('TinyTimeout has been destroyed.');
+        if (!Number.isFinite(value) || value <= 0)
+            throw new TypeError(`Expected 'value' to be a positive number.`);
+        this.#cooldownWatcherTime = value;
+        if (this.#cooldownWatcher)
+            clearInterval(this.#cooldownWatcher);
+        this.#cooldownWatcher = setInterval(() => {
+            this.#timeoutFixer.forEach((data) => {
+                if (data.now > 0)
+                    data.now--;
+            });
+        }, this.#cooldownWatcherTime);
+    }
+    /**
+     * Schedules a callback using a dynamically adjusted timeout based on usage frequency.
+     * The more often an ID is triggered, the longer the timeout becomes,
+     * scaled by the provided `value`. Optionally, the delay can be limited by `limit`.
+     *
+     * @param {string} id - A unique identifier to track timeout usage.
+     * @param {Function} callback - The function to execute after the delay.
+     * @param {number} value - Base delay multiplier in milliseconds.
+     * @param {number|null} [limit=null] - Optional maximum delay cap.
+     * @returns {number} Handle to the scheduled timeout.
+     * @throws {Error} Throws if the instance has been destroyed or arguments are invalid.
+     */
+    set(id, callback, value, limit = null) {
+        if (this.#isDestroyed)
+            throw new Error('TinyTimeout has been destroyed.');
+        if (typeof id !== 'string' || id.trim() === '')
+            throw new TypeError(`Expected 'id' to be a non-empty string.`);
+        if (typeof callback !== 'function')
+            throw new TypeError(`Expected 'callback' to be a function.`);
+        if (!Number.isFinite(value) || value < 0)
+            throw new TypeError(`Expected 'value' to be a non-negative number.`);
+        if (limit !== null && (!Number.isFinite(limit) || limit < 0))
+            throw new TypeError(`Expected 'limit' to be null or a non-negative number.`);
+        let entry = this.#timeoutFixer.get(id);
+        if (!entry || (this.#allowAutoConfigChange && value !== entry.value)) {
+            entry = { value, now: 0 };
+            this.#timeoutFixer.set(id, entry);
+        }
+        const delay = entry.value * entry.now;
+        entry.now++;
+        return setTimeout(callback, typeof limit === 'number' ? Math.min(delay, limit) : delay);
+    }
+    /**
+     * Waits until a provided function returns `true`, checking repeatedly at the defined interval.
+     * Useful for polling asynchronous conditions.
+     *
+     * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+     * @param {number} [checkInterval=100] - How often (in ms) to check the condition.
+     * @returns {Promise<void>} Resolves when the condition is met.
+     * @throws {TypeError} If arguments are invalid.
+     */
+    static waitForTrue(getValue, checkInterval = 100) {
+        if (typeof getValue !== 'function')
+            throw new TypeError(`Expected 'getValue' to be a function.`);
+        if (!Number.isFinite(checkInterval) || checkInterval <= 0)
+            throw new TypeError(`Expected 'checkInterval' to be a positive number.`);
+        return new Promise((resolve) => {
+            const interval = setInterval(() => {
+                if (getValue()) {
+                    clearInterval(interval);
+                    resolve();
+                }
+            }, checkInterval);
+        });
+    }
+    /**
+     * Instance version of `waitForTrue`, which defaults to using the instance's
+     * cooldownWatcherTime if not explicitly provided.
+     *
+     * @param {() => boolean} getValue - A function that returns `true` when the condition is met.
+     * @param {number|null} [checkInterval=100] - How often (in ms) to check the condition.
+     * @returns {Promise<void>} Resolves when the condition is met.
+     * @throws {Error} If the instance is destroyed or arguments are invalid.
+     */
+    waitForTrue(getValue, checkInterval = 100) {
+        if (this.#isDestroyed)
+            throw new Error('TinyTimeout has been destroyed.');
+        if (typeof getValue !== 'function')
+            throw new TypeError(`Expected 'getValue' to be a function.`);
+        if (checkInterval !== null && (!Number.isFinite(checkInterval) || checkInterval <= 0))
+            throw new TypeError(`Expected 'checkInterval' to be null or a positive number.`);
+        return TinyTimeout.waitForTrue(getValue, checkInterval ?? this.#cooldownWatcherTime);
+    }
+    /**
+     * Cleans up all internal references and stops the cooldown watcher.
+     * After calling this, the instance becomes unusable.
+     */
+    destroy() {
+        if (this.#isDestroyed)
+            return;
+        this.#isDestroyed = true;
+        if (this.#cooldownWatcher)
+            clearInterval(this.#cooldownWatcher);
+        this.#cooldownWatcher = null;
+        this.#timeoutFixer.clear();
+    }
+}
+export default TinyTimeout;

package/dist/v1/libs/TinyUploadClicker.cjs

@@ -1,10 +1,12 @@
 'use strict';
 
-var objFilter = require('../basics/objFilter.cjs');
+require('../basics/objFilter.cjs');
+var objChecker = require('../basics/objChecker.cjs');
 require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');
+require('./TinyLocalStorage.cjs');
 
 /**
  * @typedef {Object} UploaderConfig
@@ -79,7 +81,7 @@ class TinyUploadClicker {
    * @throws {TypeError} If the config is invalid or required options are missing.
    */
   constructor(options) {
-    if (!objFilter.isJsonObject(options))
+    if (!objChecker.isJsonObject(options))
       throw new TypeError('TinyUploadClicker: "options" must be a valid object.');
 
     this.#config = {
@@ -145,10 +147,10 @@ class TinyUploadClicker {
     )
       throw new TypeError('TinyUploadClicker: "onFileLoad" must be a function or null.');
 
-    if (options.inputAttributes !== undefined && !objFilter.isJsonObject(options.inputAttributes))
+    if (options.inputAttributes !== undefined && !objChecker.isJsonObject(options.inputAttributes))
       throw new TypeError('TinyUploadClicker: "inputAttributes" must be an object.');
 
-    if (options.inputStyles !== undefined && !objFilter.isJsonObject(options.inputStyles))
+    if (options.inputStyles !== undefined && !objChecker.isJsonObject(options.inputStyles))
       throw new TypeError('TinyUploadClicker: "inputStyles" must be an object.');
 
     this.#boundClick = this.#handleClick.bind(this);

package/docs/v1/README.md

@@ -15,6 +15,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📦 **[Array](./basics/array.md)** — A tiny utility for shuffling arrays using the Fisher–Yates algorithm.
 - ⏰ **[Clock](./basics/clock.md)** — A versatile time utility module for calculating and formatting time durations.
 - 🧠 **[ObjFilter](./basics/objFilter.md)** — Type detection, extension, and analysis made easy with simple and extensible type validation.
+* 🧮 **[objChecker](./basics/objChecker.md)** — Utilities for counting keys in objects or arrays and for safely detecting plain JSON-compatible objects.
 - 🔢 **[SimpleMath](./basics/simpleMath.md)** — A collection of simple math utilities for calculations like the Rule of Three and percentages.
 - ✍️ **[Text](./basics/text.md)** — A utility for transforming text into title case formats, with multiple options for capitalization.
 - 🔄 **[AsyncReplace](./basics/asyncReplace.md)** — Asynchronously replaces matches in a string using a regex and an async function.
@@ -39,6 +40,10 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 📋 **[TinyClipboard](./libs/TinyClipboard.md)** — A clipboard management utility with support for modern APIs, legacy fallbacks, and custom copy handlers for text and blobs, plus flexible read operations and clipboard item filtering.
 - 🍮 **[UltraRandomMsgGen](./libs/UltraRandomMsgGen.md)** — A whimsical random message generator using grammar templates, word sets, emojis, and chaotic modes to craft playful text outputs.
 - ✍️ **[TinyTextRangeEditor](./libs/TinyTextRangeEditor.md)** — An flexible text range manipulation utility for `input` and `textarea` elements. Supports selection, cursor control, tag insertion, attribute handling, inline editing, formatting, and advanced wrap/toggle logic with optional spacing auto-completion.
+- ⏳ **[TinyTimeout](./libs/TinyTimeout.md)** — A dynamic timeout and delay manager with support for usage-based throttling, delay scaling, configurable decay intervals, and asynchronous polling for conditions.
+- 🌈 **[TinyColorConverter](./libs/TinyColorConverter.md)** — A complete color conversion toolkit supporting hex, RGB(A), HSL(A), and integer formats, with smooth gradient generation, color parsing, and multi-format output conversion.
+- 📡 **[TinyEvents](./libs/TinyEvents.md)** — A lightweight and dependency-free event emitter inspired by Node.js, supporting persistent and one-time listeners, listener inspection, and max listener limits.
+- 📦 **[TinyLocalStorage](./libs/TinyLocalStorage.md)** — A tiny wrapper for `localStorage` with full support for objects, arrays, `Map`, `Set`, and typed value helpers like string, number, and boolean.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.

package/docs/v1/basics/objChecker.md

@@ -0,0 +1,47 @@
+# 🧠 objChecker.mjs
+
+## 📘 Object & Type Utilities
+
+This document introduces utility functions designed to help you safely and efficiently work with JavaScript objects and types. These helpers are particularly useful when dealing with dynamic values — especially in situations where data might be coming from APIs, user input, or JSON files.
+
+These tools are built to reduce boilerplate code and prevent common mistakes when handling unknown or loosely-typed values in JavaScript.
+
+---
+
+### 🧮 `countObj(obj)`
+
+Returns the number of elements in an array or the number of keys in an object.
+
+```js
+countObj([1, 2, 3]);       // 3
+countObj({ a: 1, b: 2 });  // 2
+countObj('hi');            // 0
+```
+
+---
+
+### 🧼 `isJsonObject(value)`
+
+Check if a value is a **plain JSON-compatible object** — meaning it's created via `{}` or `new Object()`, with a prototype of `Object.prototype`, and **not** a special object like `Date`, `Map`, `Array`, etc.
+
+```js
+isJsonObject({}); // true
+isJsonObject(Object.create({})); // true
+isJsonObject(Object.create(Object.prototype)); // true
+isJsonObject(Object.assign({}, { a: 1 })); // true
+```
+
+```js
+isJsonObject([]); // false
+isJsonObject(new Date()); // false
+isJsonObject(new Map()); // false
+isJsonObject(Object.create(null)); // false
+```
+
+🔒 This function ensures the object:
+
+* is not `null`
+* has `typeof === 'object'`
+* is **directly** inherited from `Object.prototype`
+
+Use this when you need to strictly validate a raw JSON object (like the output of `JSON.parse()` or manual object literals).

package/docs/v1/basics/objFilter.md

@@ -121,18 +121,6 @@ const currentOrder = cloneObjTypeOrder();
 
 ---
 
-### 🧮 `countObj(obj)`
-
-Returns the number of elements in an array or the number of keys in an object.
-
-```js
-countObj([1, 2, 3]);       // 3
-countObj({ a: 1, b: 2 });  // 2
-countObj('hi');            // 0
-```
-
----
-
 ## Supported Types
 
 Here’s a full list of supported type names (in their default order):
@@ -164,31 +152,3 @@ You can change this order or insert your own types with `extendObjType`.
 ### 🛠️ `getCheckObj()`
 
 This function creates a clone of the functions from the `typeValidator` object. It returns a new object where the keys are the same and the values are the cloned functions.
-
----
-
-### 🧼 `isJsonObject(value)`
-
-Check if a value is a **plain JSON-compatible object** — meaning it's created via `{}` or `new Object()`, with a prototype of `Object.prototype`, and **not** a special object like `Date`, `Map`, `Array`, etc.
-
-```js
-isJsonObject({}); // true
-isJsonObject(Object.create({})); // true
-isJsonObject(Object.create(Object.prototype)); // true
-isJsonObject(Object.assign({}, { a: 1 })); // true
-```
-
-```js
-isJsonObject([]); // false
-isJsonObject(new Date()); // false
-isJsonObject(new Map()); // false
-isJsonObject(Object.create(null)); // false
-```
-
-🔒 This function ensures the object:
-
-* is not `null`
-* has `typeof === 'object'`
-* is **directly** inherited from `Object.prototype`
-
-Use this when you need to strictly validate a raw JSON object (like the output of `JSON.parse()` or manual object literals).

package/docs/v1/libs/TinyColorConverter.md

@@ -0,0 +1,220 @@
+# 🎨 `TinyColorConverter`
+
+A JavaScript class for **color conversion and manipulation** between Hex, RGB(A), HSL(A), and integer formats. It also supports generation of color gradients and random color generation.
+
+---
+
+## 📦 Features
+
+* Convert between Hex, RGB, RGBA, HSL, HSLA, and integers
+* Parse various color input formats
+* Generate pastel or full-spectrum rainbow gradients 🌈
+* Return colors in multiple formats (strings, arrays, objects)
+* Get random colors easily!
+
+---
+
+## 🧱 Types
+
+### `RgbColor`
+
+```ts
+[number, number, number]
+```
+
+* Red, Green, Blue — integers from `0` to `255`
+
+### `RgbaColor`
+
+```ts
+[number, number, number, number]
+```
+
+* Red, Green, Blue, Alpha — all from `0` to `255`
+
+### `HslColor`
+
+```ts
+[number, number, number]
+```
+
+* Hue `0–360`, Saturation and Lightness `0–100`
+
+### `HslaColor`
+
+```ts
+[number, number, number, number]
+```
+
+* Like `HslColor`, but with alpha (0–255)
+
+### `HexColor`
+
+```ts
+string
+```
+
+* Hex string, like `#ff33aa`
+
+### `ColorTypes`
+
+```ts
+HexColor | number | RgbColor | RgbaColor
+```
+
+---
+
+## 🧪 Result Object Types
+
+### `RgbResult`
+
+```ts
+{ r: number, g: number, b: number }
+```
+
+### `RgbaResult`
+
+```ts
+{ r: number, g: number, b: number, a: number }
+```
+
+### `HexResult`
+
+```ts
+{ hex: string }
+```
+
+### `HslResult`
+
+```ts
+{ h: number, s: number, l: number }
+```
+
+---
+
+## 🎲 Random Color
+
+### `TinyColorConverter.randomColor()`
+
+Returns a completely random hex color.
+
+```ts
+const hex = TinyColorConverter.randomColor(); // #a4f23b
+```
+
+---
+
+## 🌈 Rainbow Gradient Generator
+
+All three gradient methods use sine wave patterns to generate smooth, eye-pleasing color palettes.
+
+### `TinyColorConverter.rcaRgb(len = 24, pastel = false)`
+
+Returns an array of `RgbResult` colors.
+
+### `TinyColorConverter.rcaHex(len = 24, pastel = false)`
+
+Returns an array of `HexResult` colors.
+
+### `TinyColorConverter.rcaHsl(len = 24, pastel = false)`
+
+Returns an array of `HslResult` colors.
+
+> 📌 Set `pastel: true` for lighter, more desaturated tones.
+
+---
+
+## 🛠️ Color Conversion Methods
+
+### Hex <=> Int
+
+* `hexToInt(hex): number`
+* `intToHex(int): HexColor`
+
+### Hex <=> RGBA
+
+* `hexToRgba(hex): RgbaColor`
+* `hexToRgb(hex): RgbColor`
+* `rgbToHex(r, g, b): HexColor`
+
+### Hex <=> HSL(A)
+
+* `hexToHsl(hex): HslColor`
+* `hexToHsla(hex): HslaColor`
+* `hslToHex(h, s, l): HexColor`
+
+### HSL <=> RGB(A)
+
+* `hslToRgba(h, s, l, a?): RgbaColor`
+* `hslToRgb(h, s, l, a?): RgbColor`
+* `rgbaToHsl(r, g, b, a?): HslColor`
+* `rgbaToHsla(r, g, b, a?): HslaColor`
+
+### Int <=> RGBA
+
+* `intToRgba(int): RgbaColor`
+* `rgbToInt(r, g, b): number`
+
+---
+
+## 🔄 Parsing & String Formats
+
+* `parseInput(input: ColorTypes, isHsl: boolean): RgbaColor`
+* `rgbStringToRgbaArray("rgba(...)"): RgbaColor`
+* `hslStringToRgbaArray("hsl(...)"): RgbaColor`
+
+---
+
+## 🧪 Instance API
+
+```ts
+const color = new TinyColorConverter('#ff66cc');
+```
+
+### `.setColor(input: ColorTypes)`
+
+Sets a new color and parses it internally.
+
+### `.getOriginal(): ColorTypes`
+
+Returns the original color input.
+
+### `.toRgbaArray(): RgbaColor`
+
+Returns the RGBA array.
+
+### `.toHex(): HexColor`
+
+Returns the color as hex string.
+
+### `.toInt(): number`
+
+Returns the color as a single 24-bit integer.
+
+### `.toRgbString(): string`
+
+Returns `'rgb(r, g, b)'` format.
+
+### `.toRgbaString(): string`
+
+Returns `'rgba(r, g, b, a)'` format.
+
+### `.toHslString(): string`
+
+Returns `'hsl(h, s%, l%)'` format.
+
+### `.toHslaString(): string`
+
+Returns `'hsla(h, s%, l%, a)'` format.
+
+### `.toHslaArray(): HslaColor`
+
+Returns an array: `[h, s, l, a]`
+
+---
+
+## 🔒 Internal State (Private)
+
+* `#original` → stores the input color
+* `#rgba` → RGBA representation
+* `#checkIsHsl` → checks if array input should be interpreted as HSL