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。

方法	說明
`getItem(key, context?)`	回傳已儲存的字串或 null。
`setItem(key, value, context?)`	儲存字串。
`removeItem(key, context?)`	刪除紀錄。
`isAvailable?()`	同步回報儲存空間是否可用。
`clear?() / close?()`	選用的清除與清理。
`coordinationKey?`	在包裝同一個底層儲存空間的多個轉接器之間共用的物件。

依據 restate 1.0 API 撰寫