tiny-essentials
Version:
Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.
167 lines • 6.5 kB
text/typescript
export default TinyIframeEvents;
/**
* A function to handle incoming event payloads.
*/
export type handler = (payload: any, event: MessageEvent<any>) => any;
/**
* Configuration object for initializing TinyIframeEvents.
*/
export type TinyIframeEventsConfig = {
/**
* - The target iframe element to post messages to. Required if instantiated in the parent window.
*/
targetIframe?: HTMLIFrameElement | undefined;
/**
* - The target origin to restrict messages to. Defaults to `window.location.origin`.
*/
targetOrigin?: string | undefined;
/**
* - Custom internal name used to validate standard routing messages.
*/
secretEventName?: string | undefined;
/**
* - Custom internal name used for the initial MessageChannel handshake.
*/
handshakeEventName?: string | undefined;
/**
* - Custom internal name used for the ready event trigger.
*/
readyEventName?: string | undefined;
};
/**
* Internal message structure for routed communication.
*/
export type IframeEventBase = {
/**
* - Dynamic key based on secretEventName to validate the message.
*/
secretIndicator?: boolean | undefined;
/**
* - The name of the custom event route.
*/
eventName: string;
/**
* - The data being sent (can be any type).
*/
payload: any;
/**
* - Indicates the sender: 'iframe' or 'parent'.
*/
direction: "iframe" | "parent";
};
/**
* @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.
*/
/**
* @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 communication by establishing
* a direct, un-interceptable port connection after a secure initial handshake.
*
* 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.
*/
declare class TinyIframeEvents extends EventEmitter<any> {
/**
* Creates a new TinyIframeEvents instance to manage secure communication.
* Automatically establishes a MessageChannel connection between contexts.
*
* @param {TinyIframeEventsConfig} config - Configuration object.
*/
constructor({ targetIframe, targetOrigin, secretEventName, handshakeEventName, readyEventName, }?: TinyIframeEventsConfig);
get targetWindow(): Window;
get targetIframeElement(): HTMLIFrameElement | undefined;
get targetOrigin(): string;
get selfType(): "iframe" | "parent";
get ready(): boolean;
/**
* 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: () => void): void;
_boundWindowMessage: (event: MessageEvent<any>) => void;
_boundPortMessage: (event: MessageEvent<any>) => void;
/**
* Sets the internal secret iframe event name.
* @param {string} name
* @throws {TypeError} If the value is not a string.
*/
set secretEventName(name: string);
/**
* Gets the internal secret iframe event name used for validation.
* @returns {string}
*/
get secretEventName(): string;
/**
* Sets the internal handshake event name.
* @param {string} name
* @throws {TypeError} If the value is not a string.
*/
set handshakeEventName(name: string);
/**
* Gets the internal handshake event name used for establishing the MessageChannel.
* @returns {string}
*/
get handshakeEventName(): string;
/**
* Sets the internal ready event name.
* @param {string} name
* @throws {TypeError} If the value is not a string.
*/
set readyEventName(name: string);
/**
* Gets the internal ready event name used when the connection is fully established.
* @returns {string}
*/
get readyEventName(): string;
/**
* 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 {TypeError} If `eventName` is not a string.
* @throws {Error} If instance has been destroyed.
*/
winEmit(eventName: string, payload: any): void;
/**
* Checks if the communication instance has been destroyed.
*
* @returns {boolean} True if destroyed, false otherwise.
*/
isDestroyed(): boolean;
/**
* 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(): void;
#private;
}
import { EventEmitter } from 'events';
//# sourceMappingURL=TinyIframeEvents.d.mts.map