Skip to main content

use-everywhere

Classes

ClassDescription
BroadcastChannelTransportSame-origin transport over a real BroadcastChannel.
HandshakeTimeoutErrorThe ready/ready-ack handshake never completed.
MemoryHubIn-memory hub for tests: N transports attached to one hub, each post is delivered to every other transport on a microtask (mirrors BroadcastChannel's async, no-self-echo delivery).
MemoryTransportOne simulated client on a MemoryHub. Create via hub.connect().
NoopTransportSilent local transport: nothing leaves this context, nothing arrives. Used for SSR and for state scoped to a single tab.
WindowClosedErrorThe opened window closed before delivering a result.

Interfaces

InterfaceDescription
BusEventOne wire crossing the bus, in either direction.
Channel-
ChannelHooksA channel bound to a name and message map: typed hooks with no per-call generics.
CommonOptions-
ConnectToOpenerOptions-
DebugOptions-
DefineStoreOptions-
Leader-
LeaderOptionsDeliberately extends CommonOptions, not BusOptions: heartbeatMs here means the leader's re-announce interval, which is a different thing from the bus's presence ping. See the note in leader.ts about forwarding to getBus.
LeaderSnapshot-
MessageEventLike-
MessageMeta-
OpenedWindow-
OpenerConnection-
OpenWindowOptions-
Peer-
PersistAdapter-
PersistedWhat goes to disk. The version clocks travel with the values — that is the whole point: a reopened tab re-enters the last-writer-wins race with its real term instead of a fresh zero, so a restored value can legitimately beat, or legitimately lose to, whatever the live tabs are holding.
PersistOptions-
Presence-
PresenceOptions-
SharedStore-
SharedStoreOptions-
StoreHooksA store bound to a name and a shape: typed hooks with no per-call generics.
TransportMinimal message bus. Implementations: BroadcastChannelTransport (same-origin), NoopTransport (SSR / local-only), MemoryTransport (tests). A transport never echoes a client's own posts back to it.
UseLeaderOptionsDeliberately extends CommonOptions, not BusOptions: heartbeatMs here means the leader's re-announce interval, which is a different thing from the bus's presence ping. See the note in leader.ts about forwarding to getBus.
UseOpenedWindow-
UseSharedStateOptions-
WindowEventTargetThe subset of Window we listen on (our side).
WindowLikeThe subset of Window we post to (the other side).

Type Aliases

Type AliasDescription
AnyStoreRegistry stores hold arbitrary keys — shape is decided by the hooks using them.
BusObserver-
BusWireEverything on the same-origin bus, multiplexed by scope over one BroadcastChannel per name.
MessageMap-
OpenedWindowStatus-
PeerKind-
ShareScopeHow far a shared value travels: - 'everywhere' — every tab, window, and worker on this origin (default) - 'tabs' — tabs and windows only; writes coming from workers are ignored - 'tab' — this tab only (state is still shared between components)
StorageLike-
VersionPer-key logical clock: [counter, clientId]. Ties break by clientId.

Variables

VariableDescription
CID_PARAM-
DEFAULT_NAMEThe bus name used when a caller does not pick one. A BroadcastChannel is global to the origin, so identity is the name string — everything that omits a name lands on this one bus.

Functions

FunctionDescription
connectToOpenerCall from the opened (child) window to connect back to its opener. Throws synchronously when there is no opener or no ue-cid parameter — i.e. the page was not opened via openWindow().
createChannelTyped pub/sub over the same-origin bus.
createLeaderElects exactly one client on the bus to hold a seat: the tab that owns the WebSocket, polls, or refreshes the token, while the others stand by.
createPresenceTracks the other tabs/windows/workers on this bus. Any message from a peer counts as a liveness signal (state patches, events, and presence pings all piggyback); explicit 'bye' or silence past pruneAfterMs removes them.
createSharedStoreState synced across every same-origin tab/window/worker: per-key last-writer-wins version clocks and a hello/snapshot late-joiner handshake. Create at most one store per name per tab (the React package memoizes).
defaultTransportDefault factory: real BroadcastChannel when available, otherwise a local no-op.
defineChannelBind a channel name and message map once, at module level, and get fully typed hooks back. Sugar over useChannel/useMessage/useSend — the same page-wide channel singleton is shared, so mixing bound and standalone hooks for one name is safe.
defineStoreBind a store name — and optionally persistence — once, at module level.
enableDebugLog every wire on a bus to the console. Returns a function to stop.
getBusNamesNames of the buses currently alive on this page. Buses built with a custom transport (tests) bypass the registry, so they are not listed.
getLeaderOne Leader per name per tab. Eligibility is deliberately not part of the key: two Leaders on one name would share a bus and a clientId, and since a post never loops back locally, neither would ever see the other's claims. Timing options are first-wins, like every other engine here.
getSharedStoreImperative access to the store behind useSharedState (patch logs, non-React code).
isBroadcastChannelAvailable-
localStorageAdapterSurvives closing every tab.
newerIs a newer than b? Last-writer-wins; equal counters break ties by clientId.
observeBusWatch every wire crossing the named bus, in both directions. Outbound wires are the interesting half: a post goes straight to the transport, so without this seam nothing this client says is visible to it.
openWindowOpen a window (possibly on another origin) and get a typed 1:1 channel to it. The child must call connectToOpener(). Every received message is validated: event.origin, envelope brand, per-connection nonce, and event.source.
sessionStorageAdapterSurvives reloads, but dies with the tab.
useChannelGet the page-wide typed channel for name (one instance per name).
useClientIdThis client's own id on the presence bus (matches patch origin ids).
useIsLeaderIs this tab the leader?
useLeaderWho currently holds the seat on this bus, and whether it is us. Exactly one tab leads; opening another does not steal it, and closing the leader hands it over at once.
useLeaderEffectRun an effect only in the tab that holds the seat, and tear it down when the seat moves. The one place to put "exactly one tab owns the socket".
useMessageSubscribe to one message type. The handler is kept fresh without resubscribing, so it may close over render state.
useOpenedWindowDrive an openWindow() flow from a component: the factory is called on open(), and the child window's lifecycle is folded into render state. Reopening replaces the previous window; a stale window's outcome is ignored.
usePeersThe other tabs/windows/workers currently alive on this origin.
useSendThe channel's post function (stable identity per channel).
useSharedStateLike useState, but the value exists in every tab, window, and worker on this origin. Late-joining tabs hydrate to the current value; concurrent writes converge last-writer-wins. Pass options.scope to delimit how much is shared ('everywhere'
webStorageAdapterPersist to any Storage-shaped thing.