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.
193 lines • 7.54 kB
text/typescript
export default TinyIframeEvents;
/**
* 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.
*/
/**
* A flexible event routing system for structured communication
* between a parent window and its iframe using `postMessage`.
*
* 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
*
* Use this class when building applications that require modular, event-driven
* communication across embedded frames.
*/
declare class TinyIframeEvents {
/**
* 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 }?: {
targetIframe?: HTMLIFrameElement | undefined;
targetOrigin?: 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 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.
* @returns {string}
*/
get secretEventName(): string;
_boundOnMessage: (event: MessageEvent<any>) => void;
_boundOnceMessage: () => void;
/**
* Sends an event to the target window.
*
* @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.
*/
emit(eventName: string, payload: any): void;
/**
* Checks if the communication instance has been destroyed.
*
* @returns {boolean}
*/
isDestroyed(): boolean;
/**
* Unsubscribes all registered event listeners and removes the message handler.
* Call this when the instance is no longer needed to prevent memory leaks.
*/
destroy(): void;
#private;
}
//# sourceMappingURL=TinyIframeEvents.d.mts.map