PersistedStateRegistry

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

按 namespace / name 两级复用的持久化状态注册表。

Remarks

这是三端 useState / usePersistedState 的框架无关内核：键转义、旧键迁移、 类型标签校验、undefined 的落盘语义、写盘失败可观测都只在这里定义一份（RVU-010）。 框架侧只负责把 PersistedStateEntry 包成各自的响应式容器 （Angular Signal、Vue Ref、React useSyncExternalStore）。

采用嵌套 Map，namespace 与 name 各占一层，进程内不可能串号（RAN-005）。

非浏览器环境（SSR、Node）下不读也不写 localStorage，状态退化成纯内存值， 因此服务端渲染不会因为缺少 localStorage 抛错。

暂不监听 storage 事件，因此不跨标签页同步：另一个标签页的写入不会反映到本实例。

Example

const registry = new PersistedStateRegistry({ onError: console.error });
const theme = registry.entry('my-app', 'theme', 'dark');

theme.subscribe(() => render(theme.get()));
theme.set('light'); // 落盘到 'my-app:theme' 并通知订阅者

Constructors

Constructor

new PersistedStateRegistry(options?): PersistedStateRegistry;

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

Parameters

Parameter	Type	Description
options?	PersistedStateRegistryOptions	见 PersistedStateRegistryOptions

Returns

PersistedStateRegistry

Methods

entry()

entry<T>(
   namespace, 
   name, 
   initialValue
): PersistedStateEntry<T>;

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

取得（必要时创建）某个键的状态入口。

Type Parameters

Type Parameter	Description
T	状态值类型

Parameters

Parameter	Type	Description
namespace	string	命名空间；与 name 各自转义后组成持久化键
name	string	键名
initialValue	T	仅首次注册生效的初值；盘上已有值时以盘上值为准

Returns

PersistedStateEntry<T>

同 namespace + name 始终返回同一个 PersistedStateEntry 对象

Throws

同键此前以不同值类型注册过时抛出（RAN-010）

Remarks

首次创建时会把解析出的初值立即落盘一次：这样「初值即约定」在盘上可见， 也让 undefined 初值顺手清掉可能遗留的旧键。