tabs-broadcast
v3.1.12
Published
Library for managing inter-tab communication
Downloads
200
Maintainers
Readme
TabsBroadcast
TabsBroadcast is a library for managing inter-tab communication via the BroadcastChannel API. It implements a singleton pattern to ensure a single instance and allows for registering, emitting, and handling various types of events across different browser tabs. The library also manages primary and slave tabs, ensuring that only one tab is designated as the primary tab, which can perform certain tasks exclusively.
License
This project is licensed under the MIT License. See the LICENSE file for details.
Author
- Andrei (Ravy) Rovnyi
- [email protected]
Features
- Singleton pattern to ensure a single instance.
- Inter-tab communication using the BroadcastChannel API.
- Primary-Slave tab management.
- Event registration and handling.
- Emit messages to all tabs or only from the primary tab.
- Configurable settings.
Demo
You can access the live demo at the following URL:
Installation
You can install the library using npm, pnpm, yarn or bun:
npm install tabs-broadcast
or
pnpm install tabs-broadcast
or
yarn add tabs-broadcast
or
bun install tabs-broadcast
Usage
To use the library, import the TabsBroadcast class and initialize it:
Importing the Library
import TabsBroadcast from 'tabs-broadcast';
Creating an Instance
const tabsBroadcast = new TabsBroadcast({
channelName: 'myChannel',
listenOwnChannel: true,
onBecomePrimary: (detail) => console.log('Became primary tab:', detail),
emitByPrimaryOnly: true
});
Config Options
channelName
: The name of the BroadcastChannel. Using for multiple instance per site.listenOwnChannel
: Whether the tab should listen to its own emitted messages.onBecomePrimary
: Callback function when the tab becomes the primary tab.emitByPrimaryOnly
: Whether only the primary tab can emit messages.
Methods
on(message: string, callback: (data: any) => void): void
Register a callback to be executed whenever a message of the specified type is received.
tabsBroadcast.on('eventType', (data) => {
console.log('Event received:', data);
});
onList(list: Array<[string, Function]>): void
Register multiple callbacks to be executed whenever messages of specified types are received.
tabsBroadcast.onList([
['eventType1', (data) => console.log('Event 1 received:', data)],
['eventType2', (data) => console.log('Event 2 received:', data)],
['eventType3', (data) => console.log('Event 3 received:', data)]
]);
once(message: string, callback: (data: any) => void): void
Register a callback to be executed only once when a message of the specified type is received.
tabsBroadcast.once('eventType', (data) => {
console.log('One-time event received:', data);
});
onceList(list: Array<[string, Function]>): void
Register multiple callbacks to be executed one-time when messages of specified types are received.
tabsBroadcast.onceList([
['eventType1', (data) => console.log('One-time event 1 received:', data)],
['eventType2', (data) => console.log('One-time event 2 received:', data)],
['eventType3', (data) => console.log('One-time event 3 received:', data)],
]);
off(message: string): void
Unregister all callbacks of the specified type.
tabsBroadcast.off('eventType');
emit(message: string, data?: any): void
Emit a message to all listening tabs with the specified type and payload.
tabsBroadcast.emit('eventType', { key: 'value' });
tabsBroadcast.emit('eventType', 'Hello World');
tabsBroadcast.emit('eventType');
isPrimary(): boolean
Check if the current tab is the primary tab.
if (tabsBroadcast.isPrimary()) {
console.log('This is the primary tab.');
}
setConfig(config: TDefaultConfig): void
Set custom configuration properties.
tabsBroadcast.setConfig({
channelName: 'newChannelName',
listenOwnChannel: false,
onBecomePrimary: (detail) => console.log('New primary tab:', detail),
emitByPrimaryOnly: true
});
destroy(): void
Destroy the BroadcastChannel. Messages will no longer be received.
tabsBroadcast.destroy();
getEvents() : TCallbackItem[]
Receive a copy of the registered events list.
const events = tabsBroadcast.getEvents();
console.log('Registered events:', events);
Primary-Slave Tab Management
The library ensures that one tab is marked as the primary tab and others as slave tabs. When the primary tab is closed, another tab is promoted to the primary status.
Example Usage
window.addEventListener('load', () => {
const tabsBroadcast = new TabsBroadcast({
onBecomePrimary: (detail) => console.log('This tab became the primary tab:', detail),
});
tabsBroadcast.on('customEvent', (data) => {
console.log('Received custom event:', data);
});
if (tabsBroadcast.isPrimary()) {
tabsBroadcast.emit('customEvent', { message: 'Hello from the primary tab!' });
}
});
window.addEventListener('beforeunload', () => {
tabsBroadcast.destroy();
});
This example demonstrates how to create an instance of TabsBroadcast, register an event listener for a custom event, emit an event only from the primary tab, and handle the tab's unload event to destroy the BroadcastChannel.
Why Do I Need Primary-Slave Tab Management?
In modern web applications, users often open multiple tabs of the same application. Managing the state and interaction between these tabs efficiently is crucial. Primary-Slave Tab Management addresses several key challenges:
- Avoiding Conflicts: When multiple tabs attempt to perform the same actions (e.g., synchronizing data with the server), it can lead to conflicts and errors. Primary-Slave Tab Management designates one tab as the primary tab, responsible for executing such critical tasks, while the other tabs (slaves) perform auxiliary functions.
- Resource Optimization: Performing tasks (like background data synchronization or periodic updates) only in one tab reduces the load on the browser and server, significantly improving performance and lowering resource consumption.
- Centralized State Management: The primary tab can manage the shared state of the application and coordinate actions across all tabs. This ensures data consistency and predictable application behavior.
What Problems Can Primary-Slave Tab Management Solve?
- Data Synchronization: The primary tab can perform periodic data synchronization with the server and distribute updates to other tabs, ensuring data is up-to-date across all tabs.
- User Session Management: The primary tab can monitor user activity and manage sessions (e.g., automatic logout on inactivity), enhancing security and user experience.
- Notifications and Alerts: The primary tab can centrally handle notifications and alerts, preventing the user from receiving duplicate notifications in every tab.
- Load Distribution: In scenarios involving resource-intensive operations (e.g., processing large data sets), the primary tab can distribute tasks among other tabs, optimizing overall application performance.
Primary-Slave Tab Management is an effective way to improve performance, manage state, and enhance the reliability of web applications operating with multiple tabs.
TypeScript Support
This library fully supports TypeScript, providing type definitions for seamless integration with TypeScript projects. TypeScript users can leverage static typing to catch errors early in the development process and benefit from improved code editor support, including auto-completion and type checking.
Sponsorship and Support
If you have found this library useful and would like to support its continued development and maintenance, you can make a donation to the following TRC20 wallet address:
TFWHdvkHs78jrANbyYfAy6JaXVVfKQiwjv
Your donation will directly contribute to improving functionality, bug fixes, and ensuring long-term support for this library. Thank you for your support!