@broadcaster/core
Version:
Cross window serverless messaging system based on BroadcastChannel API. Allows to send messages and keep track about instances between browsing contexts (tabs, windows, workers, etc..)
184 lines (183 loc) • 5.96 kB
TypeScript
import { BroadcasterInstanceDescriptor } from "./types";
import { BroadcasterError } from "./utils/Errors";
import { BroadcasterMessage, BroadcasterSettings } from "./types";
/**
* **Broadcaster: Cross Window Serverless Messaging System**
*
* Enables seamless communication across various browsing contexts,
* including tabs, windows, and workers. This system not only preserves
* the state of each instance but also shares the current state with
* remote counterparts.
*
* @public
* @typeParam Payload message shape
* @typeParam Metadata metadata object shape
*/
export declare class Broadcaster<Payload, Metadata> {
private settings;
/**
* List of states of all active broadcasters
*/
private _broadcasters;
get broadcasters(): Readonly<Broadcaster<Payload, Metadata>["_broadcasters"]>;
/**
* Bridge instance (BroadcasterChannel, WebSockets, etc..)
*/
private bridge;
/**
* When Broadcaster instance was created
*/
readonly createdAt: number;
/**
* Channel name is unique ID, which is used as a key for messaging
*/
readonly channel: string;
/**
* Indicates whether destroy method was called or not
*/
private closed;
/**
* Random ID of an instance
*/
readonly id: string;
/**
* Current metadata
*/
private metadata;
private intervals;
private messageSubscriptionManager;
private broadcastersSubscriptionManager;
private broadcastersErrorManager;
constructor(settings: BroadcasterSettings<Payload, Metadata>);
/**
* Propagates changes in metadata descriptors to all subscribers
*/
private broadcastersUpdated;
/**
* Cancel a connection to a channel and notify other Broadcasters about it.
*
* @param silent skips multi call detection
*/
close(silent?: boolean): void;
/**
* Marks as disabled all broadcasters which are inactive for specific amount of time.
* Removes those who cross removeAfter threshold.
*/
private collectGarbage;
/**
* Find Broadcaster instance based on its ID.
*
* @param ownerId Broadcaster instance ID
* @returns Broadcaster instance which id matches ownerId attribute
*/
findOwner: (ownerId: string) => BroadcasterInstanceDescriptor<Metadata> | null;
/**
* Detects whether Broadcaster method can be triggered or not
*
* @param action
*/
private isBroadcasterActive;
private init;
get isClosed(): boolean;
/**
* Send a message to all instances of Broadcaster across browsing context.
*
* @param payload data payload
* _____
* @example```ts
*
* const broadcaster = new Broadcaster<string>({
* channel: "CHANNEL",
* });
*
* broadcaster.postMessage("Hello World");
* ```
*
* @param payload message payload
* @param to a id(s) of receivers
*/
postMessage: (payload: Payload, to?: BroadcasterMessage<Payload>["to"]) => void;
/**
* Creates a new state message
*
* @param type message type
* @param to message receiver id
* @param withoutState
* @returns
*/
private prepareStateMessage;
/**
* Push new message to all subscribers
*
* @param data Broadcaster message
*/
private pushMessage;
/**
* Updates Broadcaster instance metadata and notify other instances about the change.
* ____
*
* @example```ts
* // override metadata
* broadcasterInstance.updateMetadata({name: "John"});
* // update metadata
* broadcasterInstance.updateMetadata((current) => ({...current, lastName: "Doe"}));
*
* // all broadcasters will receive new state with updated metadata
* ```
* @param newMetadata data to override or a method with current state as an attribute
*/
updateMetadata: (newMetadata: Metadata | ((current: Metadata) => Metadata)) => void;
private sendAliveMessage;
/**
* Subscribes to selected channel.
* ____
* @example```ts
* const callback = (message: string) => console.log(message);
*
* const subscription = broadcasterInstance.subscribe.message(callback);
*
* //...later
* subscription.unsubscribe();
* // or
* broadcaster.unsubscribe.message(callback);
* ```
*/
subscribe: {
message: (callback: (args_0: BroadcasterMessage<Payload>) => void, complete?: ((...args: never[]) => void) | undefined) => {
unsubscribe: () => void;
};
broadcasters: (callback: (args_0: BroadcasterInstanceDescriptor<Metadata>[]) => void, complete?: ((...args: never[]) => void) | undefined) => {
unsubscribe: () => void;
};
errors: (callback: (args_0: BroadcasterError) => void, complete?: ((...args: never[]) => void) | undefined) => {
unsubscribe: () => void;
};
};
private stateToDescriptor;
/**
* Unsubscribes from the selected channel.
* ____
* @example```ts
* const callback = (message: string) => console.log(message);
*
* broadcaster.subscribe.message(callback);
* broadcaster.subscribe.broadcasters(callback);
*
* //...later
* broadcaster.unsubscribe.message(callback);
* broadcaster.unsubscribe.broadcasters(callback);
* ```
*/
unsubscribe: {
message: (callback: (args_0: BroadcasterMessage<Payload>) => void) => void;
broadcasters: (callback: (args_0: BroadcasterInstanceDescriptor<Metadata>[]) => void) => void;
errors: (callback: (args_0: BroadcasterError) => void) => void;
};
/**
* Updates broadcasters based on remote message
*
* @param data remote state message
* @param localUpdate if true, it will always update broadcasters list, but never take any other action
*/
private updateBroadcasterDescriptor;
}