tiny-essentials 1.24.5 → 1.25.1

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

@@ -0,0 +1,109 @@
+export default TinyTextDiffer;
+/**
+ * Represents the result of a single text segment comparison.
+ */
+export type DiffResult = {
+    /**
+     * - The actual string content of the segment.
+     */
+    value: string;
+    /**
+     * - The status of the segment relative to the comparison.
+     */
+    type: "normal" | "added" | "deleted";
+};
+/**
+ * Represents the result of a single text segment comparison.
+ * @typedef {Object} DiffResult
+ * @property {string} value - The actual string content of the segment.
+ * @property {"normal"|"added"|"deleted"} type - The status of the segment relative to the comparison.
+ */
+/**
+ * A utility class to store a history of text strings and compute the differences
+ * between any two versions, generating a detailed diff output.
+ */
+declare class TinyTextDiffer {
+    /**
+     * Initializes a new instance of TinyTextDiffer.
+     * @param {string[]} [history=[]]
+     */
+    constructor(history?: string[]);
+    /**
+     * Overwrites the current history array, ensuring all elements are valid strings.
+     * @param {string[]} history
+     */
+    set history(history: string[]);
+    /**
+     * Retrieves a shallow copy of the current history array.
+     * @returns {string[]}
+     */
+    get history(): string[];
+    /**
+     * Gets the total number of versions currently stored in the history.
+     * @returns {number}
+     */
+    get size(): number;
+    /**
+     * Retrieves the text string at the specified index.
+     * @param {number} index
+     * @returns {string}
+     */
+    get(index: number): string;
+    /**
+     * Checks if a text string exists at the specified index.
+     * @param {number} index
+     * @returns {boolean}
+     */
+    has(index: number): boolean;
+    /**
+     * Appends a new text string to the end of the history.
+     * @param {string} text
+     * @returns {void}
+     */
+    add(text: string): void;
+    /**
+     * Removes and returns the last text string from the history.
+     * @returns {string | undefined}
+     */
+    remove(): string | undefined;
+    /**
+     * Inserts a text string at the specified index position.
+     * @param {number} index
+     * @param {string} text
+     * @returns {void}
+     */
+    addAt(index: number, text: string): void;
+    /**
+     * Removes the text string at the specified index position.
+     * @param {number} index
+     * @returns {boolean}
+     */
+    removeAt(index: number): boolean;
+    /**
+     * Empties the entire history.
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Compares multiple pairs of text strings from the history based on their indices.
+     * Each pair of indices (e.g., index1 and index2) will produce a DiffResult array.
+     * @param {...number} indexes - An even number of indices to be compared in pairs.
+     * @returns {(DiffResult[])[]} An array of DiffResult arrays for each compared pair.
+     */
+    compare(...indexes: number[]): (DiffResult[])[];
+    /**
+     * Computes the Longest Common Subsequence (LCS) to generate the diff result.
+     * @private
+     * @param {string} str1
+     * @param {string} str2
+     * @returns {DiffResult[]}
+     */
+    private _computeDiff;
+    /**
+     * Cleans up internal references and marks the instance as destroyed to prevent memory leaks.
+     * @returns {void}
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyTextDiffer.d.mts.map

package/dist/v1/libs/TinyTextDiffer.mjs

@@ -0,0 +1,255 @@
+/**
+ * Represents the result of a single text segment comparison.
+ * @typedef {Object} DiffResult
+ * @property {string} value - The actual string content of the segment.
+ * @property {"normal"|"added"|"deleted"} type - The status of the segment relative to the comparison.
+ */
+/**
+ * A utility class to store a history of text strings and compute the differences
+ * between any two versions, generating a detailed diff output.
+ */
+class TinyTextDiffer {
+    /** @type {string[]} */
+    #history = [];
+    /** @type {boolean} */
+    #destroyed = false;
+    /**
+     * Retrieves a shallow copy of the current history array.
+     * @returns {string[]}
+     */
+    get history() {
+        return [...this.#history];
+    }
+    /**
+     * Overwrites the current history array, ensuring all elements are valid strings.
+     * @param {string[]} history
+     */
+    set history(history) {
+        if (!Array.isArray(history)) {
+            throw new TypeError('History data must be provided as an array.');
+        }
+        if (!history.every((item) => typeof item === 'string')) {
+            throw new TypeError('All items in the history array must be strings.');
+        }
+        /** @type {string[]} */
+        this.#history = [...history];
+    }
+    /**
+     * Gets the total number of versions currently stored in the history.
+     * @returns {number}
+     */
+    get size() {
+        return this.#history.length;
+    }
+    /**
+     * Initializes a new instance of TinyTextDiffer.
+     * @param {string[]} [history=[]]
+     */
+    constructor(history = []) {
+        this.history = history;
+    }
+    /**
+     * @throws {Error}
+     * @returns {void}
+     */
+    #checkDestroyed() {
+        if (this.#destroyed) {
+            throw new Error('Cannot perform operations on a destroyed TinyTextDiffer instance.');
+        }
+    }
+    /**
+     * @param {any} index
+     * @throws {TypeError}
+     * @returns {void}
+     */
+    #checkIndex(index) {
+        if (typeof index !== 'number') {
+            throw new TypeError('The provided index must be a valid number.');
+        }
+    }
+    /**
+     * @param {any} text
+     * @throws {TypeError}
+     * @returns {void}
+     */
+    #checkText(text) {
+        if (typeof text !== 'string') {
+            throw new TypeError('The provided text must be a valid string.');
+        }
+    }
+    /**
+     * Retrieves the text string at the specified index.
+     * @param {number} index
+     * @returns {string}
+     */
+    get(index) {
+        this.#checkDestroyed();
+        this.#checkIndex(index);
+        if (typeof this.#history[index] === 'undefined') {
+            throw new Error(`No text version found at index ${index}.`);
+        }
+        return this.#history[index];
+    }
+    /**
+     * Checks if a text string exists at the specified index.
+     * @param {number} index
+     * @returns {boolean}
+     */
+    has(index) {
+        this.#checkDestroyed();
+        this.#checkIndex(index);
+        return typeof this.#history[index] !== 'undefined';
+    }
+    /**
+     * Appends a new text string to the end of the history.
+     * @param {string} text
+     * @returns {void}
+     */
+    add(text) {
+        this.#checkDestroyed();
+        this.#checkText(text);
+        this.#history.push(text);
+    }
+    /**
+     * Removes and returns the last text string from the history.
+     * @returns {string | undefined}
+     */
+    remove() {
+        this.#checkDestroyed();
+        return this.#history.pop();
+    }
+    /**
+     * Inserts a text string at the specified index position.
+     * @param {number} index
+     * @param {string} text
+     * @returns {void}
+     */
+    addAt(index, text) {
+        this.#checkDestroyed();
+        this.#checkIndex(index);
+        this.#checkText(text);
+        this.#history.splice(index, 0, text);
+    }
+    /**
+     * Removes the text string at the specified index position.
+     * @param {number} index
+     * @returns {boolean}
+     */
+    removeAt(index) {
+        this.#checkDestroyed();
+        this.#checkIndex(index);
+        const oldSize = this.#history.length;
+        this.#history.splice(index, 1);
+        const newSize = this.#history.length;
+        return oldSize !== newSize;
+    }
+    /**
+     * Empties the entire history.
+     * @returns {void}
+     */
+    clear() {
+        this.#checkDestroyed();
+        this.#history = [];
+    }
+    /**
+     * Compares multiple pairs of text strings from the history based on their indices.
+     * Each pair of indices (e.g., index1 and index2) will produce a DiffResult array.
+     * @param {...number} indexes - An even number of indices to be compared in pairs.
+     * @returns {(DiffResult[])[]} An array of DiffResult arrays for each compared pair.
+     */
+    compare(...indexes) {
+        this.#checkDestroyed();
+        /** @type {number} */
+        const totalIndexes = indexes.length;
+        if (totalIndexes === 0 || totalIndexes % 2 !== 0) {
+            throw new Error('The compare method requires an even number of indices to form comparison pairs.');
+        }
+        /** @type {(DiffResult[])[]} */
+        const results = [];
+        for (let i = 0; i < totalIndexes; i += 2) {
+            const i2 = i + 1;
+            if (i2 > totalIndexes - 1)
+                continue;
+            this.#checkIndex(indexes[i]);
+            this.#checkIndex(indexes[i2]);
+            /** @type {string} */
+            const str1 = this.#history[indexes[i]];
+            /** @type {string} */
+            const str2 = this.#history[indexes[i2]];
+            results.push(this._computeDiff(str1, str2));
+        }
+        return results;
+    }
+    /**
+     * Computes the Longest Common Subsequence (LCS) to generate the diff result.
+     * @private
+     * @param {string} str1
+     * @param {string} str2
+     * @returns {DiffResult[]}
+     */
+    _computeDiff(str1, str2) {
+        /** @type {number} */
+        const len1 = str1.length;
+        /** @type {number} */
+        const len2 = str2.length;
+        /** @type {number[][]} */
+        const matrix = Array(len1 + 1)
+            .fill(null)
+            .map(() => Array(len2 + 1).fill(0));
+        /** @type {number} */
+        let i = 1;
+        /** @type {number} */
+        let j = 1;
+        for (i = 1; i <= len1; i++) {
+            for (j = 1; j <= len2; j++) {
+                if (str1[i - 1] === str2[j - 1]) {
+                    matrix[i][j] = matrix[i - 1][j - 1] + 1;
+                }
+                else {
+                    matrix[i][j] = Math.max(matrix[i - 1][j], matrix[i][j - 1]);
+                }
+            }
+        }
+        i = len1;
+        j = len2;
+        /** @type {DiffResult[]} */
+        const result = [];
+        while (i > 0 || j > 0) {
+            if (i > 0 && j > 0 && str1[i - 1] === str2[j - 1]) {
+                result.unshift({ value: str1[i - 1], type: 'normal' });
+                i--;
+                j--;
+            }
+            else if (j > 0 && (i === 0 || matrix[i][j - 1] >= matrix[i - 1][j])) {
+                result.unshift({ value: str2[j - 1], type: 'added' });
+                j--;
+            }
+            else if (i > 0 && (j === 0 || matrix[i][j - 1] < matrix[i - 1][j])) {
+                result.unshift({ value: str1[i - 1], type: 'deleted' });
+                i--;
+            }
+        }
+        return result.reduce((/** @type {DiffResult[]} */ acc, /** @type {DiffResult} */ curr) => {
+            /** @type {number} */
+            const lastIndex = acc.length - 1;
+            if (acc.length > 0 && acc[lastIndex].type === curr.type) {
+                acc[lastIndex].value += curr.value;
+            }
+            else {
+                acc.push(curr);
+            }
+            return acc;
+        }, []);
+    }
+    /**
+     * Cleans up internal references and marks the instance as destroyed to prevent memory leaks.
+     * @returns {void}
+     */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#history = [];
+        this.#destroyed = true;
+    }
+}
+export default TinyTextDiffer;

