tiny-essentials 1.18.1 → 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

@@ -6,6 +6,7 @@ require('./TinyHtml.cjs');
 require('fs');
 require('path');
 require('fs/promises');
+require('./TinyLocalStorage.cjs');
 
 /**
  * @typedef {Object} UploaderConfig

package/docs/v1/README.md

@@ -40,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/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

package/docs/v1/libs/TinyEvents.md

@@ -0,0 +1,199 @@
+# 📦 TinyEvents
+
+A **lightweight event emitter** class similar to Node.js's `EventEmitter`, written in modern JavaScript with no dependencies. Perfect for publish/subscribe patterns in modular apps.
+
+---
+
+## 🧠 What is TinyEvents?
+
+`TinyEvents` enables your components or modules to **subscribe to**, **emit**, and **manage custom events**.
+
+It supports:
+
+* 🔁 Persistent listeners (`on`, `appendListener`, `prependListener`)
+* 🔂 One-time listeners (`once`, `appendListenerOnce`, `prependListenerOnce`)
+* 📤 Emitting events (`emit`)
+* 🔍 Inspecting listeners (`listenerCount`, `listeners`, `onceListeners`, `allListeners`, `eventNames`)
+* 🧹 Removing listeners (`off`, `offAll`, `offAllTypes`)
+* 🚦 Controlling listener count (`setMaxListeners`, `getMaxListeners`)
+
+---
+
+## 🔧 API Reference
+
+### `on(event: string, handler: function): void`
+
+Adds a listener for the specified event.
+
+```js
+emitter.on('hello', (name) => console.log(`Hi, ${name}`));
+```
+
+---
+
+### `once(event: string, handler: function): function`
+
+Adds a one-time listener that is automatically removed after it runs once.
+
+```js
+emitter.once('data', console.log);
+```
+
+---
+
+### `appendListener(event: string, handler: function): void`
+
+Alias for `on()`.
+
+---
+
+### `appendListenerOnce(event: string, handler: function): function`
+
+Alias for `once()`.
+
+---
+
+### `prependListener(event: string, handler: function): void`
+
+Adds a listener to the **start** of the listener array (called before others).
+
+---
+
+### `prependListenerOnce(event: string, handler: function): function`
+
+Adds a one-time listener to the **start** of the listener array.
+
+---
+
+### `emit(event: string, ...payload: any[]): boolean`
+
+Calls all listeners for an event, passing any number of arguments.
+
+Returns `true` if any listeners were called, otherwise `false`.
+
+```js
+emitter.emit('greet', 'Yasmin', 21);
+```
+
+---
+
+### `off(event: string, handler: function): void`
+
+Removes a specific listener from an event.
+
+---
+
+### `offAll(event: string): void`
+
+Removes **all listeners** for a specific event.
+
+---
+
+### `offAllTypes(): void`
+
+Clears **all listeners** from **all events**.
+
+---
+
+### `listenerCount(event: string): number`
+
+Returns how many listeners are currently registered for the event.
+
+---
+
+### `listeners(event: string): function[]`
+
+Returns an array of **non-once** listener functions for an event.
+
+---
+
+### `onceListeners(event: string): function[]`
+
+Returns an array of **once-only** listener functions for an event.
+
+---
+
+### `allListeners(event: string): function[]`
+
+Returns all listeners, including wrapped `once()` functions.
+
+---
+
+### `eventNames(): string[]`
+
+Returns an array of event names that currently have listeners.
+
+---
+
+### `setMaxListeners(n: number): void`
+
+Sets the maximum allowed listeners per event. Shows a warning if exceeded.
+
+---
+
+### `getMaxListeners(): number`
+
+Returns the current max listener limit (default: 10).
+
+---
+
+### `setThrowOnMaxListeners(shouldThrow: boolean): void`
+
+Enables or disables the behavior of throwing an error when the number of listeners exceeds the maximum limit.
+
+* If `true`, the class will **throw an error** instead of just logging a warning.
+* If `false`, it will default to console warning (default behavior).
+
+#### Parameters:
+
+* `shouldThrow` *(boolean)* – Whether to throw an error when the listener limit is exceeded.
+
+---
+
+### `getThrowOnMaxListeners(): boolean`
+
+Returns whether the emitter is currently set to throw an error when the maximum number of listeners is exceeded.
+
+#### Returns:
+
+* *(boolean)* – `true` if error throwing is enabled, otherwise `false`.
+
+---
+
+## 🧪 Example
+
+```js
+import TinyEvents from './TinyEvents.js';
+
+const emitter = new TinyEvents();
+
+function greet(name) {
+  console.log(`👋 Hello, ${name}`);
+}
+
+emitter.on('greet', greet);
+emitter.emit('greet', 'Yasmin'); // "👋 Hello, Yasmin"
+emitter.off('greet', greet);
+```
+
+---
+
+## 🛡️ Type Definitions
+
+```ts
+/**
+ * A generic event listener callback function.
+ * @callback handler
+ * @param {...any} payload - Arguments passed when event is emitted.
+ * @returns {void}
+ */
+```
+
+---
+
+## ✅ Why Use It?
+
+* No dependencies
+* Fully typed (with JSDoc)
+* Inspired by Node.js EventEmitter
+* Works in browser or Node