@r_wohl/web-channel-message/dist/index.d.mts

A light weight type-safe library for communicating via the Channel Message Web API

type ActionType = "broadcast" | "all";
type ObserverMessage = {
    type: "observer";
    key?: string;
    action: ActionType;
    payload?: any;
};
type CallbackMessage = {
    type: "callback";
    callbackKey: string;
    action: ActionType;
    payload?: any;
};
type CloseMessage = {
    type: "close";
};
type ConnectionUpdate = {
    type: "internal";
    channelData: {
        connections: number;
    };
};
type InternalMessage = CloseMessage | ConnectionUpdate;
type UserMessage = CallbackMessage | ObserverMessage;
type Message = UserMessage | InternalMessage;

declare class ChannelObserver {
    private onUpdate;
    /**
     * Constructs a new `ChannelObserver` instance, that immediately subscribes to the provided channel's subject.
     * When the `SharedWebChannel` receives a message with action set to `observer`, it will update it's subject's subscribed observers.
     * If a `key` is provided then only messages with that key or `key: "all"` will trigger it's `onUpdate` function.
     *
     * @example
     *
     * const observer = new ChannelObserver(channel, (message) => {
     *     const payload = message.payload as MyCustomType;
     *
     *     if (payload) {
     *         handlePayload(payload);
     *     }
     * });
     *
     * //and to cleanup the observer:
     *
     * channel.subject.unsubscribe(observer);
     */
    constructor(channel: SharedWebChannel, onUpdate: (data: ObserverMessage) => any, key?: string);
    update: <R>(data: ObserverMessage) => R | void;
}

declare class SimpleSubject {
    private observers;
    subscribe(observer: ChannelObserver, key?: string): void;
    unsubscribe(observer: ChannelObserver, key?: string): void;
    update(data: ObserverMessage): void;
}

declare class SharedWebChannel {
    worker: SharedWorker | undefined;
    subject: SimpleSubject;
    connections: number;
    private connectionsUpdateCallback;
    /**
     * Constructs a new SharedWebChannel instance. If you'll need more then one
     * instance throughout your application, it is recommended to provide a name.
     *
     * When omitted, the name will default to "default-shared-worker".
     *
     */
    constructor(name?: string);
    private updateObservers;
    /**
     * Sends a `UserMessage` object to the SharedWorker
     * so it can be forwarded to other active channels.
     *
     * @example
     *
     * channel.sendMessage({
     *   //type: "callback" to trigger a callback function with corresponding callbackKey or "observer" to update one or more ChannelObservers.
     *   type: "callback",
     *  // action: "broadcast" to send to all OTHER app instances or "all" to send to all.
     *   action: "broadcast",
     *  // payload: optional; in "callback" mode this will be your callback's input
     *   payload: "bg-red-500",
     *   callbackKey: "set-bg-color",
     *});
     *
     */
    sendMessage(message: UserMessage): void;
    /**
     * Registers a callback with a key in a Map object. When a message sent with type `callback`
     * is received the `SharedWebChannel` will look for a callback with the corresponding
     * `callbackKey`, and -if found- execute it with the value in `payload` as input.
     *
     * @example
     *
     * channel.registerCallback("set-bg-color", setBgColor);
     *
     */
    registerCallback(key: string, callback: (...args: any[]) => any): void;
    /**
     * Registers a callback to be executed when the number of open connections
     * (the number of open browser session in different tabs/windows) changes.
     *
     * @example
     *
     * channel.onConnectionsUpdate(setInstances);
     *
     */
    onConnectionsUpdate(callback: (...args: any[]) => any): void;
    private terminate;
}

export { type ActionType, ChannelObserver, type Message, SharedWebChannel };