Nexus State Concepts
Understand the model and semantics behind Nexus State.
This Nexus State guide explains the mental model behind synchronized remote state.
Remote Store, Not Fake Local Store
Nexus State is not pretending that remote state is local memory.
Instead, Nexus State gives you a model with explicit rules:
- the host owns the authoritative state
- the client owns a mirrored local snapshot
- reads are synchronous from the mirror
- writes execute remotely on the host
- updates arrive through subscription events
That is why getState() is sync on the client, while actions are async.
Host And Client
There are always two sides in Nexus State.
Host
The host:
- owns the real store state
- executes actions
- advances versions
- publishes snapshot updates to subscribed clients
- cleans up connection-owned subscriptions on disconnect
Client
The client:
- connects through ordinary Nexus targeting
- receives an atomic subscribe baseline
- receives an initial snapshot and a live subscription in one setup step
- maintains a local mirror
- exposes
getState()andsubscribe()like a local store - turns connection loss into explicit lifecycle status
One Concrete Flow
The smallest useful Nexus State end-to-end flow is:
- define a store contract
- host it in one Nexus context
- connect to it from another context
- receive an initial snapshot and create a local mirror
- read from the mirror synchronously with
getState() - call actions asynchronously on the host
- receive later snapshots through subscription updates
Why Not Just Proxy A Store Object?
Because a raw remote object proxy gives the wrong mental model.
If you proxy a store directly, users naturally assume:
- reads are local
- writes are immediate
- lifecycle is invisible
None of those are true across contexts.
Nexus State makes the remote nature explicit without forcing you to hand-write subscription and action protocol boilerplate each time.
Status Model
RemoteStore exposes observable initializing, ready, disconnected,
stale, and destroyed states. See Lifecycle and errors
for the state meanings and failure behavior.
Headless Core vs Hook-Level Lifecycle
Keep these two layers separate:
- headless core (
connectNexusStore/RemoteStore) - React ownership (
useRemoteStoreand scoped selection), with direct selection through Zustand’suseStore
Headless core behavior:
- initial connect failure means
connectNexusStore(...)rejects (or safe API returnsErr) - no
RemoteStoreinstance exists from that failed attempt - once a
RemoteStorereaches a terminal state (disconnected,stale,destroyed), replacement means creating a new instance
Hook-level behavior:
- the owner hook exposes
pending,store, and acquisitionerror; lifecycle status is observed separately withuseStoreStatusorScope.useStatus - hooks may create a replacement
RemoteStorehandle, but they do not make a terminal handle usable again
See the Nexus State React guide for reconnectKey, reconnect(),
selector fallback, and target changes.
Full Snapshots
Nexus State synchronizes full snapshots, not public patch streams.
That means:
- simpler semantics
- easier validation
- stronger correctness story
- fewer protocol edge cases
The implementation keeps room for future patch-like optimization, but the public model is snapshot-based today.
Why Actions Wait For Publication
When you call:
await remoteStore.actions.increment(1);the promise waits for the caller’s ordinary Core function call and its fixed publication-window acknowledgement. It is not a receipt or waiter protocol. The action may already have mutated the host if the call later fails; do not automatically retry non-idempotent actions.
After a successful await, the caller’s mirror has acknowledged the targeted snapshot, but later host updates may already have been published or may still be pending. Snapshots are complete projections, may skip intermediate versions, and the client ignores older versions.
This is one of the most important semantics in the system.
For terminal handles, replacement, and session-bound Core handles, see Lifecycle and errors.