post-me/dist/messenger.d.ts

Use web Workers and other Windows through a simple Promise API

declare type MessageListener = (event: MessageEvent) => void;
declare type ListenerRemover = () => void;
/**
 * An interface used internally to exchange low level messages across contexts.
 *
 * @remarks
 *
 * Having a single interface lets post-me deal with Workers, Windows, and MessagePorts
 * without having to worry about their differences.
 *
 * A few concrete implementations of the Messenger interface are provided.
 *
 * @public
 *
 */
export interface Messenger {
    /**
     * Send a message to the other context
     *
     * @param message - The payload of the message
     * @param transfer - A list of Transferable objects that should be transferred to the other context instead of cloned.
     */
    postMessage(message: any, transfer?: Transferable[]): void;
    /**
     * Add a listener to messages received by the other context
     *
     * @param listener - A listener that will receive the MessageEvent
     * @returns A function that can be invoked to remove the listener
     */
    addMessageListener(listener: MessageListener): ListenerRemover;
}
/**
 * A concrete implementation of {@link Messenger} used to communicate with another Window.
 *
 * @public
 *
 */
export declare class WindowMessenger implements Messenger {
    postMessage: (message: any, transfer?: Transferable[]) => void;
    addMessageListener: (listener: MessageListener) => ListenerRemover;
    constructor({ localWindow, remoteWindow, remoteOrigin, }: {
        localWindow?: Window;
        remoteWindow: Window;
        remoteOrigin: string;
    });
}
interface Postable {
    postMessage(message: any, transfer?: Transferable[]): void;
    addEventListener(eventName: 'message', listener: MessageListener): void;
    removeEventListener(eventName: 'message', listener: MessageListener): void;
}
/** @public */
export declare class BareMessenger implements Messenger {
    postMessage: (message: any, transfer?: Transferable[]) => void;
    addMessageListener: (listener: MessageListener) => ListenerRemover;
    constructor(postable: Postable);
}
/**
 * A concrete implementation of {@link Messenger} used to communicate with a Worker.
 *
 * Takes a {@link Postable} representing the `Worker` (when calling from
 * the parent context) or the `self` `DedicatedWorkerGlobalScope` object
 * (when calling from the child context).
 *
 * @public
 *
 */
export declare class WorkerMessenger extends BareMessenger implements Messenger {
    constructor({ worker }: {
        worker: Postable;
    });
}
/**
 * A concrete implementation of {@link Messenger} used to communicate with a MessagePort.
 *
 * @public
 *
 */
export declare class PortMessenger extends BareMessenger implements Messenger {
    constructor({ port }: {
        port: MessagePort;
    });
}
/**
 * Create a logger function with a specific namespace
 *
 * @param namespace - The namespace will be prepended to all the arguments passed to the logger function
 * @param log - The underlying logger (`console.log` by default)
 *
 * @public
 *
 */
export declare function debug(namespace: string, log?: (...data: any[]) => void): (...data: any[]) => void;
/**
 * Decorate a {@link Messenger} so that it will log any message exchanged
 * @param messenger - The Messenger that will be decorated
 * @param log - The logger function that will receive each message
 * @returns A decorated Messenger
 *
 * @public
 *
 */
export declare function DebugMessenger(messenger: Messenger, log?: (...data: any[]) => void): Messenger;
export {};