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.
122 lines • 3.99 kB
text/typescript
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 extends EventEmitter<any> {
/**
* 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;
});
/**
* 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}
*/
winEmit(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;
}
import { EventEmitter } from 'events';
//# sourceMappingURL=TinyNewWinEvents.d.mts.map