PersistedStateEntry<T>

Defined in: packages/utils/src/@browser/persisted-state.ts:59

一个 namespace + name 的持久化状态入口。

Remarks

同一个 namespace + name 在同一个 PersistedStateRegistry 内始终是同一个对象， 因此任意持有者的写入对其余持有者立即可见，也不存在「两份陈旧副本互相覆盖盘上数据」。

Type Parameters

Type Parameter	Description
T	状态值类型

Properties

storageKey

readonly storageKey: string;

Defined in: packages/utils/src/@browser/persisted-state.ts:61

该状态在 localStorage 中的键（已转义）。

Methods

get()

get(): T;

Defined in: packages/utils/src/@browser/persisted-state.ts:68

读当前值。

Returns

T

内存中的当前值；引用在两次 PersistedStateEntry.set 之间保持稳定， 可直接用作 React useSyncExternalStore 的 snapshot。

---

persistError()

persistError(): Error | undefined;

Defined in: packages/utils/src/@browser/persisted-state.ts:89

最近一次持久化失败；写盘成功后自动清空。

Returns

Error | undefined

失败原因，或 undefined

Remarks

配额超限、循环引用、BigInt 等都会让写盘失败而内存值照常更新 —— 只有这个字段能让调用方知道数据没落盘（RAN-010）。

---

set()

set(next): void;

Defined in: packages/utils/src/@browser/persisted-state.ts:79

写入并同步落盘，然后通知所有订阅者。

Parameters

Parameter	Type	Description
next	T	新值

Returns

void

Remarks

写盘失败不会抛错：内存值照常更新，失败经 PersistedStateEntry.persistError 暴露给调用方（RAN-010）。订阅者无论落盘成功与否都会收到通知 —— persistError 的变化本身就是订阅者要看的状态变化。

---

subscribe()

subscribe(listener): () => void;

Defined in: packages/utils/src/@browser/persisted-state.ts:96

订阅该状态的变化。

Parameters

Parameter	Type	Description
listener	() => void	值或 persistError 变化后调用；不接收参数，请在回调里重新 get()

Returns

退订函数；重复调用是幂等的

() => void