Nexus State Core API
不依赖 UI 的 Nexus State 存储与订阅 API 参考。
本页介绍 @nexus-js/core/state 的公共接口。
导出
当前公共入口:
import {
createStoreToken,
createNexusStore,
bindNexusStore,
connectNexusStore,
safeConnectNexusStore,
safeInvokeStoreAction,
} from "@nexus-js/core/state";类型和错误也从相同子路径导出。
共享 Store Token
声明一个包含数据和方法的共享存储类型。Token 会推导快照和远程动作类型,调用方无需手动定义底层通信服务。
interface CounterStore {
count: number;
increment(by?: number): number;
}
const counterStore = createStoreToken<CounterStore>("app:counter");职责
StoreToken 携带:
- 存储标识
- 共享存储契约
- 通过
validation提供的可选状态与动作校验
说明
- 将 StoreToken 直接传给 State API,无需包成
{ token } - 连接目标通过 State 连接选项传入,不放在 StoreToken 中
- 宿主状态和动作以原生 Zustand
StateCreator的形式单独传给createNexusStore() - 动作的参数与结果必须可序列化
- 状态同步发布完整快照
RemoteStore<CounterStore> 从同一契约推导只读数据和异步方法。
createStoreToken<Store, Model>(id, options) 支持绑定适配器模型,以及可选的 validation: { state, actionResults } 校验模式。
使用 TokenSpace 的 space.storeToken<Store>(name, options?) 或 space.safeStoreToken<Store>(...) 继承命名空间 ID。
本地存储可以包含额外的私有字段;运行时实际共享的数据和动作仍由 snapshot 与 expose 决定。
校验 Schema
状态和动作结果验证器接受同步的 Standard Schema 实现,包括 Valibot、Zod 和 Zod Mini。Nexus 内部协议使用 Valibot,应用可以继续使用自己的验证库。
import * as v from "valibot";
const validatedCounterStore = createStoreToken<CounterStore>("app:counter", {
validation: {
state: v.object({ count: v.number() }),
actionResults: { increment: v.number() },
},
});验证器应检查实际快照或动作结果的结构。Nexus 保留原始值:默认值和转换后的输出不会写入镜像,也不会替代动作结果。强制转换或 transform 的输出类型不能证明原始值具有该类型。
TypeScript 契约约束验证器的输出类型,不静态检查输入类型兼容性;支持输入类型为 unknown 的验证器。
验证必须同步返回。异步验证器会得到 E_STORE_PROTOCOL,不会延迟发布;验证器抛出的错误也会转换为 State 协议错误。
createNexusStore()
createNexusStore() 创建权威宿主存储,返回 Nexus 服务提供者、原始 Zustand 存储,以及绑定的生命周期方法。
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());通过 nexus.configure({ providers: [provider] }) 注册 provider。store 留在宿主上下文中,用于直接读取权威状态、订阅变化和调用本地动作。
store 是 Zustand 返回的原始 Mutate<StoreApi<...>>,保留创建器的中间件变更类型与扩展能力。
本地动作仍通过 store.getState().action() 调用,不等待 Nexus 发布状态。
const { store } = createNexusStore(counterStore, creator, options);返回的绑定对象通过 [Symbol.dispose]() 支持 using。离开作用域时,执行与 destroy() 相同的同步、幂等清理。
销毁绑定不会销毁原始 Zustand 存储。
绑定不替换或重建 Zustand API。snapshot 函数生成完整的共享数据投影,expose 是运行时动作白名单。
校验模式只验证传输数据;解析过程中变换后的输出不会写回源存储或远程镜像。
bindNexusStore()
已有 Zustand 存储时,使用 bindNexusStore(token, existingStore, options),包括通过 persist、immer、devtools 或 subscribeWithSelector 组合的存储。
两种创建方式使用相同选项。
const binding = bindNexusStore(counterStore, store, {
snapshot: (local) => ({ count: local.count }),
expose: ["increment"],
});
binding.destroy(); // store 仍可使用publishWindowMs 定义从首次更新开始的固定发布窗口,默认 200 毫秒,不是防抖间隔;动作完成也不会强制提前发布。
maxPendingSnapshots 默认 32。超过待确认快照上限,或回调在五秒内未获确认时,对应订阅会终止,但不影响共享连接上的其他服务。
终止通知尽力发送,不保证送达;State 不会自动重试失败动作或重放快照。
connectNexusStore()
连接远程 Nexus State 存储,返回 RemoteStore。
import { chromeTarget } from "@nexus-js/chrome";
const remote = await connectNexusStore(nexus, counterStore, {
target: chromeTarget.background(),
});关键行为
- 接受 Core
ConnectOptions:target、where、正有限数timeout和signal - 先获取连接,再检查当前服务目录,不等待缺失的服务提供者
- 通过一次初始化回调同时建立初始快照与持续订阅
- 根据基线快照初始化本地镜像
- 握手失败时不返回存储句柄
每个订阅都会自动使用显式 Core 资源域。销毁镜像会关闭该资源域,但不会关闭共享 Connection。Relay 路径也端到端使用同一资源域,无需 relayNexusStore helper。
初始化回调提供初始状态、每个动作对应的原始 Core 函数代理,以及幂等的取消订阅方法。
State 不添加按动作名分发的协议,也不再包装动作代理。因此直接调用动作时,失败会保留 E_CONN_CLOSED、E_CALL_TIMEOUT、E_RESOURCE_ACCESS_DENIED 等 Core 错误码;只有 safeInvokeStoreAction() 可能在返回公共 Result 时将错误归一化。
两个阶段分别计时:timeout 先限制获取连接的时间,再单独限制初始化回调的时间,并非整个流程共用一个截止时间。
signal 只取消连接获取,不取消已开始的订阅握手,也不销毁返回的存储。
动作调用使用 Core 资源调用的默认超时;State 不会将获取超时转换成 Core 的 callTimeout。
生命周期边界:
- 返回的
RemoteStore句柄绑定当前会话 - 底层会话被替换后,需要用
connectNexusStore(...)创建新句柄 - 已进入终态的句柄不会原地恢复
- 身份更新后不再满足
where时,State 句柄变为stale;普通 Connection 代理则不会持续检查该条件
资源域关闭后,镜像进入终态。路径恢复后请创建新订阅以取得完整基线;State 不会向旧镜像重放 action 或 snapshot acknowledgement。参阅 Nexus Relay 与资源域。
safeConnectNexusStore()
connectNexusStore() 的安全版本,以 Result 返回结果。
const result = await safeConnectNexusStore(nexus, counterStore, options);
if (result.isErr()) {
console.error(result.error);
} else {
const remote = result.value;
}需要显式组合 Result,而不是通过异常控制流程时,可以使用这个接口。
选择异常接口还是安全接口
以下情况适合使用抛出异常的接口:
- 希望调用点最直接
- 已经用
try/catch处理错误 - 编写应用代码,优先优化可读性
以下情况适合使用返回 Result 的安全接口:
- 代码库已经组合 better-result
Result/Promise<Result> - 需要无异常的显式错误分支
- 编写流程编排或基础设施代码,失败处理本身就是流程的一部分
存储句柄类型
RemoteStore 是 connectNexusStore() 和 safeConnectNexusStore() 成功时返回的客户端存储接口。
RemoteStore 能力:
getState()subscribe(listener)getStatus()subscribeStatus(listener)destroy()actions.*
RemoteStore 支持 getInitialState() 和通过 [Symbol.dispose]() 使用 JavaScript using。
createNexusStore() 返回的本地 store 保留原始 Zustand API;destroy() 和 [Symbol.dispose]() 位于绑定对象上,不在存储本身上。
远程存储句柄绑定一个连接会话。进入 disconnected、stale 或 destroyed 后,需要创建新句柄替换,不能继续复用。
RemoteStore.getInitialState() 返回握手成功时的基线快照,后续快照不会改变它。
初始状态和当前状态都应视为不可变数据;重复读取同一个快照时,对象引用保持一致。
示例
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 执行与 destroy() 相同的同步、幂等终止操作。
它会尝试向远端取消订阅,但不额外等待确认,也不保证异步清理完成。
safeInvokeStoreAction()
调用 Nexus State 动作的统一安全辅助函数。
const result = await safeInvokeStoreAction(remote, "increment", [1]);
if (result.isErr()) {
console.error(result.error.code, result.error.message);
} else {
console.log(result.value);
}因此无需为每个存储再生成一套重复的 safeActions.* 接口。
错误
重要的 Nexus State 公共错误包括:
NexusStoreConnectErrorNexusStoreDisconnectedErrorNexusStoreActionErrorNexusStoreProtocolError
需要区分连接失败、连接断开、远程动作失败和协议异常时,可以使用这些错误类型。