目次

※全目次は一番下にあります

class Snapshot

Snapshotオブジェクトは、atomのRecoil stateの不変snapshotを表します。これは、グローバルなRecoil stateを観察、検査、管理するためのAPIを標準化することを意図しています。主に、開発ツール、グローバルstate同期、履歴ナビゲーションなどに役立ちます。

class Snapshot {
  // Accessors to inspect snapshot state
  getLoadable: <T>(RecoilValue<T>) => Loadable<T>;
  getPromise: <T>(RecoilValue<T>) => Promise<T>;

  // API to transform snapshots for transactions
  map: (MutableSnapshot => void) => Snapshot;
  asyncMap: (MutableSnapshot => Promise<void>) => Promise<Snapshot>;

  // Developer Tools API
  getID: () => SnapshotID;
  getNodes_UNSTABLE: ({
    isModified?: boolean,
  } | void) => Iterable<RecoilValue<mixed>>;
  getInfo_UNSTABLE: <T>(RecoilValue<T>) => {...};
}

function snapshot_UNSTABLE(initializeState?: (MutableSnapshot => void)): Snapshot

Snapshotの取得

Hooks

Recoilには、現在のstateに基づいてsnapshotを取得するための次のhookが用意されています。

* useRecoilCallback() - snapshotへの非同期アクセス
* useRecoilSnapshot() - snapshotへの同期アクセス
* useRecoilTransactionObserver_UNSTABLE() - すべてのstate変更に対してsnapshotを登録

snapshotの構築

snapshot_UNSTABLE()ファクトリを使用して新しいsnapshotを作成することもできます。このファクトリは省略可能な初期化関数を受け付けます。これは、Reactコンテキスト以外でselectorをテストまたは評価するために使用できます。

snapshotの読み取り

snapshotは、atomのstateに関しては読み取り専用です。atomのstateを読み取り、selectorの派生stateを評価するために使用できます。getLoadable()は、このsnapshotのatomまたはselectorのstateをLoadableに提供します。getPromise()メソッドを使用すると、非同期selectorの値が評価されるのを待つことができるので、その値が静的なatom stateに基づいているかどうかを確認できます。

サンプルコード

function MyComponent() {
  const logState = useRecoilCallback(({snapshot}) => () => {
    console.log("State: ", snapshot.getLoadable(myAtom).contents);

    const newSnapshot = snapshot.map(({set}) => set(myAtom, 42));
  });
}

Snapshotの変換

snapshotを変更したい場合があります。snapshotは不変ですが、新しい不変(Mutable)なsnapshotに変換セットをmapするメソッドがあります。mapメソッドは、MutableSnapshotに渡されるコールバックを取ります。MutableSnapshotはコールバック中に変更され、最終的にマッピング操作によって返される新しいsnapshotになります。

class MutableSnapshot {
  set: <T>(RecoilState<T>, T | DefaultValue | (T => T | DefaultValue)) => void;
  reset: <T>(RecoilState<T>) => void;
}

set()とreset()は、書き込み可能なselectorのsetプロパティに提供されるコールバックと同じシグネチャを持ちますが、新しいsnapshotにのみ影響し、現在のstateには影響しないことに注意してください。

Snapshotへの移動

次のhookを使用して、現在のRecoil stateを指定のsnapshotに移動できます。

useGotoRecoilSnapshot() - snapshotに合わせて現在のstateを更新する

開発者ツール

snapshotには、Recoilを使用した開発者ツールの構築やデバッグ機能に役立つメソッドがいくつか用意されています。このAPIはまだ進化しており、初期の開発ツールでは_UNSTABLEとなっています。

Snapshot IDs

コミットされたstateまたは変更されたsnapshotには、getID()で取得できる一意の不透明なバージョンIDがあります。これは、useGotoRecoilSnapshot()によって前のsnapshotに戻ったことを検出するために使用できます。

atomとselectorの列挙

getNodes_UNSTABLE()メソッドを使用すると、このsnapshotで使用されていたすべてのatomとselectorを反復できます。atom、selector、およびファミリー(?)はいつでも作成できます。ただし、実際に使用された場合にのみsnapshotに表示されます。atomおよびselectorは、それらが既に使用されていない場合、後続のstate snapshotから除去されます。

オプションのisModifiedフラグを指定すると、最後のトランザクション以降に変更されたatomのみを返すことができます。

デバッグ情報

getInfo_UNSTABLE()メソッドは、atomとselectorに関する追加のデバッグ情報を提供します。提供されるデバッグ情報は進化していますが、次の情報が含まれる場合があります。

loadable - 現在のstateでロード可能です。getLoadable()などのメソッドとは異なり、このメソッドはsnapshotをまったく変更しません。現在のstateを提供し、新しいatom/selectorの初期化、新しいselector評価の実行、依存関係やサブスクリプション(購読)の更新は行いません。
isSet - snapshot stateに格納されている明示的な値を持つatomの場合はTrue。selectorの場合、またはデフォルトのatom stateを使用する場合はfalse。
isModified - 最後のトランザクション以降に変更されたatomの場合にTrue。
type - atomまたはselectorのいずれか。
deps - このノードが依存するatomまたはselectorに対するイテレータ。
subscribers - このsnapshotのこのノードに登録しているものに関する情報。詳細は開発中です。

stateの初期化

<RecoilRoot>コンポーネントおよびsnapshot_UNSTABLE()ファクトリは、MutableSnapshotを介してstateを初期化するためのオプションのinitializeStatepropを取ります。これは、すべてのatomが事前にわかっている場合に永続stateをロードするのに役立ち、初期レンダリングと同期してstateを設定する必要があるサーバサイドレンダリングと互換性があります。atomごとの初期化/永続化、および動的atomの操作の容易さについては、atom effectsを参照してください。

参考サイト

・公式ドキュメント
・IT用語辞典 e-Words シグネチャ
・IT用語辞典 BINARY トランザクション
・atom effects
・みらい翻訳

全目次

前書き
①動機
②コアコンセプト
③インストール
④入門
基本チュートリアル
⑤概要
⑥Atoms
⑦Selectors
ガイド
⑧非同期データクエリ
⑨非同期状態・同期状態
⑩Stateの永続性
APIリファレンス
Core

•　⑪ <RecoilRoot />

•　State

　・　⑫atom()

　・　⑬selector()

　・　⑭Loadable

　・　⑮useRecoilState()

　・　⑯useRecoilValue()

　・　⑰useSetRecoilState()

　・　⑱useResetRecoilState()

　・　⑲useRecoilValueLoadable()

　・　⑳useRecoilStateLoadable()

　・　㉑isRecoilValue()

•　Snapshots

　・　㉒Snapshot

　・　㉓useRecoilTransactionObserver()

　・　㉔useRecoilSnapshot()

　・　㉕useGotoRecoilSnapshot()

•　㉖useRecoilCallback()

•　雑録(Misc)

　・　㉗useRecoilBridgeAcrossReactRoots()
実用(utils)

•　㉘atomFamily()

•　㉙selectorFamily()

•　㉚constSelector()

•　㉛errorSelector()

•　㉜waitForAll()

•　㉝waitForAny()

•　㉞waitForNone()

•　㉟noWait()