nexus
Nexus State

Nexus State Core API

Reference the headless Nexus State store and subscription APIs.

This Nexus State guide covers the public @nexus-js/core/state surface.

Exports

Current public entrypoint:

import {
  createStoreToken,
  createNexusStore,
  bindNexusStore,
  connectNexusStore,
  safeConnectNexusStore,
  safeInvokeStoreAction,
} from "@nexus-js/core/state";

Types and errors are also exported from the same subpath.

Shared Store Token

Declare one shared store type containing data and methods. The token derives snapshot and remote-action types internally; callers do not describe the wire service.

interface CounterStore {
  count: number;
  increment(by?: number): number;
}

const counterStore = createStoreToken<CounterStore>("app:counter");

Responsibilities

The StoreToken carries:

  • the store identity
  • the shared store contract
  • optional state and action validation through validation

Notes

  • pass the StoreToken directly to State APIs, without a { token } wrapper
  • connection targeting is supplied by the State connection options, not by the StoreToken
  • host-side state and actions are supplied separately to createNexusStore() as a native Zustand StateCreator
  • store actions must use serializable arguments/results
  • synchronization publishes full snapshots

RemoteStore<CounterStore> derives data-only reads and asynchronous methods from the same contract. createStoreToken<Store, Model>(id, options) supports typed adapter association and optional validation: { state, actionResults } schemas. Use space.storeToken<Store>(name, options?) or space.safeStoreToken<Store>(...) with TokenSpace to inherit namespaced IDs. A local store may contain additional private fields; snapshot and expose still define the runtime sharing boundary.

Validation schemas

State and action-result validators accept synchronous Standard Schema implementations, including Valibot, Zod, and Zod Mini. Nexus uses Valibot for its own protocol schemas; applications can keep their preferred validator.

import * as v from "valibot";

const validatedCounterStore = createStoreToken<CounterStore>("app:counter", {
  validation: {
    state: v.object({ count: v.number() }),
    actionResults: { increment: v.number() },
  },
});

Validators must check the actual snapshot or action-result shape. Nexus preserves the original value: defaults and transformed outputs are not installed in a mirror or returned instead of an action result. A coercing or transforming validator’s output type does not establish the original value’s type. The TypeScript contract constrains the validator’s output type; it does not statically check input compatibility. Unknown-input validators are supported.

Validation must return synchronously. Asynchronous validators are rejected with E_STORE_PROTOCOL; they do not delay publication. Thrown validation errors are also converted to State protocol errors.

createNexusStore()

createNexusStore() creates one authoritative store host and returns the Nexus provider, the original Zustand store, and binding lifecycle methods.

const { provider, store, destroy } = createNexusStore(
  counterStore,
  (set, get) => ({
    count: 0,
    increment(by = 1) {
      const count = get().count + by;
      set({ count });
      return count;
    },
  }),
  {
    snapshot: (local) => ({ count: local.count }),
    expose: ["increment"],
  },
);

nexus.configure({
  providers: [provider],
});

console.log(store.getState());
console.log(store.getInitialState());

Use provider with nexus.configure({ providers: [provider] }). Use store only in the hosting context for local authoritative reads, subscriptions, and actions.

store is the original Mutate<StoreApi<...>> returned by Zustand. It keeps the creator’s middleware mutator types and extensions. Local actions continue to use store.getState().action() and do not wait for Nexus publication.

const { store } = createNexusStore(counterStore, creator, options);

The binding result supports using through [Symbol.dispose](); scope exit delegates to the same synchronous, idempotent destroy() transition. Destroy does not destroy the original Zustand store.

The binding does not replace or recreate Zustand’s API. Its snapshot function is the complete shared data projection, and expose is the runtime action allowlist. Validation schemas validate payloads; parsed transform outputs are not installed into the source or remote store.

bindNexusStore()

Use bindNexusStore(token, existingStore, options) for an already-created Zustand store, including one composed with persist, immer, devtools, or subscribeWithSelector. The same options apply to both creation paths.

const binding = bindNexusStore(counterStore, store, {
  snapshot: (local) => ({ count: local.count }),
  expose: ["increment"],
});

binding.destroy(); // store remains usable

publishWindowMs is a fixed window beginning with the first update (default 200ms), not a debounce; action completion does not force a flush. maxPendingSnapshots defaults to 32. A subscription that exceeds this budget or fails to acknowledge a callback within five seconds is stopped, without closing other services on the shared connection. Terminal notification is best effort; State does not retry failed actions or replay snapshots automatically.

