restate / v1.0.0

API 参考

@kkwaenggwari/restate 1.0 的所有导出，及其参数、返回值和行为。

本页内容

导出

在 Web 和 React Native 上，一切都从 @kkwaenggwari/restate 导入。

导出	返回	用途
`restate(initial, updater \| options?)`	store Hook	创建共享的内存 store。
`persistedRestate(initial, options)`	持久化 store Hook	创建通过存储恢复和保存的 store。
`useRestateScope(factory?)`	工厂函数的结果或 scope	在组件中拥有 store；卸载后销毁。
`createRestateScope()`	RestateScope	在 React 之外拥有 store；用完后调用 destroy()。
`shallow(left, right)`	boolean	对选取结果做一层比较。
`batch(callback)`	回调的返回值	多次变化后只通知订阅者一次。
`restateManager`	RestateManager	等待启动数据，并对全局 store 执行批量操作。
`createIndexedDBStorage(options?)`	RestateStorage	用自定义的数据库名或仓库名创建 IndexedDB 适配器。
`createMMKVStorage(options?)`	RestateStorage	用你自己的实例或配置创建 MMKV 适配器。

store 是一个可以当作 Hook 调用的函数，带有以下方法。

成员	说明
`useStore()`	返回整个值，每次变化都重新渲染。
`useStore(selector, isEqual?)`	返回选取结果；当 isEqual（默认为 Object.is）报告有变化时重新渲染。
`get()`	当前值，不订阅。
`set(value \| updater)`	替换值，或基于旧值计算新值。destroy() 之后会被忽略。
`reset()`	恢复声明的初始值并返回它。
`subscribe(listener)`	每次变化后调用 listener(value, previous, event)；返回取消订阅的函数。
`subscribeSelector(selector, listener, isEqual?)`	只在选取结果变化时调用 listener。
`on(type, listener)`	监听 change、reset、save、error 等事件。
`start() / stop() / isRunning()`	手动控制 updater。
`destroy() / isDestroyed()`	释放监听器和 updater。之后的订阅会抛出 STORE_DESTROYED。
`getInitial() / getServerSnapshot() / getError()`	初始值、服务端快照和最近一次监听器错误。
`id / kind`	唯一 id；memory 或 persistent。

persistedRestate 返回的 store 额外带有以下成员。

成员	说明
`ready`	自动加载结束时（即使失败）完成的 Promise。请检查 status()。
`save()`	写入当前值；以实际写入的值 resolve。
`restore()`	把已保存的值读入内存。
`hasSaved()`	是否存在已保存的记录。
`clearStorage()`	删除已保存的记录；内存不变。
`resetAndClearStorage()`	把内存重置为初始值，并删除已保存的记录。
`initialize()`	重新加载，例如在修复失败的记录之后。
`status()`	冻结的状态快照；在某个字段变化之前一直是同一个对象。
`useStatus(selector?, isEqual?)`	状态或选取的部分变化时重新渲染的 Hook。
`key / storageKey / storage`	逻辑 key、带命名空间的 key，以及正在使用的适配器。

key 是必需的，其他选项都是可选的。

选项	默认值	含义
`key`	必需	记录的逻辑 key。
`namespace`	"@kkwaenggwari/restate"	存储 key 的前缀；设为空字符串即可禁用。
`storage`	IndexedDB / MMKV	用来替代平台默认值的适配器。
`autoSave`	false	true 在每次变化后保存；{ delayMs } 等待停顿。
`version / migrate`	1 / 无	记录的版本，以及如何升级旧记录。
`validate`	无	在保存前以及恢复或迁移后检查值。
`serializer`	JSON	自定义的 serialize 和 deserialize 函数。
`operationTimeoutMs`	30000	单个存储操作的时间上限。
`maxPendingOperations`	256	允许等待的操作数，包括正在执行的那个。
`maxStorageCharacters`	5242880	编码后值的最大长度，以 UTF-16 码元计。
`updater / managed / serverSnapshot / onError`	—	与 restate 的选项相同。

status() 和 useStatus() 返回以下字段。

字段	含义
`ready`	自动加载已结束。
`dirty`	内存与上次加载、保存或恢复的值不同。
`operation`	正在执行的存储操作，或 null。
`pending`	尚未结束的存储操作数，包括正在执行的那个。
`blocked`	被中止或超时的适配器调用尚未结束。
`available`	是否可以使用存储。
`error / observerError`	最近一次存储错误；最近一次状态监听器错误。
`lastSavedAt / lastRestoredAt`	最近一次成功的时间（epoch 毫秒），或 null。

每个管理器跟踪注册到它的持久化 store。

成员	说明
`ready`	等待访问时已注册的 store；以 BULK_OPERATION_FAILED 拒绝。
`saveAll(options?) / restoreAll(options?)`	对每个 store 执行 save 或 restore；{ concurrency } 限制并行数量。
`clearStorageAll() / resetAll() / resetAllAndClearStorage()`	清空记录、重置内存，或两者都做。
`list() / get(idOrKey) / size()`	查看已注册的 store。
`subscribe(listener) / status()`	观察管理器事件和监听器错误。
`destroyAll()`	销毁所有已注册的 store。

把带有以下方法的对象作为 storage 传入。每个方法都可以返回值或 Promise。

基于 restate 1.0 API 编写