{"id":25480115,"url":"https://github.com/rexerwang/channelstate","last_synced_at":"2026-02-25T21:05:37.947Z","repository":{"id":277855873,"uuid":"933737571","full_name":"rexerwang/channelstate","owner":"rexerwang","description":"✨ A lightweight cross-context state management library built on the BroadcastChannel API.","archived":false,"fork":false,"pushed_at":"2025-03-20T15:09:32.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-12T05:52:30.413Z","etag":null,"topics":["broadcastchannel","channelstate","react","state-management"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rexerwang.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-02-16T15:27:53.000Z","updated_at":"2025-03-20T15:09:36.000Z","dependencies_parsed_at":"2025-02-16T16:36:15.065Z","dependency_job_id":"f0f6bc9c-1581-4ac3-ade9-82e2445afd97","html_url":"https://github.com/rexerwang/channelstate","commit_stats":null,"previous_names":["rexerwang/channelstate"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/rexerwang/channelstate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexerwang%2Fchannelstate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexerwang%2Fchannelstate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexerwang%2Fchannelstate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexerwang%2Fchannelstate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rexerwang","download_url":"https://codeload.github.com/rexerwang/channelstate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rexerwang%2Fchannelstate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29839980,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T20:42:33.054Z","status":"ssl_error","status_checked_at":"2026-02-25T20:42:21.322Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["broadcastchannel","channelstate","react","state-management"],"created_at":"2025-02-18T15:27:29.642Z","updated_at":"2026-02-25T21:05:37.941Z","avatar_url":"https://github.com/rexerwang.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ChannelState\n\n[![](https://img.shields.io/npm/v/channelstate)](https://www.npmjs.com/package/channelstate)\n[![test](https://github.com/rexerwang/channelstate/actions/workflows/test.yml/badge.svg)](https://github.com/rexerwang/channelstate/actions/workflows/test.yml)\n\nChannelState 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.\n\n```sh\nnpm install channelstate\n```\n\n## Key Features\n\n- 🌐 Cross-context state synchronization (tabs/windows/iframes)\n- ⚡ BroadcastChannel-based efficient communication\n- 🧩 React Hooks integration (useChannelState)\n- 🔒 Strong consistency guarantees (Primary-Replica protocol)\n- 📦 Type-safe implementation (TypeScript first)\n\n## Architectural Design\n\nThe `ChannelState` implements a `Primary-Replica` pattern with a single-writer/multiple-reader approach to ensure cross-context data consistency.\n\n```mermaid\ngraph TD\n  subgraph ChannelState Architecture\n    Primary[Primary Instance\u003cbr/\u003e- Read/Write Permissions\u003cbr/\u003e- State Coordinator]\n    Replica1[Replica Instance #1\u003cbr/\u003e- Read-only Replica\u003cbr/\u003e- Auto-sync]\n    Replica2[Replica Instance #2\u003cbr/\u003e- Read-only Replica\u003cbr/\u003e- Auto-sync]\n  end\n\n  Replica1 -- \"Write Proxy Requests\" --\u003e Primary\n  Replica2 -- \"Write Proxy Requests\" --\u003e Primary\n  Primary -- \"State Change Broadcasts\" --\u003e Replica1\n  Primary -- \"State Change Broadcasts\" --\u003e Replica2\n```\n\n### Primary Instance\n\n- Sole instance with direct write privileges\n- Created via [createPrimaryChannelState](./src/channel/createPrimaryChannelState.ts)\n- Responsibilities:\n  - Process write proxy requests from replicas\n  - Maintain authoritative state version\n  - Broadcast state changes\n  - Constraint: **Only one Primary instance allowed per channel**\n\n### Replica Instance\n\n- Created via [createReplicaChannelState](./src/channel/createReplicaChannelState.ts)\n- Features:\n  - Automatic synchronization with Primary instance\n  - Write operations proxied through Primary\n  - Supports unlimited replicas\n\n\u003e [!IMPORTANT]\n\u003e Critical Constraints\n\u003e\n\u003e 1. Channel Uniqueness: Single instance (Primary or Replica) per channelName per browser context\n\u003e 2. Primary Singleton: Multiple Primary instances in the same channel will break synchronization\n\u003e 3. Context Isolation: Each browser tab/window maintains independent instance topology\n\n### API Style\n\nThe API style of `ChannelState` is similar to `Zustand` and provides React integration (`useChannelState`).\n\n## Compatibility\n\n`ChannelState` is compatible with modern browsers that support the [BroadcastChannel API](https://caniuse.com/?search=BroadcastChannel). This includes:\n\n- Chrome 54+\n- Firefox 38+\n- Edge 79+\n- Safari 15.4+\n- Opera 41+\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frexerwang%2Fchannelstate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frexerwang%2Fchannelstate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frexerwang%2Fchannelstate/lists"}