package/docs/v1/README.md

@@ -60,6 +60,8 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 👀 **[TinyElementObserver](./libs/TinyElementObserver.md)** — A DOM mutation tracking utility built on MutationObserver, with customizable detectors for handling changes, event dispatching, and lifecycle management.  
 - ⏳ **[TinyLoadingScreen](./libs/TinyLoadingScreen.md)** — A lightweight, fully-configurable loading overlay with fade-in/out animations, custom messages (string or HTMLElement), HTML rendering option, and status-change callbacks.
 - 🎨 **[TinyColorValidator](./libs/TinyColorValidator.md)** — A comprehensive CSS color validation and parsing utility supporting HEX, HEXA, RGB, RGBA, HSL, HSLA, HWB, Lab, LCH, standard HTML color names, and special keywords, with automatic type detection and parsing.
+* 📝 **[TinyTextDiffer](./libs/TinyTextDiffer.md)** — A granular text comparison utility using the LCS algorithm to detect additions, deletions, and unchanged segments between multiple history versions, returning a clean, parseable diff structure.
+* 🕒 **[TinyAnalogClock](./libs/TinyAnalogClock.md)** — A lightweight analog clock engine for managing time-based rotations, supporting custom offsets, smooth transitions, and easy binding to CSS variables rendering.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.
@@ -98,13 +100,8 @@ Feel free to suggest changes, improvements, or additional features. You can fork
 
 ## 📘 Want to Know How I Use AI in My Projects?
 
