tiny-essentials 1.25.2 → 1.25.4

package/dist/v1/libs/TinyIframeEvents.mjs

@@ -9,18 +9,35 @@ const instances = new WeakMap();
  * @param {MessageEvent<any>} event - Metadata about the message.
  */
 /**
- * A flexible event routing system for structured communication
- * between a parent window and its iframe using `postMessage`.
+ * @typedef {object} TinyIframeEventsConfig
+ * Configuration object for initializing TinyIframeEvents.
+ * @property {HTMLIFrameElement} [targetIframe] - The target iframe element to post messages to. Required if instantiated in the parent window.
+ * @property {string} [targetOrigin] - The target origin to restrict messages to. Defaults to `window.location.origin`.
+ * @property {string} [secretEventName] - Custom internal name used to validate standard routing messages.
+ * @property {string} [handshakeEventName] - Custom internal name used for the initial MessageChannel handshake.
+ * @property {string} [readyEventName] - Custom internal name used for the ready event trigger.
+ */
+/**
+ * @typedef {object} IframeEventBase
+ * Internal message structure for routed communication.
+ * @property {boolean} [secretIndicator] - Dynamic key based on secretEventName to validate the message.
+ * @property {string} eventName - The name of the custom event route.
+ * @property {any} payload - The data being sent (can be any type).
+ * @property {'iframe' | 'parent'} direction - Indicates the sender: 'iframe' or 'parent'.
+ */
+/**
+ * A highly secure and flexible event routing system for structured communication
+ * between a parent window and its iframe using `MessageChannel`.
  *
- * This class abstracts the complexity of cross-origin and window-type handling,
- * allowing both the iframe and parent to:
- * - Send events with arbitrary payloads
- * - Listen to specific event names
- * - Filter events by origin and source
- * - Work symmetrically from both sides with automatic direction handling
+ * This class abstracts the complexity of cross-origin communication by establishing
+ * a direct, un-interceptable port connection after a secure initial handshake.
  *
- * Use this class when building applications that require modular, event-driven
- * communication across embedded frames.
+ * Features:
+ * - Secure direct pipeline via `MessageChannel`.
+ * - Customizable internal event names to avoid collisions.
+ * - Symmetrical usage for both parent and iframe.
+ * - Queue management for messages sent before the connection is established.
+ * - Auto-reconnects and resets ports if the target iframe is reloaded.
  */
 class TinyIframeEvents {
     #events = new TinyEvents();
@@ -188,29 +205,87 @@ class TinyIframeEvents {
     ///////////////////////////////////////////////////
     /** @type {Window} */
     #targetWindow;
+    get targetWindow() {
+        return this.#targetWindow;
+    }
+    /** @type {HTMLIFrameElement | undefined} */
+    #targetIframeElement;
+    get targetIframeElement() {
+        return this.#targetIframeElement;
+    }
     /** @type {string} */
     #targetOrigin;
-    /** @type {string} */
+    get targetOrigin() {
+        return this.#targetOrigin;
+    }
+    /** @type {'iframe' | 'parent'} */
     #selfType;
+    get selfType() {
+        return this.#selfType;
+    }
     /** @type {boolean} */
     #isDestroyed = false;
     /** @type {boolean} */
     #ready = false;
+    get ready() {
+        return this.#ready;
+    }
     /**
-     * @typedef {object} IframeEventBase
-     * @property {string} eventName - The name of the custom event route.
-     * @property {any} payload - The data being sent (can be any type).
-     * @property {'iframe' | 'parent'} direction - Indicates the sender: 'iframe' or 'parent'.
+     * Executes the provided callback when the secure MessageChannel connection is fully established.
+     * If the connection is already ready, the callback is executed immediately.
+     *
+     * @param {function(): void} handler - The callback function to execute.
      */
+    onReady(handler) {
+        if (this.#ready) {
+            handler();
+        }
+        else {
+            this.#events.once(this.#readyEventName, handler);
+        }
+    }
+    /** @type {MessagePort | null} */
+    #port = null;
+    /** @type {IframeEventBase[]} */
+    #pendingQueue = [];
+    /** @type {string} */
+    #secretEventName;
+    /** @type {string} */
+    #handshakeEventName;
+    /** @type {string} */
+    #readyEventName;
+    /** @type {(() => void) | null} */
+    #boundSendPort = null;
     /**
-     * Queue of messages emitted before connection is ready
-     * @type {IframeEventBase[]}
+     * Creates a new TinyIframeEvents instance to manage secure communication.
+     * Automatically establishes a MessageChannel connection between contexts.
+     *
+     * @param {TinyIframeEventsConfig} config - Configuration object.
      */
-    #pendingQueue = [];
-    /** @type {string} Internal message type for routed communication */
-    #secretEventName = '__tinyIframeEvent__';
+    constructor({ targetIframe, targetOrigin = window.location.origin, secretEventName = '__tinyIframeEvent__', handshakeEventName = '__tinyIframeHandshake__', readyEventName = '__tinyIframeReady__', } = {}) {
+        if (targetIframe !== undefined &&
+            (!(targetIframe instanceof HTMLIFrameElement) || !targetIframe.contentWindow)) {
+            throw new TypeError(`[TinyIframeEvents] Invalid "targetIframe": expected HTMLIFrameElement, received ${typeof targetIframe}`);
+        }
+        if (typeof targetOrigin !== 'string') {
+            throw new TypeError(`[TinyIframeEvents] Invalid "targetOrigin": expected string, received ${typeof targetOrigin}`);
+        }
+        this.#targetIframeElement = targetIframe;
+        this.#targetWindow = targetIframe?.contentWindow ?? window.parent;
+        this.#targetOrigin = targetOrigin;
+        this.#selfType = !targetIframe ? 'iframe' : 'parent';
+        this.#secretEventName = secretEventName;
+        this.#handshakeEventName = handshakeEventName;
+        this.#readyEventName = readyEventName;
+        if (instances.has(this.#targetWindow))
+            throw new Error('Duplicate window reference.');
+        this._boundWindowMessage = this.#onWindowMessage.bind(this);
+        this._boundPortMessage = this.#onPortMessage.bind(this);
+        this.#initializeConnection();
+        instances.set(this.#targetWindow, this);
+    }
     /**
-     * Gets the internal secret iframe event name.
+     * Gets the internal secret iframe event name used for validation.
      * @returns {string}
      */
     get secretEventName() {
@@ -227,71 +302,140 @@ class TinyIframeEvents {
         this.#secretEventName = name;
     }
     /**
-     * Creates a new TinyIframeEvents instance to manage communication between iframe and parent.
-     * Automatically determines the current context (`iframe` or `parent`) based on the `targetWindow`.
-     *
-     * @param {Object} config - Configuration object.
-     * @param {HTMLIFrameElement} [config.targetIframe] - The target window to post messages to. Defaults to `window.parent` (assumes this is inside an iframe).
-     * @param {string} [config.targetOrigin] - The target origin to restrict messages to. Defaults to `window.location.origin`.
-     */
-    constructor({ targetIframe, targetOrigin } = {}) {
-        if (typeof targetIframe !== 'undefined' &&
-            (!(targetIframe instanceof HTMLIFrameElement) || !targetIframe.contentWindow))
-            throw new TypeError(`[TinyIframeEvents] Invalid "targetIframe" provided: expected a HTML Iframe Element, received ${typeof targetIframe}`);
-        if (typeof targetOrigin !== 'undefined' && typeof targetOrigin !== 'string')
-            throw new TypeError(`[TinyIframeEvents] Invalid "targetOrigin" provided: expected a string, received ${typeof targetOrigin}`);
-        this.#targetWindow = targetIframe?.contentWindow ?? window.parent;
-        this.#targetOrigin = targetOrigin ?? window.location.origin;
-        this.#selfType = !targetIframe ? 'iframe' : 'parent';
-        if (instances.has(this.#targetWindow))
-            throw new Error('Duplicate window reference.');
-        this._boundOnMessage = this.#onMessage.bind(this);
-        this._boundOnceMessage = this.#onceMessage.bind(this);
-        if (this.#targetWindow.document.readyState === 'complete' ||
-            this.#targetWindow.document.readyState === 'interactive')
-            this.#onceMessage();
+     * Gets the internal handshake event name used for establishing the MessageChannel.
+     * @returns {string}
+     */
+    get handshakeEventName() {
+        return this.#handshakeEventName;
+    }
+    /**
+     * Sets the internal handshake event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set handshakeEventName(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyIframeEvents: handshakeEventName must be a string.');
+        this.#handshakeEventName = name;
+    }
+    /**
+     * Gets the internal ready event name used when the connection is fully established.
+     * @returns {string}
+     */
+    get readyEventName() {
+        return this.#readyEventName;
+    }
+    /**
+     * Sets the internal ready event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set readyEventName(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyIframeEvents: readyEventName must be a string.');
+        this.#readyEventName = name;
+    }
+    /**
+     * Initializes the correct connection strategy based on the current context (parent or iframe).
+     */
+    #initializeConnection() {
+        if (this.#selfType === 'parent') {
+            this.#boundSendPort = () => {
+                if (this.#isDestroyed)
+                    return;
+                // Closes any existing port to prevent memory leaks during iframe reloads
+                if (this.#port) {
+                    this.#port.close();
+                }
+                // Creates a fresh channel for every attempt to prevent clone errors
+                const channel = new MessageChannel();
+                this.#port = channel.port1;
+                this.#port.onmessage = this._boundPortMessage;
+                // Resets ready state to require a new ACK
+                this.#ready = false;
+                this.#targetWindow.postMessage({ type: this.#handshakeEventName }, this.#targetOrigin, [
+                    channel.port2,
+                ]);
+            };
+            if (this.#targetIframeElement) {
+                this.#targetIframeElement.addEventListener('load', this.#boundSendPort);
+                this.#boundSendPort();
+            }
+        }
         else {
-            this.#targetWindow.addEventListener('load', this._boundOnceMessage, false);
-            this.#targetWindow.addEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+            window.addEventListener('message', this._boundWindowMessage, false);
         }
-        window.addEventListener('message', this._boundOnMessage, false);
-        instances.set(this.#targetWindow, this);
     }
     /**
-     * Marks the communication as ready and flushes any queued messages.
+     * Internal handler for the initial window message event (used by iframe to receive the port).
+     *
+     * @param {MessageEvent<any>} event - The message event received via `postMessage`.
      */
-    #onceMessage() {
-        if (this.#ready)
+    #onWindowMessage(event) {
+        const data = event.data;
+        const ports = event.ports;
+        if (!isJsonObject(data) || data.type !== this.#handshakeEventName || ports.length === 0)
             return;
-        this.#ready = true;
-        this.#flushQueue();
+        this.#port = ports[0];
+        this.#port.onmessage = this._boundPortMessage;
+        window.removeEventListener('message', this._boundWindowMessage);
+        this.#port.postMessage({ type: `${this.#handshakeEventName}_ACK` });
+        this.#markReady();
     }
     /**
-     * Internal handler for the message event. Filters and dispatches incoming messages.
+     * Internal handler for messages received through the secure MessageChannel port.
      *
-     * @param {MessageEvent<any>} event - The message event received via `postMessage`.
+     * @param {MessageEvent<any>} event - The message event received via `MessagePort`.
      */
-    #onMessage(event) {
-        const { data, source } = event;
-        // Reject non-object or unrelated messages
+    #onPortMessage(event) {
+        /** @type {any} */
+        const data = event.data;
+        if (isJsonObject(data) && data.type === `${this.#handshakeEventName}_ACK`) {
+            this.#markReady();
+            return;
+        }
         if (!isJsonObject(data) || !data[this.#secretEventName])
             return;
-        const { eventName, payload, direction } = data;
-        // Reject if not from the expected window (for security)
-        if (source !== this.#targetWindow)
+        const eventName = data.eventName;
+        const payload = data.payload;
+        const direction = data.direction;
+        if (typeof eventName !== 'string' ||
+            (this.#selfType === 'iframe' && direction !== 'iframe') ||
+            (this.#selfType === 'parent' && direction !== 'parent')) {
             return;
-        // Reject if direction is not meant for this side
-        if ((this.#selfType === 'iframe' && direction !== 'iframe') ||
-            (this.#selfType === 'parent' && direction !== 'parent'))
+        }
+        this.#events.emit(eventName, payload, event);
+    }
+    /**
+     * Marks the communication as ready, flushes any queued messages,
+     * and triggers the internal ready event for any waiting listeners.
+     */
+    #markReady() {
+        if (this.#ready)
             return;
-        this.#events.emit(/** @type {string} */ (eventName), payload, event);
+        this.#ready = true;
+        this.#flushQueue();
+        this.#events.emit(this.#readyEventName);
     }
     /**
-     * Sends an event to the target window.
+     * Sends all pending messages queued before the secure port was established.
+     */
+    #flushQueue() {
+        while (this.#pendingQueue.length > 0) {
+            /** @type {IframeEventBase | undefined} */
+            const data = this.#pendingQueue.shift();
+            if (data && this.#port) {
+                this.#port.postMessage(data);
+            }
+        }
+    }
+    /**
+     * Sends an event to the target window through the secure MessageChannel.
      *
      * @param {string} eventName - A unique name identifying the event.
      * @param {*} payload - The data to send with the event. Can be any serializable value.
-     * @throws {Error} If `eventName` is not a string.
+     * @throws {TypeError} If `eventName` is not a string.
+     * @throws {Error} If instance has been destroyed.
      */
     emit(eventName, payload) {
         if (typeof eventName !== 'string')
@@ -305,41 +449,35 @@ class TinyIframeEvents {
             payload,
             direction: this.#selfType === 'parent' ? 'iframe' : 'parent',
         };
-        if (!this.#ready) {
+        if (!this.#ready || !this.#port) {
             this.#pendingQueue.push(message);
             return;
         }
-        this.#targetWindow.postMessage(message, this.#targetOrigin);
-    }
-    /**
-     * Sends all pending messages queued before handshake completion.
-     *
-     * @returns {void}
-     */
-    #flushQueue() {
-        while (this.#pendingQueue.length) {
-            const data = this.#pendingQueue.shift();
-            if (data)
-                this.#targetWindow.postMessage(data, this.#targetOrigin);
-        }
+        this.#port.postMessage(message);
     }
     /**
      * Checks if the communication instance has been destroyed.
      *
-     * @returns {boolean}
+     * @returns {boolean} True if destroyed, false otherwise.
      */
     isDestroyed() {
         return this.#isDestroyed;
     }
     /**
-     * Unsubscribes all registered event listeners and removes the message handler.
+     * Unsubscribes all registered event listeners, closes the message port, and cleans up references.
      * Call this when the instance is no longer needed to prevent memory leaks.
      */
     destroy() {
         this.#isDestroyed = true;
-        window.removeEventListener('message', this._boundOnMessage);
-        this.#targetWindow.removeEventListener('load', this._boundOnceMessage, false);
-        this.#targetWindow.removeEventListener('DOMContentLoaded', this._boundOnceMessage, false);
+        this.#ready = false;
+        window.removeEventListener('message', this._boundWindowMessage);
+        if (this.#targetIframeElement && this.#boundSendPort) {
+            this.#targetIframeElement.removeEventListener('load', this.#boundSendPort);
+        }
+        if (this.#port) {
+            this.#port.close();
+            this.#port = null;
+        }
         this.#events.offAllTypes();
         this.#pendingQueue = [];
         instances.delete(this.#targetWindow);

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! 💻✨