Store 与同步参考

Store 使用数据 paths 和独立快照。应用 facade 暴露 get、getSnapshot、set、update、on 和 batch；管理、历史和同步操作属于宿主。

选择操作

set 替换数据，update 同步计算新值，batch 在第一次写入前验证多项写入。on 通过 microtask 通知，tap 同步观察每次 commit。hydrate 替换根，不创建 ring buffer 条目，也不经过 taps。

值支持普通数据、稠密数组和 codec 标量。renderer 对象、函数、Date、Map、循环引用和 Promise 不属于共享状态值。Store 支持 bigint 标量，不代表 sync 能序列化它。

明确所有者的会话

import { wu } from 'wu-framework';

const sync = wu.store.sync({ transport: 'broadcast', room: 'catalog' });
await sync.ready();
wu.store.set('catalog.selectedId', 'p-42');
console.log(sync.status());
// Al terminar la sesión:
sync.stop();

只有激活之后的写入才被 sync 记录。Last Writer Wins 按 path 排序；父子路径并发写入不提供与同一路径写入相同的收敛性。保持一致粒度，并在适用时认证传输。

new WuStore

创建带环形历史的独立 store。

new WuStore(bufferSize?: number): WuStore

• 参数： bufferSize 默认 256，选择历史容量，不是状态字节上限。
• 返回值： 实例；buffer 大小向上取整为二的幂。
• 错误： 后续写入的值由 store codec 验证。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： state.dispose() 移除 sync、listeners 和 taps。

import { WuStore } from 'wu-framework';
const state = new WuStore(512);

参考：src/core/wu-store.js.

wu.store.tap

在 on 通知之前同步观察每次 commit。

wu.store.tap(callback): () => void

• 参数： callback(sequence,path,value)，适用于 journal 或传输。
• 返回值： Cleanup；非函数参数返回空 cleanup。
• 错误： 不按路径过滤，也不提供初始快照。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： stop() 移除 tap。

const stop = wu.store.tap((sequence, path, value) => {
  console.log(sequence, path, value);
});

参考：src/core/wu-store.js.

wu.store.hydrate

替换完整状态，并通知所选 paths。

wu.store.hydrate(state, { notifyPaths? }?): void

• 参数： 普通对象 state；notifyPaths 默认为新状态顶层键。
• 返回值： void；不增加 ring buffer 条目，不触发 taps。
• 错误： 替换前可能产生 WU_STORE_INVALID_VALUE 或 WU_STORE_INVALID_PATH。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

wu.store.hydrate({ cart: { count: 2 } }, { notifyPaths: ['cart.count'] });

参考：src/core/wu-store.js.

wu.store.getMetrics

读取读写、通知、历史和 listeners 计数。

wu.store.getMetrics(): object

• 参数： 无参数。
• 返回值： 指标快照。
• 错误： 不测量网络或渲染。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

console.log(wu.store.getMetrics().listenerCount);

参考：src/core/wu-store.js.

wu.store.getRecentEvents

查询最近的写入，包括序号、路径、值和时间戳。

wu.store.getRecentEvents(count?: number): object[]

• 参数： count 为有限正数，默认为 10，并受缓冲区大小限制。
• 返回值： 按从新到旧的顺序排列；值与内部状态分离。
• 错误： 非正数或非有限数返回 []。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不创建需要释放的资源。

console.table(wu.store.getRecentEvents(10));

WuStore 声明未列出此运行时方法。

参考：src/core/wu-store.js.

wu.store.reset

清空状态和历史记录，保留订阅和 taps。

wu.store.reset(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 不会删除此实例之外的持久化数据。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 不会自动通知初始空值；sync 仍处于活动状态。

wu.store.reset();

参考：src/core/wu-store.js.

wu.store.dispose

停止 sync，移除状态、监听器和 taps。

wu.store.dispose(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 不会删除此实例之外的持久化数据。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 在移除你所管理的 store 时使用；不要对其他使用方共享的 store 调用。

wu.store.dispose();

参考：src/core/wu-store.js.

wu.store.clear

执行与 dispose 相同的完整释放操作。

wu.store.clear(): void

• 参数： 无参数。
• 返回值： void。
• 错误： 不会删除此实例之外的持久化数据。
• 权限： 仅宿主；应用 facade 不提供。
• 清理： 同时移除订阅，并非仅操作值。

wu.store.clear();

参考：src/core/wu-store.js.

WuSyncHandle.ready

等待模块加载和传输启动。

sync.ready(): Promise<unknown>

• 参数： wu.store.sync(options) 返回的句柄。
• 返回值： Promise
• 错误： ready 可能拒绝；status.error 提供加载、授权或传输错误。
• 权限： 宿主会话；使用 WebSocket 时，中继应验证对等端身份。
• 清理： 所有者结束使用时，调用 stop() 取消会话。

await sync.ready();

参考：src/core/wu-store.js.

WuSyncHandle.status

查询连接、时钟、对等端和同步计数。

sync.status(): WuSyncStatus

• 参数： wu.store.sync(options) 返回的句柄。
• 返回值： WuSyncStatus
• 错误： ready 可能拒绝；status.error 提供加载、授权或传输错误。
• 权限： 宿主会话；使用 WebSocket 时，中继应验证对等端身份。
• 清理： 读取不会创建额外资源。

console.log(sync.status());

参考：src/core/wu-store.js.

WuSyncHandle.stop

停止消息交换和写入观察。

sync.stop(): void

• 参数： wu.store.sync(options) 返回的句柄。
• 返回值： void
• 错误： ready 可能拒绝；status.error 提供加载、授权或传输错误。
• 权限： 宿主会话；使用 WebSocket 时，中继应验证对等端身份。
• 清理： 移除 tap 并关闭此会话的传输。

sync.stop();

参考：src/core/wu-store.js.

WuSyncHandle.connected

查询会话的传输是否已连接。

sync.connected: boolean

• 参数： wu.store.sync(options) 返回的句柄。
• 返回值： boolean
• 错误： ready 可能拒绝；status.error 提供加载、授权或传输错误。
• 权限： 宿主会话；使用 WebSocket 时，中继应验证对等端身份。
• 清理： 读取状态；使用 stop 释放会话。

console.log(sync.connected);

参考：src/core/wu-store.js.