-If you're curious about how I integrate AI into my development workflow — including how I manage prompts, avoid context drift, and keep control over logic and documentation — feel free to check out the following guides:
+If you're curious about how I integrate AI into my development workflow — including how I manage prompts, avoid context drift, and keep full control over logic and documentation — all related guides have been moved to a dedicated documentation space.
 
-* [**AI Tips & Workflow**](./Ai-Tips.md)
-  Personal tips, common pitfalls to avoid, and how I keep AI assistance effective without losing my own creative and logical direction.
+✨ **Visit the Tiny-Essentials documentation hub here:**
 
-* [**Personal AI Prompts**](./Personal-Ai-Prompts.md)
-  A curated collection of my most-used AI prompts for various tasks like coding, writing, automation, and technical documentation — written in English.
-
-* [**Personal AI Prompts (Portuguese)**](./Personal-Ai-Prompts%28portuguese%29.md)
-  The same set of personal AI prompts, but fully translated into Portuguese for ease of use in native language contexts.
+👉 [https://github.com/Tiny-Essentials/.github/tree/main/docs](https://github.com/Tiny-Essentials/.github/tree/main/docs)

package/docs/v1/basics/html.md

@@ -155,6 +155,21 @@ Loads data from a remote URL using the Fetch API, with support for custom HTTP m
   * `retries` *(number)*: Number of retry attempts if the request fails. Default is `0`.
   * `headers` *(object)*: Additional headers to include in the request.
   * `body` *(object)*: Request body. If the value is a plain object, it will be automatically stringified as JSON.
+  * `onProgress` *((loaded: number, total: number) => void)*: Track the load progress.
+
+#### `trackFetchProgress(response, onProgress)`
+
+Intercepts a standard Fetch API Response to track the download progress of its body stream.
+
+* **Parameters**:
+
+  * `response` *(Response)*: The original response object to be tracked.
+  * `options` *(FetchOnProgressResult)*: The callback function to handle progress events (loaded and total numbers).
+
+* **Returns**:
+  `Response` — A new Response object with the tracked stream.
+
+---
 
 #### `fetchJson(url, options?)`
 
@@ -374,3 +389,57 @@ stopWatching(); // later
   transition: opacity 0.3s ease;
 }
 ```
+
+---
+
+### 📖 `loadImage(options): Promise<object>`
+
+A robust, asynchronous utility for loading images in the browser. It captures critical lifecycle events and provides a normalized result object, making it much easier to handle image loading states and performance metrics.
+
+#### ✨ Features
+
+* **Asynchronous:** Returns a clean `Promise`.
+* **Performance Tracking:** Automatically calculates the time taken to load the image.
+* **Memory Safe:** Includes a cleanup mechanism for event listeners.
+* **Normalized Output:** Returns consistent data structures for both success and edge cases.
+
+#### 📥 Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `url` | `string` | **Required** | The source URL of the image. |
+| `crossOrigin` | `string` | `'anonymous'` | The CORS policy for the request. |
+| `onLoading` | `function` | `undefined` | Callback fired when the browser starts the network request. |
+
+#### 📤 Returns
+
+The promise resolves to an object containing:
+
+* **`element`**: `HTMLImageElement` - The actual image object.
+* **`isSuccess`**: `boolean` - True if the image loaded correctly.
+* **`event`**: `Event` - The raw event captured from the browser.
+* **`status`**: `string` - `'loaded'` or `'aborted'`.
+* **`loadTimeMs`**: `number` - Total duration of the request in milliseconds.
+* **`dimensions`**: `Object` - Contains `width`, `height`, `naturalWidth`, and `naturalHeight`.
+
+#### 🧪 Example
+
+```javascript
+import { loadImage } from './html.mjs';
+
+const handleLoading = (event, startTime) => {
+  console.log('Started loading at:', startTime);
+};
+
+const result = await loadImage({
+  url: 'https://example.com/image.png',
+  onLoading: handleLoading,
+  crossOrigin: 'anonymous'
+});
+
+if (result.isSuccess) {
+  console.log(`Image loaded in ${result.loadTimeMs.toFixed(2)}ms`);
+  document.body.appendChild(result.element);
+}
+```
+> **Note:** The utility uses `performance.now()` for high-resolution timestamps, ensuring accurate performance monitoring of your assets.