restate / v1.0.0

API リファレンス

@kkwaenggwari/restate 1.0 のすべてのエクスポートと、その引数、戻り値、動作。

このページの内容

エクスポート

Web でも React Native でも、すべて @kkwaenggwari/restate から import します。

エクスポート	戻り値	用途
`restate(initial, updater \| options?)`	ストアのフック	共有のメモリストアを作る。
`persistedRestate(initial, options)`	保存ストアのフック	ストレージを通じて復元・保存するストアを作る。
`useRestateScope(factory?)`	ファクトリーの結果、またはスコープ	コンポーネントでストアを所有する。アンマウント後に破棄。
`createRestateScope()`	RestateScope	React の外でストアを所有する。終わったら destroy() を呼ぶ。
`shallow(left, right)`	boolean	選択結果を 1 階層だけ比較する。
`batch(callback)`	コールバックの戻り値	複数の変更の後に、購読者へ一度だけ通知する。
`restateManager`	RestateManager	起動時のデータを待ち、グローバルなストアに一括操作を行う。
`createIndexedDBStorage(options?)`	RestateStorage	独自のデータベース名やストア名で IndexedDB アダプターを作る。
`createMMKVStorage(options?)`	RestateStorage	自分のインスタンスや設定で MMKV アダプターを作る。

ストアはフックとして呼び出す関数で、次のメソッドを持ちます。

メンバー	説明
`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 は、次のメンバーが追加されたストアを返します。

メンバー	説明
`ready`	自動の読み込みが終わると、失敗した場合でも完了する Promise。status() を確認してください。
`save()`	現在の値を書き込みます。実際に書き込んだ値で resolve されます。
`restore()`	保存済みの値をメモリに読み込みます。
`hasSaved()`	保存済みのレコードがあるかどうか。
`clearStorage()`	保存済みのレコードを削除します。メモリは変わりません。
`resetAndClearStorage()`	メモリを初期値に戻し、保存済みのレコードを削除します。
`initialize()`	もう一度読み込みます。たとえば失敗したレコードを修正した後に使います。
`status()`	凍結されたステータスのスナップショット。フィールドが変わるまで同じオブジェクトです。
`useStatus(selector?, isEqual?)`	ステータス、または選択した部分が変わると再レンダリングするフック。
`key / storageKey / storage`	論理キー、名前空間付きのキー、使用中のアダプター。

key は必須です。ほかのオプションはすべて省略できます。

オプション	デフォルト	意味
`key`	必須	レコードの論理キー。
`namespace`	"@kkwaenggwari/restate"	保存するキーの接頭辞。空文字列にすると無効になります。
`storage`	IndexedDB / MMKV	プラットフォームのデフォルトの代わりに使うアダプター。
`autoSave`	false	true は変更のたびに保存し、{ delayMs } は入力の区切りを待ちます。
`version / migrate`	1 / なし	レコードのバージョンと、古いレコードを更新する方法。
`validate`	なし	保存の前と、復元またはマイグレーションの後に値をチェックします。
`serializer`	JSON	独自の serialize 関数と deserialize 関数。
`operationTimeoutMs`	30000	1 つのストレージ操作の制限時間。
`maxPendingOperations`	256	許可される保留中の操作の数(実行中のものを含む)。
`maxStorageCharacters`	5242880	UTF-16 コード単位で数えた、エンコード後の値の最大サイズ。
`updater / managed / serverSnapshot / onError`	—	restate のオプションと同じです。

status() と useStatus() は次のフィールドを返します。

フィールド	意味
`ready`	自動の読み込みが終わった。
`dirty`	メモリが、最後に読み込み・保存・復元した値と異なる。
`operation`	実行中のストレージ操作、または null。
`pending`	完了していないストレージ操作の数(実行中のものを含む)。
`blocked`	中断またはタイムアウトしたアダプター呼び出しが、まだ完了していない。
`available`	ストレージを使えるかどうか。
`error / observerError`	最後のストレージエラー / 最後のステータスリスナーのエラー。
`lastSavedAt / lastRestoredAt`	最後に成功したときのエポックミリ秒、または null。

各マネージャーは、自分に登録された永続ストアを管理します。

メンバー	説明
`ready`	アクセスした時点で登録されているストアを待ちます。BULK_OPERATION_FAILED で reject されます。
`saveAll(options?) / restoreAll(options?)`	すべてのストアに save または restore を実行します。{ concurrency } で並列数を制限できます。
`clearStorageAll() / resetAll() / resetAllAndClearStorage()`	レコードのクリア、メモリのリセット、またはその両方。
`list() / get(idOrKey) / size()`	登録されたストアを調べます。
`subscribe(listener) / status()`	マネージャーのイベントとリスナーのエラーを監視します。
`destroyAll()`	登録されたすべてのストアを破棄します。

次のメソッドを持つオブジェクトを storage に渡します。どのメソッドも値か Promise を返せます。

メソッド	説明
`getItem(key, context?)`	保存された文字列、または null を返します。
`setItem(key, value, context?)`	文字列を保存します。
`removeItem(key, context?)`	レコードを削除します。
`isAvailable?()`	ストレージを使えるかどうかを同期的に返します。
`clear?() / close?()`	省略可能なクリアと後片付け。
`coordinationKey?`	同じ保存先をラップする複数のアダプター間で共有するオブジェクト。

restate 1.0 の API に基づいています