https://github.com/rexerwang/channelstate
✨ A lightweight cross-context state management library built on the BroadcastChannel API.
https://github.com/rexerwang/channelstate
broadcastchannel channelstate react state-management
Last synced: 4 months ago
JSON representation
✨ A lightweight cross-context state management library built on the BroadcastChannel API.
- Host: GitHub
- URL: https://github.com/rexerwang/channelstate
- Owner: rexerwang
- License: mit
- Created: 2025-02-16T15:27:53.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-20T15:09:32.000Z (about 1 year ago)
- Last Synced: 2025-09-12T05:52:30.413Z (9 months ago)
- Topics: broadcastchannel, channelstate, react, state-management
- Language: TypeScript
- Homepage:
- Size: 90.8 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ChannelState
[](https://www.npmjs.com/package/channelstate)
[](https://github.com/rexerwang/channelstate/actions/workflows/test.yml)
ChannelState is a lightweight cross-context state management library built on the [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel), designed to provide efficient state synchronization across **same-origin** browser tabs, windows, and iframes.
```sh
npm install channelstate
```
## Key Features
- 🌐 Cross-context state synchronization (tabs/windows/iframes)
- ⚡ BroadcastChannel-based efficient communication
- 🧩 React Hooks integration (useChannelState)
- 🔒 Strong consistency guarantees (Primary-Replica protocol)
- 📦 Type-safe implementation (TypeScript first)
## Architectural Design
The `ChannelState` implements a `Primary-Replica` pattern with a single-writer/multiple-reader approach to ensure cross-context data consistency.
```mermaid
graph TD
subgraph ChannelState Architecture
Primary[Primary Instance
- Read/Write Permissions
- State Coordinator]
Replica1[Replica Instance #1
- Read-only Replica
- Auto-sync]
Replica2[Replica Instance #2
- Read-only Replica
- Auto-sync]
end
Replica1 -- "Write Proxy Requests" --> Primary
Replica2 -- "Write Proxy Requests" --> Primary
Primary -- "State Change Broadcasts" --> Replica1
Primary -- "State Change Broadcasts" --> Replica2
```
### Primary Instance
- Sole instance with direct write privileges
- Created via [createPrimaryChannelState](./src/channel/createPrimaryChannelState.ts)
- Responsibilities:
- Process write proxy requests from replicas
- Maintain authoritative state version
- Broadcast state changes
- Constraint: **Only one Primary instance allowed per channel**
### Replica Instance
- Created via [createReplicaChannelState](./src/channel/createReplicaChannelState.ts)
- Features:
- Automatic synchronization with Primary instance
- Write operations proxied through Primary
- Supports unlimited replicas
> [!IMPORTANT]
> Critical Constraints
>
> 1. Channel Uniqueness: Single instance (Primary or Replica) per channelName per browser context
> 2. Primary Singleton: Multiple Primary instances in the same channel will break synchronization
> 3. Context Isolation: Each browser tab/window maintains independent instance topology
### API Style
The API style of `ChannelState` is similar to `Zustand` and provides React integration (`useChannelState`).
## Compatibility
`ChannelState` is compatible with modern browsers that support the [BroadcastChannel API](https://caniuse.com/?search=BroadcastChannel). This includes:
- Chrome 54+
- Firefox 38+
- Edge 79+
- Safari 15.4+
- Opera 41+