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.
241 lines • 8.62 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 {
/**
* 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