connectNexusStore()

Connects to a remote Nexus State store and returns a RemoteStore.

import { chromeTarget } from "@nexus-js/chrome";

const remote = await connectNexusStore(nexus, counterStore, {
  target: chromeTarget.background(),
});

Key behavior

  • accepts Core ConnectOptions: target, where, positive finite timeout, and signal
  • acquires a connection, then checks its current service catalog; it does not wait for a missing provider
  • establishes the initial snapshot and live subscription through one callback-init setup
  • initializes the local mirror from the baseline
  • returns no Store handle when the handshake fails

Each subscription uses an explicit Core resource scope automatically. Destroying the mirror closes that scope without closing the shared Connection. A Relay path uses the same scope end to end; no relayNexusStore helper is needed.

The init callback supplies the initial state, the raw Core function proxies for each action, and an idempotent unsubscribe capability. State does not add an action-name dispatch protocol or wrap those action proxies. Consequently, direct action failures retain Core error codes such as E_CONN_CLOSED, E_CALL_TIMEOUT, and E_RESOURCE_ACCESS_DENIED; safeInvokeStoreAction() may normalize them only at its public safe-result boundary.

Timeout boundaries remain separate: a supplied timeout bounds connection acquisition and then separately bounds callback-init setup. It is not one shared end-to-end deadline. signal cancels connection acquisition only; it does not cancel a subscription handshake that has already started or destroy a returned store. Action calls use Core’s existing resource-call timeout defaults; State does not translate the acquisition timeout into Core’s callTimeout option.

Lifecycle boundary:

  • the returned RemoteStore is a session-bound handle
  • if the underlying session is replaced, create a new handle with connectNexusStore(...)
  • terminal handles are not revived in place
  • if the supplied where stops matching on an identity update, the State handle becomes stale; ordinary Connection proxies do not retain that predicate

If its resource scope closes, the mirror is terminal. Create a new subscription for a recovered route and fresh baseline; State does not replay actions or snapshot acknowledgements into an old mirror. See Nexus Relay and resource scopes.

safeConnectNexusStore()

Safe variant of connectNexusStore().

const result = await safeConnectNexusStore(nexus, counterStore, options);

if (result.isErr()) {
  console.error(result.error);
} else {
  const remote = result.value;
}

Use this when you want safe-first composition instead of throw-style flow.

Choosing Throw vs Safe

Use throw-style APIs when:

  • you want the most direct call sites
  • you already handle errors with try/catch
  • you are writing app code and want to optimize for readability first

Use safe-style APIs when:

  • your codebase already composes better-result Result / Promise<Result>
  • you want explicit error branching without exceptions
  • you are writing orchestration or infrastructure code where failure handling is part of the flow

Store Handle Types

RemoteStore is the client-side Store interface returned by connectNexusStore() and safeConnectNexusStore().

RemoteStore capabilities:

  • getState()
  • subscribe(listener)
  • getStatus()
  • subscribeStatus(listener)
  • destroy()
  • actions.*

RemoteStore supports getInitialState() and JavaScript using through [Symbol.dispose](). The local store returned by createNexusStore() is the original Zustand API; the binding result, not the store, owns destroy() and [Symbol.dispose]().

A remote Store handle is tied to one connection session. After it becomes disconnected, stale, or destroyed, create a replacement instead of reusing it.

On RemoteStore, getInitialState() returns the stable successful-handshake baseline. Later snapshots do not change it. Treat both initial and current state as immutable; repeated reads of the same snapshot preserve its identity.

Example

using remote = await connectNexusStore(nexus, counterStore, options);

const stop = remote.subscribe((state) => {
  console.log(state.count);
});

await remote.actions.increment(1);

console.log(remote.getStatus());

stop();

using delegates to the same synchronous, idempotent terminal transition as destroy(). It starts the existing best-effort remote unsubscribe but does not add an acknowledgement or asynchronous cleanup guarantee.

safeInvokeStoreAction()

Single safe helper for Nexus State action invocation.

const result = await safeInvokeStoreAction(remote, "increment", [1]);

if (result.isErr()) {
  console.error(result.error.code, result.error.message);
} else {
  console.log(result.value);
}

This exists to avoid generating a second mirrored safeActions.* tree for every store.

Errors

Important Nexus State public errors include:

  • NexusStoreConnectError
  • NexusStoreDisconnectedError
  • NexusStoreActionError
  • NexusStoreProtocolError

Use these when you want to distinguish connection failure, disconnect, remote action failure, and protocol corruption.

Edit this page on GitHub