tiny-essentials 1.25.3 → 1.25.4

package/dist/v1/build/TinyArrayComparator.cjs

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

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

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

package/dist/v1/build/TinyArrayComparator.mjs

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

package/dist/v1/index.cjs

@@ -49,6 +49,7 @@ var TinyLoadingScreen = require('./libs/TinyLoadingScreen.cjs');
 var TinyColorValidator = require('./libs/TinyColorValidator.cjs');
 var TinyAnalogClock = require('./libs/TinyAnalogClock.cjs');
 var TinyTextDiffer = require('./libs/TinyTextDiffer.cjs');
+var TinyArrayComparator = require('./libs/TinyArrayComparator.cjs');
 
 
 
@@ -179,3 +180,4 @@ exports.TinyLoadingScreen = TinyLoadingScreen;
 exports.TinyColorValidator = TinyColorValidator;
 exports.TinyAnalogClock = TinyAnalogClock;
 exports.TinyTextDiffer = TinyTextDiffer;
+exports.TinyArrayComparator = TinyArrayComparator;

package/dist/v1/index.d.mts

@@ -1,3 +1,4 @@
+import TinyArrayComparator from './libs/TinyArrayComparator.mjs';
 import TinyTextDiffer from './libs/TinyTextDiffer.mjs';
 import TinyAnalogClock from './libs/TinyAnalogClock.mjs';
 import TinyColorValidator from './libs/TinyColorValidator.mjs';
