tiny-essentials 1.19.3 → 1.20.1

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

@@ -0,0 +1,241 @@
+export default TinyNewWinEvents;
+/**
+ * A function to handle incoming event payloads.
+ */
+export type handler = (payload: any, event: MessageEvent<any>) => any;
+/**
+ * @callback handler
+ * A function to handle incoming event payloads.
+ * @param {any} payload - The data sent by the emitter.
+ * @param {MessageEvent<any>} event - Metadata about the message.
+ */
+/**
+ * TinyNewWinEvents provides structured communication between a main window
+ * and a child window (created using window.open) using postMessage.
+ *
+ * It supports routing, queuing messages until handshake is ready,
+ * connection status checks, and close detection.
+ *
+ * @class
+ */
+declare class TinyNewWinEvents {
+    /**
+     * Initializes a TinyNewWinEvents instance for communication.
+     *
+     * @param {Object} [settings={}] Configuration object.
+     * @param {string} [settings.targetOrigin] Origin to enforce in postMessage.
+     * @param {string} [settings.url] URL string to open.
+     * @param {string} [settings.name] Window name (required if opening a new window).
+     * @param {string} [settings.features] Features string for `window.open`.
+     *
+     * @throws {Error} If `name` is "_blank", which is not allowed.
+     * @throws {TypeError} If `targetOrigin`, `url`, or `features` are not strings (when provided).
+     * @throws {Error} If the window reference is invalid or already being tracked.
+     */
+    constructor({ targetOrigin, url, name, features }?: {
+        targetOrigin?: string | undefined;
+        url?: string | undefined;
+        name?: string | undefined;
+        features?: string | undefined;
+    });
+    /**
+     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     *
+     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     */
+    setThrowOnMaxListeners(shouldThrow: boolean): void;
+    /**
+     * Checks whether an error will be thrown when the max listener limit is exceeded.
+     *
+     * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+     */
+    getThrowOnMaxListeners(): boolean;
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     */
+    prependListener(event: string, handler: handler): void;
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     * @returns {handler} - The wrapped handler used internally.
+     */
+    prependListenerOnce(event: string, handler: handler): handler;
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    appendListener(event: string, handler: handler): void;
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    appendListenerOnce(event: string, handler: handler): handler;
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    on(event: string, handler: handler): void;
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    once(event: string, handler: handler): handler;
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {string} event - The name of the event to remove the handler from.
+     * @param {handler} handler - The specific callback function to remove.
+     */
+    off(event: string, handler: handler): void;
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event: string): void;
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes(): void;
+    /**
+     * Returns the number of listeners for a given event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {number} Number of listeners for the event.
+     */
+    listenerCount(event: string): number;
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    listeners(event: string): handler[];
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    onceListeners(event: string): handler[];
+    /**
+     * Returns a copy of the internal listeners array for the specified event,
+     * including wrapper functions like those used by `.once()`.
+     * @param {string | symbol} event - The event name.
+     * @returns {handler[]} An array of raw listener functions.
+     */
+    allListeners(event: string | symbol): handler[];
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames(): string[];
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n: number): void;
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners(): number;
+    /**
+     * Sets the internal handshake event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set readyEventName(name: string);
+    /**
+     * Gets the internal handshake event name.
+     * @returns {string}
+     */
+    get readyEventName(): string;
+    /**
+     * Sets the internal route event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set routeEventName(name: string);
+    /**
+     * Gets the internal route event name.
+     * @returns {string}
+     */
+    get routeEventName(): string;
+    _handleMessage: (event: MessageEvent) => void;
+    /**
+     * Returns the internal window reference.
+     *
+     * @returns {Window|null}
+     */
+    getWin(): Window | null;
+    /**
+     * Closes the child window (only allowed from the host).
+     *
+     * @returns {void}
+     */
+    close(): void;
+    /**
+     * Emits a message to the other window on a specific route.
+     * If the handshake is not yet complete, the message is queued.
+     * Throws an error if the instance has already been destroyed.
+     *
+     * @param {string} route - Route name used to identify the message handler.
+     * @param {any} payload - Data to send along with the message.
+     * @throws {Error} If the instance is already destroyed.
+     * @returns {void}
+     */
+    emit(route: string, payload: any): void;
+    /**
+     * Checks if the connection is active and the window is still open.
+     *
+     * @returns {boolean}
+     */
+    isConnected(): boolean;
+    /**
+     * Registers a callback for when the window is closed.
+     *
+     * @param {handler} callback Callback to run on close
+     * @returns {void}
+     */
+    onClose(callback: handler): void;
+    /**
+     * Unregisters a previously registered close callback.
+     *
+     * @param {handler} callback Callback to remove
+     * @returns {void}
+     */
+    offClose(callback: handler): void;
+    /**
+     * Checks if the communication instance has been destroyed.
+     *
+     * @returns {boolean}
+     */
+    isDestroyed(): boolean;
+    /**
+     * Destroys the communication instance, cleaning up all resources and listeners.
+     *
+     * @returns {void}
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=TinyNewWinEvents.d.mts.map

package/dist/v1/libs/TinyNewWinEvents.mjs

@@ -0,0 +1,437 @@
+import TinyEvents from './TinyEvents.mjs';
+/**
+ * Stores polling intervals associated with window references.
+ * Used to detect when the window is closed.
+ *
+ * @type {WeakMap<Window, NodeJS.Timeout>}
+ */
+const pollClosedInterval = new WeakMap();
+/**
+ * @callback handler
+ * A function to handle incoming event payloads.
+ * @param {any} payload - The data sent by the emitter.
+ * @param {MessageEvent<any>} event - Metadata about the message.
+ */
+/**
+ * TinyNewWinEvents provides structured communication between a main window
+ * and a child window (created using window.open) using postMessage.
+ *
+ * It supports routing, queuing messages until handshake is ready,
+ * connection status checks, and close detection.
+ *
+ * @class
+ */
+class TinyNewWinEvents {
+    #events = new TinyEvents();
+    /**
+     * Enables or disables throwing an error when the maximum number of listeners is exceeded.
+     *
+     * @param {boolean} shouldThrow - If true, an error will be thrown when the max is exceeded.
+     */
+    setThrowOnMaxListeners(shouldThrow) {
+        return this.#events.setThrowOnMaxListeners(shouldThrow);
+    }
+    /**
+     * Checks whether an error will be thrown when the max listener limit is exceeded.
+     *
+     * @returns {boolean} True if an error will be thrown, false if only a warning is shown.
+     */
+    getThrowOnMaxListeners() {
+        return this.#events.getThrowOnMaxListeners();
+    }
+    /////////////////////////////////////////////////////////////
+    /**
+     * Adds a listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     */
+    prependListener(event, handler) {
+        return this.#events.prependListener(event, handler);
+    }
+    /**
+     * Adds a one-time listener to the beginning of the listeners array for the specified event.
+     *
+     * @param {string} event - Event name.
+     * @param {handler} handler - The callback function.
+     * @returns {handler} - The wrapped handler used internally.
+     */
+    prependListenerOnce(event, handler) {
+        return this.#events.prependListenerOnce(event, handler);
+    }
+    //////////////////////////////////////////////////////////////////////
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    appendListener(event, handler) {
+        return this.#events.appendListener(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    appendListenerOnce(event, handler) {
+        return this.#events.appendListenerOnce(event, handler);
+    }
+    /**
+     * Adds a event listener.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - Callback function to be called when event fires.
+     */
+    on(event, handler) {
+        return this.#events.on(event, handler);
+    }
+    /**
+     * Registers an event listener that runs only once, then is removed.
+     *
+     * @param {string} event - Event name, such as 'onScrollBoundary' or 'onAutoScroll'.
+     * @param {handler} handler - The callback function to run on event.
+     * @returns {handler} - The wrapped version of the handler.
+     */
+    once(event, handler) {
+        return this.#events.once(event, handler);
+    }
+    ////////////////////////////////////////////////////////////////////
+    /**
+     * Removes a previously registered event listener.
+     *
+     * @param {string} event - The name of the event to remove the handler from.
+     * @param {handler} handler - The specific callback function to remove.
+     */
+    off(event, handler) {
+        return this.#events.off(event, handler);
+    }
+    /**
+     * Removes all event listeners of a specific type from the element.
+     *
+     * @param {string} event - The event type to remove (e.g. 'onScrollBoundary').
+     */
+    offAll(event) {
+        return this.#events.offAll(event);
+    }
+    /**
+     * Removes all event listeners of all types from the element.
+     */
+    offAllTypes() {
+        return this.#events.offAllTypes();
+    }
+    ////////////////////////////////////////////////////////////
+    /**
+     * Returns the number of listeners for a given event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {number} Number of listeners for the event.
+     */
+    listenerCount(event) {
+        return this.#events.listenerCount(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    listeners(event) {
+        return this.#events.listeners(event);
+    }
+    /**
+     * Returns a copy of the array of listeners for the specified event.
+     *
+     * @param {string} event - The name of the event.
+     * @returns {handler[]} Array of listener functions.
+     */
+    onceListeners(event) {
+        return this.#events.onceListeners(event);
+    }
+    /**
+     * Returns a copy of the internal listeners array for the specified event,
+     * including wrapper functions like those used by `.once()`.
+     * @param {string | symbol} event - The event name.
+     * @returns {handler[]} An array of raw listener functions.
+     */
+    allListeners(event) {
+        return this.#events.allListeners(event);
+    }
+    /**
+     * Returns an array of event names for which there are registered listeners.
+     *
+     * @returns {string[]} Array of registered event names.
+     */
+    eventNames() {
+        return this.#events.eventNames();
+    }
+    //////////////////////////////////////////////////////
+    /**
+     * Sets the maximum number of listeners per event before a warning is shown.
+     *
+     * @param {number} n - The maximum number of listeners.
+     */
+    setMaxListeners(n) {
+        return this.#events.setMaxListeners(n);
+    }
+    /**
+     * Gets the maximum number of listeners allowed per event.
+     *
+     * @returns {number} The maximum number of listeners.
+     */
+    getMaxListeners() {
+        return this.#events.getMaxListeners();
+    }
+    ///////////////////////////////////////////////////
+    /** @type {Window|null} Reference to the opened or parent window */
+    #windowRef;
+    /** @type {string} Expected origin for postMessage communication */
+    #targetOrigin;
+    /** @type {{ route: string, payload: any }[]} Queue of messages emitted before connection is ready */
+    #pendingQueue = [];
+    /** @type {boolean} True if handshake between windows is complete */
+    #ready = false;
+    /** @type {boolean} True if this instance is the main window (host) */
+    #isHost = false;
+    /** @type {NodeJS.Timeout|null} Interval for polling child window closure */
+    #pollClosedInterval = null;
+    /** @type {string} Internal message type for handshake */
+    #readyEventName = '__TNE_READY__';
+    /** @type {string} Internal message type for routed communication */
+    #routeEventName = '__TNE_ROUTE__';
+    /**
+     * Gets the internal handshake event name.
+     * @returns {string}
+     */
+    get readyEventName() {
+        return this.#readyEventName;
+    }
+    /**
+     * Sets the internal handshake event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set readyEventName(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyNewWinEvents: readyEventName must be a string.');
+        this.#readyEventName = name;
+    }
+    /**
+     * Gets the internal route event name.
+     * @returns {string}
+     */
+    get routeEventName() {
+        return this.#routeEventName;
+    }
+    /**
+     * Sets the internal route event name.
+     * @param {string} name
+     * @throws {TypeError} If the value is not a string.
+     */
+    set routeEventName(name) {
+        if (typeof name !== 'string')
+            throw new TypeError('TinyNewWinEvents: routeEventName must be a string.');
+        this.#routeEventName = name;
+    }
+    /**
+     * Initializes a TinyNewWinEvents instance for communication.
+     *
+     * @param {Object} [settings={}] Configuration object.
+     * @param {string} [settings.targetOrigin] Origin to enforce in postMessage.
+     * @param {string} [settings.url] URL string to open.
+     * @param {string} [settings.name] Window name (required if opening a new window).
+     * @param {string} [settings.features] Features string for `window.open`.
+     *
+     * @throws {Error} If `name` is "_blank", which is not allowed.
+     * @throws {TypeError} If `targetOrigin`, `url`, or `features` are not strings (when provided).
+     * @throws {Error} If the window reference is invalid or already being tracked.
+     */
+    constructor({ targetOrigin, url, name, features } = {}) {
+        if (typeof name === 'string' && name === '_blank')
+            throw new Error('TinyNewWinEvents: The window name "_blank" is not supported. Please use a custom name to allow tracking.');
+        if (typeof targetOrigin !== 'undefined' && typeof targetOrigin !== 'string')
+            throw new TypeError('TinyNewWinEvents: The "targetOrigin" option must be a string.');
+        if (typeof url !== 'undefined' && typeof url !== 'string')
+            throw new TypeError('TinyNewWinEvents: The "url" option must be a string.');
+        if (typeof features !== 'undefined' && typeof features !== 'string')
+            throw new TypeError('TinyNewWinEvents: The "features" option must be a string if provided.');
+        // Open Page
+        if (typeof url === 'undefined')
+            this.#windowRef = window.opener;
+        // Main Page
+        else {
+            this.#windowRef = typeof url === 'string' ? window.open(url, name, features) : url;
+            this.#isHost = true;
+        }
+        if (!this.#windowRef || pollClosedInterval.has(this.#windowRef))
+            throw new Error('Invalid or duplicate window reference.');
+        this.#targetOrigin = targetOrigin ?? window.location.origin;
+        this._handleMessage = this.#handleMessage.bind(this);
+        window.addEventListener('message', this._handleMessage, false);
+        // Sends handshake if it is host (main window)
+        if (!this.#isHost) {
+            this.#postRaw(this.#readyEventName, null);
+            this.#startCloseWatcher();
+        }
+    }
+    /**
+     * Returns the internal window reference.
+     *
+     * @returns {Window|null}
+     */
+    getWin() {
+        return this.#windowRef;
+    }
+    /**
+     * Internal message handler.
+     *
+     * @param {MessageEvent} event
+     * @returns {void}
+     */
+    #handleMessage(event) {
+        if (!event.source || (this.#windowRef && event.source !== this.#windowRef))
+            return;
+        const { type, route, payload } = event.data || {};
+        if (type === this.#readyEventName) {
+            this.#ready = true;
+            this.#flushQueue();
+            this.#startCloseWatcher(); // start watcher after handshake (for child window)
+            if (this.#isHost)
+                this.#postRaw(this.#readyEventName, null);
+            return;
+        }
+        if (type === this.#routeEventName)
+            this.#events.emit(route, payload, event);
+    }
+    /**
+     * Sends all pending messages queued before handshake completion.
+     *
+     * @returns {void}
+     */
+    #flushQueue() {
+        while (this.#pendingQueue.length) {
+            const data = this.#pendingQueue.shift();
+            if (data) {
+                const { route, payload } = data;
+                this.emit(route, payload);
+            }
+        }
+    }
+    /**
+     * Sends a raw postMessage with given type and payload.
+     *
+     * @param {string} type Internal message type
+     * @param {any} payload Data to send
+     * @param {string} [route=''] Optional route name
+     * @returns {void}
+     */
+    #postRaw(type, payload, route = '') {
+        if (this.#windowRef && this.#windowRef.closed)
+            return;
+        this.#windowRef?.postMessage({ type, route, payload }, this.#targetOrigin);
+    }
+    /**
+     * Closes the child window (only allowed from the host).
+     *
+     * @returns {void}
+     */
+    close() {
+        if (!this.#isHost)
+            throw new Error('Only host can close the window.');
+        if (this.#windowRef && !this.#windowRef.closed)
+            this.#windowRef.close();
+    }
+    /**
+     * Emits a message to the other window on a specific route.
+     * If the handshake is not yet complete, the message is queued.
+     * Throws an error if the instance has already been destroyed.
+     *
+     * @param {string} route - Route name used to identify the message handler.
+     * @param {any} payload - Data to send along with the message.
+     * @throws {Error} If the instance is already destroyed.
+     * @returns {void}
+     */
+    emit(route, payload) {
+        if (typeof route !== 'string')
+            throw new TypeError('Event name must be a string.');
+        if (this.isDestroyed())
+            throw new Error('Cannot emit: instance has been destroyed.');
+        if (!this.#ready) {
+            this.#pendingQueue.push({ route, payload });
+            return;
+        }
+        this.#postRaw(this.#routeEventName, payload, route);
+    }
+    /**
+     * Checks if the connection is active and the window is still open.
+     *
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.#ready && this.#windowRef && !this.#windowRef.closed ? true : false;
+    }
+    /**
+     * Starts polling to detect when the window is closed.
+     *
+     * @returns {void}
+     */
+    #startCloseWatcher() {
+        if (!this.#windowRef || this.#pollClosedInterval)
+            return;
+        this.#pollClosedInterval = setInterval(() => {
+            if (this.#windowRef?.closed) {
+                this.#events.emit('WINDOW_REF_CLOSED');
+                this.destroy();
+            }
+        }, 500);
+        pollClosedInterval.set(this.#windowRef, this.#pollClosedInterval);
+    }
+    /**
+     * Registers a callback for when the window is closed.
+     *
+     * @param {handler} callback Callback to run on close
+     * @returns {void}
+     */
+    onClose(callback) {
+        return this.#events.on('WINDOW_REF_CLOSED', callback);
+    }
+    /**
+     * Unregisters a previously registered close callback.
+     *
+     * @param {handler} callback Callback to remove
+     * @returns {void}
+     */
+    offClose(callback) {
+        return this.#events.off('WINDOW_REF_CLOSED', callback);
+    }
+    /**
+     * Checks if the communication instance has been destroyed.
+     *
+     * @returns {boolean}
+     */
+    isDestroyed() {
+        return !this.#windowRef;
+    }
+    /**
+     * Destroys the communication instance, cleaning up all resources and listeners.
+     *
+     * @returns {void}
+     */
+    destroy() {
+        if (!this.#windowRef)
+            return;
+        if (this.#pollClosedInterval) {
+            clearInterval(this.#pollClosedInterval);
+            this.#pollClosedInterval = null;
+            pollClosedInterval.delete(this.#windowRef);
+        }
+        window.removeEventListener('message', this._handleMessage);
+        this.#pendingQueue = [];
+        this.#ready = false;
+        this.#windowRef = null;
+        this.#events.offAllTypes();
+    }
+}
+export default TinyNewWinEvents;

package/docs/v1/README.md

@@ -44,6 +44,8 @@ This folder contains the core scripts we have worked on so far. Each file is a m
 - 🌈 **[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.
+- 🖼️ **[TinyIframeEvents](./libs/TinyIframeEvents.md)** — A structured `postMessage`-based event router for secure and reliable communication between a parent window and its embedded iframe. Supports directional filtering, origin enforcement, payload transport, and listener lifecycle.
+- 🪟 **[TinyNewWinEvents](./libs/TinyNewWinEvents.md)** — A smart, route-based `postMessage` system for structured communication between a main window and a popup (`window.open`). Includes queueing, origin enforcement, and lifecycle tracking.
 
 ### 3. **`fileManager/`**
 * 📁 **[Main](./fileManager/main.md)** — A Node.js file/directory utility module with support for JSON, backups, renaming, size analysis, and more.