structured-channel/lib/channel.d.ts

A wrapper around MessageChannel API for bi-directional communication between two browsing contexts.

import { MessagePayload } from './types';
declare class Channel {
    static debug: boolean;
    private _handlers;
    private _pendingMessages;
    private _messageId;
    private port;
    /**
     * The StructuredChannel constructor that creates a wrapper around MessagePort
     * for sending and receiving messages.
     *
     * Users should not create instances themselves but instead use
     * waitForConnection() and connectTo() static methods.
     *
     * @constructor
     *
     * @param {MessagePort} port - The port this object wraps.
     */
    constructor(port: MessagePort);
    /**
     * Prints a message to the console if this._doDebug is true.
     * @private
     */
    private static _debug;
    /**
     * Prints a warning message to the console.
     * @private
     */
    private _warn;
    /**
     * Handles the messages sent to this port.
     *
     * @private
     */
    private _handleMessage;
    /**
     * Handles replies to previously sent message.
     *
     * @private
     */
    private _handleReply;
    /**
     * Handles a new message.
     *
     * @private
     */
    private _handleNewMessage;
    /**
     * Adds a handler for given message type.
     *
     * @param {String} eventType - The type of the message to handle.
     * @param {Function} handler - The handler function. The return value will be
     * transferred back to the sender and the Promise returned by send() is
     * settled according to it. If the function throws, returns a Promise that
     * is eventually rejected or returns a value that cannot be transmitted to the
     * sender, the send() Promise rejects. If the function returns a value, the
     * send() Promise is fulfilled with that value. If the function returns a
     * Promise that is eventually fulfilled, the send() Promise is fulfilled with
     * the fulfillment value.
     */
    on(eventType: string, handler: any): void;
    /**
     * Removes the handler for the message of given type.
     *
     * @param {String} eventType - The type of the message for which the handler is
     * to be removed.
     */
    off(eventType: string): void;
    /**
     * Sends a message to the other side of the channel.
     *
     * @param {String} type - The type of the message.
     * @param {Object} payload - The payload for the message. The value must
     * support structured cloning.
     *
     * @return {Promise} A Promise that is resolved once the receiver has handled
     * the message. The resolution value will be the object the handler method
     * returned. If the other party fails to handle the message, the Promise is
     * rejected.
     */
    send<T = unknown>(type: string, payload?: MessagePayload): Promise<T>;
    /**
     * Opens a Channel to the given target. The target must load call `Channel.waitForConnection()` on other end.
     *
     * @param {Window|Worker} target - The target window or a worker to connect to.
     * @param {String} [targetOrigin=*] - If the target is a Window, this is the
     * `targetOrigin` for [Window.postMessage()](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage).
     * __Failing to provide this parameter might have security implications as the
     * channel could be opened to a malicious target.__ If the target is a Worker,
     * this parameter is ignored.
     * @param {Object} [global] - An optional global object that can be used to get
     * a reference to the MessageChannel constructor.
     *
     * @return {Promise} A Promise that is fulfilled with a `StructuredChannel`
     * instance once the connection has been established. The Promise is rejected on
     * error.
     *
     * @throws {TypeError} TypeError if @param target is undefined.
     *
     */
    static connectTo(target: Window | Worker, targetOrigin?: string | typeof globalThis, global?: typeof globalThis): Promise<Channel>;
    /**
     * Waits for a connection request from `StructuredChannel.connectTo()` to arrive
     * as a message event to the given target.
     *
     * @param {Window|Worker} [target] - The target that should receive the
     * connection attempt (default `self`).
     * @param {String} [origin] - The origin from which the connection attempt should
     * come from. If undefined or '*', connection attempts and messages from all
     * origins are allowed. __Failing to provide a specific origin might have
     * security implications as malicious parties could establish a connection to
     * this target.__
     *
     * @return {Promise} that is resolved with a `StructuredChannel` instance once
     * the connection request is received.
     */
    static waitForConnection(target?: Worker | Window, origin?: string): Promise<Channel>;
}
export default Channel;