@@ -125,5 +126,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 { TinyTextDiffer, TinyAnalogClock, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst };
+export { TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, 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

@@ -47,7 +47,8 @@ import TinyLoadingScreen from './libs/TinyLoadingScreen.mjs';
 import TinyColorValidator from './libs/TinyColorValidator.mjs';
 import TinyAnalogClock from './libs/TinyAnalogClock.mjs';
 import TinyTextDiffer from './libs/TinyTextDiffer.mjs';
+import TinyArrayComparator from './libs/TinyArrayComparator.mjs';
 // import TinyHtmlElems from './libs/TinyHtml/index.mjs';
-export { TinyTextDiffer, TinyAnalogClock, 
+export { TinyArrayComparator, TinyTextDiffer, TinyAnalogClock, 
 // TinyHtmlElems,
 TinyColorValidator, TinyLoadingScreen, TinyElementObserver, TinySimpleDice, TinyNeedBar, TinyI18, TinyCookieConsent, TinyInventory, TinyInventoryTrader, TinyArrayPaginator, TinyAdvancedRaffle, TinyDayNightCycle, TinyGamepad, TinyTextarea, TinyNewWinEvents, TinyIframeEvents, TinyLocalStorage, TinyEvents, TinyTimeout, TinyColorConverter, TinyClipboard, TinyTextRangeEditor, TinySmartScroller, UltraRandomMsgGen, TinyAfterScrollWatcher, TinyHtml, TinyNotifications, TinyDomReadyManager, TinyDragger, TinyDragDropDetector, TinyToastNotify, TinyNotifyCenter, TinyRateLimiter, ColorSafeStringify, TinyPromiseQueue, TinyLevelUp, diffArrayList, diffStrings, breakdownDuration, calculateMarketcap, compareMarketcap, getPercentage, areElsCollTop, areElsCollBottom, areElsCollLeft, areElsCollRight, areElsCollPerfTop, areElsCollPerfBottom, areElsCollPerfLeft, areElsCollPerfRight, areElsColliding, areElsPerfColliding, getElsColliding, getElsPerfColliding, getElsCollOverlap, getElsCollOverlapPos, getRectCenter, getElsRelativeCenterOffset, getElsCollDirDepth, getElsCollDetails, safeTextTrim, installWindowHiddenScript, genFibonacciSeq, isDirEmptyAsync, fileSizeAsync, dirSizeAsync, listFilesAsync, listDirsAsync, getLatestBackupPath, fetchJson, fetchText, readJsonBlob, readFileBlob, readBase64Blob, saveJsonFile, readJsonFile, writeJsonFile, ensureDirectory, clearDirectoryAsync, clearDirectory, fileExists, dirExists, isDirEmpty, ensureCopyFile, tryDeleteFile, writeTextFile, listFiles, listDirs, fileSize, dirSize, backupFile, restoreLatestBackup, renameFileBatch, renameFileRegex, renameFileAddPrefixSuffix, renameFileNormalizeCase, renameFilePadNumbers, documentIsFullScreen, isScreenFilled, requestFullScreen, exitFullScreen, isFullScreenMode, onFullScreenChange, offFullScreenChange, isJsonObject, arraySortPositions, formatBytes, addAiMarkerShortcut, extendObjType, reorderObjTypeOrder, cloneObjTypeOrder, countObj, checkObj, objType, ruleOfThree, getSimplePerc, asyncReplace, getAge, formatCustomTimer, formatDayTimer, formatTimer, getTimeDuration, shuffleArray, toTitleCase, toTitleCaseLowerFirst, };

package/dist/v1/libs/TinyArrayComparator.cjs

@@ -0,0 +1,130 @@
+'use strict';
+
+/**
+ * @fileoverview Array comparison utility.
+ * @module TinyArrayComparator
+ */
+
+/**
+ * @typedef {Object} InternalState
+ * Holds the internal tracking variables during the comparison process.
+ * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ */
+
+/**
+ * The final array that collects added or deleted items.
+ * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ */
+
+/**
+ * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ */
+class TinyArrayComparator {
+  /**
+   * Generates a simple 32-bit integer hash converted to a base36 string.
+   * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+   * @returns {string} The unique hash representing the item's value.
+   */
+  static generateHash(item) {
+    const stringified = typeof item === 'object' ? JSON.stringify(item) : String(item);
+    let hash = 0;
+
+    for (let i = 0, len = stringified.length; i < len; i++) {
+      const char = stringified.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0; // Convert to 32bit integer
+    }
+
+    return hash.toString(36);
+  }
+
+  /**
+   * Internal storage for the base array.
+   * @type {any[]}
+   */
+  #oldArray = [];
+
+  /**
+   * Gets the current base array used for comparisons.
+   * @returns {any[]} The current initial state of the array.
+   */
+  get oldArray() {
+    return this.#oldArray;
+  }
+
+  /**
+   * Sets a new base array for future comparisons.
+   * @param {Array<any>} oldArray - The initial state of the array.
+   * @throws {TypeError} Throws an error if the provided value is not an array.
+   */
+  set oldArray(oldArray) {
+    if (!Array.isArray(oldArray))
+      throw new TypeError('The provided oldArray must be a valid Array.');
+    this.#oldArray = oldArray;
+  }
+
+  /**
+   * Initializes the comparator with an optional base array.
+   * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+   */
+  constructor(oldArray) {
+    if (typeof oldArray !== 'undefined') this.oldArray = oldArray;
+  }
+
+  /**
+   * Proxy to generates a hash converted to a string.
+   * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+   * @returns {string} The unique hash representing the item's value.
+   * @private
+   */
+  _generateHash(item) {
+    return TinyArrayComparator.generateHash(item);
+  }
+
+  /**
+   * Compares the stored older array with a newer array and identifies missing or new items.
+   *
+   * @param {Array<any>} newArray - The modified state of the array.
+   * @returns {AffectedItems} An array containing the affected items and their status.
+   * @throws {TypeError} Throws an error if the provided value is not an array.
+   */
+  compare(newArray) {
+    if (!Array.isArray(newArray))
+      throw new TypeError('The provided newArray must be a valid Array.');
+
+    /** @type {InternalState} */
+    const state = {
+      oldItemsMap: new Map(),
+      affectedItems: [],
+    };
+
+    // Step 1: Hash and store all items from the first array
+    for (const item of this.#oldArray) {
+      const hashKey = this._generateHash(item);
+      state.oldItemsMap.set(hashKey, item);
+    }
+
+    // Step 2: Iterate through the second array to find matches or additions
+    for (const item of newArray) {
+      const hashKey = this._generateHash(item);
+
+      if (state.oldItemsMap.has(hashKey)) {
+        // Item exists in both, so it is unchanged. Remove from map.
+        state.oldItemsMap.delete(hashKey);
+      } else {
+        // Item was not in the old array, so it is an addition.
+        state.affectedItems.push({ item, status: 'added' });
+      }
+    }
+
+    // Step 3: Any item left in the oldItemsMap was not present in the new array (deleted)
+    for (const item of state.oldItemsMap.values()) {
+      state.affectedItems.push({ item, status: 'deleted' });
+    }
+
+    return state.affectedItems;
+  }
+}
+
+module.exports = TinyArrayComparator;

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

@@ -0,0 +1,79 @@
+export default TinyArrayComparator;
+/**
+ * Holds the internal tracking variables during the comparison process.
+ */
+export type InternalState = {
+    /**
+     * - A map storing the hash as the key and the original item as the value.
+     */
+    oldItemsMap: Map<string, any>;
+    /**
+     * - The final array that collects added or deleted items.
+     */
+    affectedItems: AffectedItems;
+};
+/**
+ * The final array that collects added or deleted items.
+ */
+export type AffectedItems = Array<{
+    item: any;
+    status: "added" | "deleted";
+}>;
+/**
+ * @fileoverview Array comparison utility.
+ * @module TinyArrayComparator
+ */
+/**
+ * @typedef {Object} InternalState
+ * Holds the internal tracking variables during the comparison process.
+ * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ */
+/**
+ * The final array that collects added or deleted items.
+ * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ */
+/**
+ * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ */
+declare class TinyArrayComparator {
+    /**
+     * Generates a simple 32-bit integer hash converted to a base36 string.
+     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @returns {string} The unique hash representing the item's value.
+     */
+    static generateHash(item: any): string;
+    /**
+     * Initializes the comparator with an optional base array.
+     * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+     */
+    constructor(oldArray?: Array<any>);
+    /**
+     * Sets a new base array for future comparisons.
+     * @param {Array<any>} oldArray - The initial state of the array.
+     * @throws {TypeError} Throws an error if the provided value is not an array.
+     */
+    set oldArray(oldArray: Array<any>);
+    /**
+     * Gets the current base array used for comparisons.
+     * @returns {any[]} The current initial state of the array.
+     */
+    get oldArray(): any[];
+    /**
+     * Proxy to generates a hash converted to a string.
+     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @returns {string} The unique hash representing the item's value.
+     * @private
+     */
+    private _generateHash;
+    /**
+     * Compares the stored older array with a newer array and identifies missing or new items.
+     *
+     * @param {Array<any>} newArray - The modified state of the array.
+     * @returns {AffectedItems} An array containing the affected items and their status.
+     * @throws {TypeError} Throws an error if the provided value is not an array.
+     */
+    compare(newArray: Array<any>): AffectedItems;
+    #private;
+}
+//# sourceMappingURL=TinyArrayComparator.d.mts.map

package/dist/v1/libs/TinyArrayComparator.mjs

@@ -0,0 +1,112 @@
+/**
+ * @fileoverview Array comparison utility.
+ * @module TinyArrayComparator
+ */
+/**
+ * @typedef {Object} InternalState
+ * Holds the internal tracking variables during the comparison process.
+ * @property {Map<string, any>} oldItemsMap - A map storing the hash as the key and the original item as the value.
+ * @property {AffectedItems} affectedItems - The final array that collects added or deleted items.
+ */
+/**
+ * The final array that collects added or deleted items.
+ * @typedef {Array<{item: any, status: 'added'|'deleted'}>} AffectedItems
+ */
+/**
+ * Compares two arrays efficiently by hashing their items to detect additions and deletions.
+ */
+class TinyArrayComparator {
+    /**
+     * Generates a simple 32-bit integer hash converted to a base36 string.
+     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @returns {string} The unique hash representing the item's value.
+     */
+    static generateHash(item) {
+        const stringified = typeof item === 'object' ? JSON.stringify(item) : String(item);
+        let hash = 0;
+        for (let i = 0, len = stringified.length; i < len; i++) {
+            const char = stringified.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash |= 0; // Convert to 32bit integer
+        }
+        return hash.toString(36);
+    }
+    /**
+     * Internal storage for the base array.
+     * @type {any[]}
+     */
+    #oldArray = [];
+    /**
+     * Gets the current base array used for comparisons.
+     * @returns {any[]} The current initial state of the array.
+     */
+    get oldArray() {
+        return this.#oldArray;
+    }
+    /**
+     * Sets a new base array for future comparisons.
+     * @param {Array<any>} oldArray - The initial state of the array.
+     * @throws {TypeError} Throws an error if the provided value is not an array.
+     */
+    set oldArray(oldArray) {
+        if (!Array.isArray(oldArray))
+            throw new TypeError('The provided oldArray must be a valid Array.');
+        this.#oldArray = oldArray;
+    }
+    /**
+     * Initializes the comparator with an optional base array.
+     * @param {Array<any>} [oldArray] - The initial state of the array to be stored.
+     */
+    constructor(oldArray) {
+        if (typeof oldArray !== 'undefined')
+            this.oldArray = oldArray;
+    }
+    /**
+     * Proxy to generates a hash converted to a string.
+     * @param {any} item - The item to be hashed (can be an object, array, string, or number).
+     * @returns {string} The unique hash representing the item's value.
+     * @private
+     */
+    _generateHash(item) {
+        return TinyArrayComparator.generateHash(item);
+    }
+    /**
+     * Compares the stored older array with a newer array and identifies missing or new items.
+     *
+     * @param {Array<any>} newArray - The modified state of the array.
+     * @returns {AffectedItems} An array containing the affected items and their status.
+     * @throws {TypeError} Throws an error if the provided value is not an array.
+     */
+    compare(newArray) {
+        if (!Array.isArray(newArray))
+            throw new TypeError('The provided newArray must be a valid Array.');
+        /** @type {InternalState} */
+        const state = {
+            oldItemsMap: new Map(),
+            affectedItems: [],
+        };
+        // Step 1: Hash and store all items from the first array
+        for (const item of this.#oldArray) {
+            const hashKey = this._generateHash(item);
+            state.oldItemsMap.set(hashKey, item);
+        }
+        // Step 2: Iterate through the second array to find matches or additions
+        for (const item of newArray) {
+            const hashKey = this._generateHash(item);
+            if (state.oldItemsMap.has(hashKey)) {
+                // Item exists in both, so it is unchanged. Remove from map.
+                state.oldItemsMap.delete(hashKey);
+            }
+            else {
+                // Item was not in the old array, so it is an addition.
+                state.affectedItems.push({ item, status: 'added' });
+            }
+        }
+        // Step 3: Any item left in the oldItemsMap was not present in the new array (deleted)
+        for (const item of state.oldItemsMap.values()) {
+            state.affectedItems.push({ item, status: 'deleted' });
+        }
+        return state.affectedItems;
+    }
+}
+export default TinyArrayComparator;

package/docs/v1/README.md

@@ -62,6 +62,7 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🎨 **[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.
+* 🔍 **[TinyArrayComparator](./libs/TinyArrayComparator.md)** — A lightweight, highly optimized JavaScript utility class designed to compare two arrays and efficiently detect which items were **added** or **deleted**.
 
 ### 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/TinyArrayComparator.md

@@ -0,0 +1,101 @@
+# 🔍 TinyArrayComparator
+
+A lightweight, highly optimized JavaScript utility class designed to compare two arrays and efficiently detect which items were **added** or **deleted**. 
+
+## ✨ Features
+
+- **Fast Comparison:** Uses a Map and hash-based lookups for $O(N)$ performance.
+- **Stateful Design:** Store your base array once and compare it multiple times.
+- **Zero Dependencies:** Pure Vanilla JavaScript.
+- **Deep Compatibility:** Safely hashes strings, numbers, arrays, and deep objects.
+- **Clean Architecture:** Built as an ES6 Module with strict JSDoc typing and input validation.
+
+---
+
+## 🚀 Quick Start
+
+### 1. Import the Class
+Since this project uses modern ES6 modules, simply import it into your working file.
+
+```javascript
+import TinyArrayComparator from './TinyArrayComparator.js';
+```
+
+### 2. Prepare Your Arrays
+Set up the initial state (`oldArray`) and the modified state (`newArray`) that you want to compare.
+
+```javascript
+const oldList = [
+  { id: 1, role: 'admin' },
+  { id: 2, role: 'user' },
+  { id: 3, role: 'moderator' }
+];
+
+const newList = [
+  { id: 1, role: 'admin' },       // Unchanged
+  { id: 3, role: 'moderator' },   // Unchanged
+  { id: 4, role: 'guest' }        // Added
+  // User ID 2 was deleted
+];
+```
+
+### 3. Initialize and Compare
+Instantiate the class passing the initial array. Then, call the `compare` method with your new array.
+
+```javascript
+const comparator = new TinyArrayComparator(oldList);
+const results = comparator.compare(newList);
+
+console.log(results);
+```
+
+**Output:**
+```json
+[
+  {
+    "item": { "id": 4, "role": "guest" },
+    "status": "added"
+  },
+  {
+    "item": { "id": 2, "role": "user" },
+    "status": "deleted"
+  }
+]
+```
+
+---
+
+## 🛠️ API Reference
+
+### `constructor([oldArray])`
+Creates a new comparator instance.
+* **`oldArray`** `(Array<any>)` *(Optional)*: The initial state of the array to be stored. Throws a `TypeError` if the provided value is not an Array.
+
+### `compare(newArray)`
+Evaluates differences between the internally stored `oldArray` and the provided `newArray`. Throws a `TypeError` if the provided value is not an Array.
+* **`newArray`** `(Array<any>)`: The new array containing current modifications.
+* **Returns:** An array of objects. Each object contains the original `item` and a `status` string (either `'added'` or `'deleted'`).
+
+### `get oldArray` / `set oldArray(value)`
+Allows you to retrieve or update the base array stored inside the instance.
+* **Throws:** `TypeError` if attempting to set a non-array value.
+
+### `static generateHash(item)`
+A static helper method if you ever need to generate a unique base36 hash string for an item outside the comparison flow.
+* **`item`** `(any)`: The target object, string, or number to hash.
+* **Returns:** A `string` representing the unique hash.
+
+```javascript
+const myHash = TinyArrayComparator.generateHash({ pony: 'Pudding' });
+console.log(myHash); // Returns a base36 string like "1b4x9z"
+```
+
+---
+
+## 💡 Best Practices
+
+* **Order Doesn't Matter:** Because this utility relies on value-hashing, the index order of items inside the arrays does not affect the comparison. It strictly checks for the existence of the values.
+* **Object References:** The returned array preserves the exact references to the items passed in the parameters, allowing you to seamlessly integrate the output back into your application logic.
+* **Reusability:** You can easily update the base state by assigning a new array to `comparator.oldArray = [...]` without creating a new instance.
+
+Happy coding! 💻✨

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tiny-essentials",
-  "version": "1.25.3",
+  "version": "1.25.4",
   "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",
@@ -220,6 +220,10 @@
       "require": "./dist/v1/libs/TinyTextDiffer.cjs",
       "import": "./dist/v1/libs/TinyTextDiffer.mjs"
     },
+    "./libs/TinyArrayComparator": {
+      "require": "./dist/v1/libs/TinyArrayComparator.cjs",
+      "import": "./dist/v1/libs/TinyArrayComparator.mjs"
+    },
     "./libs/TinyDragDropDetector": {
       "require": "./dist/v1/libs/TinyDragDropDetector.cjs",
       "import": "./dist/v1/libs/TinyDragDropDetector.mjs"