仕組み
@k8ordo/stateが状態の読み書きをいつ、どこで行うかと、保証することとしないことが分かります。
このページの内容
定義とストア
shared definePageState / defineLocalState / defineSessionState
defineCookieState / defineMemoryState
↓ import ↓ import
server parseUrl(searchParams) client useAppState(def)
parseCookies(cookies) → [state, update]
href(path, values)定義は、スキーマと純粋な関数だけを持つデータです。メモリの状態はスキーマの代わりに初期値を持ちます。モジュールを読み込んでもnavigationやlocalStorage、document.cookieには触れません。定義はサーバーでもテストでもそのままimportできます。
ストアは、useAppStateが最初に呼ばれたときにブラウザで作られます。登録のキーは、置き場所の種類と定義の文字列のキーの組です。HMRで定義のモジュールが評価し直されても、キーが同じなら同じストアにつながります。
サーバーではストアを作りません。サーバーの描画とハイドレーションの描画では、useAppStateは既定値を返します。メモリの状態なら初期値です。initialUrlやinitialCookieで渡したフィールドだけは、渡した値になります。ブラウザの値に切り替わるのは、ハイドレーションのあとです。
Providerが無い理由
URLと履歴エントリ、Web StorageとCookieは、どれもブラウザに1つずつしかありません。ストアはそれをそのまま読み書きするので、Providerで範囲を分ける必要がありません。
その代わり、ストアはテストをまたいで残ります。テストごとにresetStateRegistry()で消す手順は「テスト」にあります。
ルーターに求めること
ルーターに左右されるのは、URLを変えるupdate()だけです。navigateイベントをintercept()するルーターが要ります。リンクとGETフォーム、URLを変えないupdate()には何も要りません。
URLを変えるupdate()はnavigation.navigate()を呼びます。@k8ordo/routerの下では、pathnameが同じ遷移は状態の変更として扱われます。@k8ordo/frameworkのページもその下にあります。再マウントは起きず、スクロールとフォーカスもそのままです。update()が新しい値を描画済みなので、finishedはその遷移が終わると解決します。
@k8ordo/frameworkのserverモードでsearchをexportしたページだけは、クエリが変わると読み込み直され、finishedはその表示を待ちます(詳しくは「パラメータ」)。
スキーマに合わない値
URLや履歴エントリ、Web Storage、Cookieから読み戻した値は入力として扱います。次の順に読みます。
- スキーマ全体で読みます。通ればそれで終わりです。
- 通らなければ、各フィールドをそのフィールドのスキーマで読み、読めたものだけを残します。
- 残したフィールドで、もう一度スキーマ全体を通します。オブジェクト全体の
.refine()はここで走ります。 - それでも通らなければ、すべてを既定値に戻します。すべてが既定値の状態は、定義の時点でスキーマを通ることを確かめてあります。
2回目の全体の読み込みには、各フィールドの出力でなく、読み戻したときの入力を渡します。z.stringbool()のように、出力をもう一度入力にできないフィールドがあるからです。
update()で書いたurlの値は、クエリ文字列にしてから訪問者のURLと同じ手順で読み直します(詳しくは「URL」)。entryとWeb Storage、Cookieは、書いた値を文字列にせずそのままスキーマに渡します。そこではスキーマが自分の出力を受け付ける必要があります。
変更の検出
比べるキーは定義が持っています。スキーマのキーか、メモリの状態なら初期値のキーです。変更の有無はキーごとに判定します。
配列とプレーンなオブジェクトは中身を、それ以外はObject.isで比べます。DateやMap、クラスのインスタンスは参照で比べるので、同じ時刻を指す新しいDateも変わったものとして扱います。
共有される置き場所
URLと履歴エントリは、ほかの定義やルーター、計測用のパラメータとも共有しています。ページの状態が書き換えるのは、自分のパラメータと、履歴エントリの中の自分の名前空間だけです。ほかの値は書き込みのたびに引き継ぎます。
書き込む値は、その時点のブラウザの値にバッチの変更を重ねて作ります。描画した値から作ると、ほかのタブやほかの定義がその間に書いた値を消してしまいます。書き込み前のバッチがある間にほかの書き込みが入っても、バッチの変更はその上に残ります。
Cookieの書き込みは非同期なので、1つずつ順に行います。次の書き込みは、前の書き込みが終わってから今の値を読みます。2つのバッチが互いのフィールドを古い値で上書きすることはありません。
保証すること
- 置き場所から読み戻した値がスキーマに合わなくても、読むときにエラーにはなりません。合わない値は既定値に戻ります。
- スキーマを持つ置き場所では、
update()が次の描画に反映する値はスキーマを通った値です。 urlとentryを両方変えるupdate()は、1回のnavigation.navigate()で同じ履歴エントリに書き込みます。戻る/進むでは、両方が一緒に戻ります。- 書き込みは、そのバッチで変えたフィールドだけを今のブラウザの値に重ねます。それ以外の値は、その間にほかのタブやほかの定義が書いたもののまま残ります。
- 変わらなかったフィールドは前と同じ参照を保ちます。キーを指定した購読は、そのキーが変わったときだけ再描画します。
- サーバーの描画とハイドレーションの描画は、いつも同じ値で行います。
@k8ordo/routerと@k8ordo/frameworkの下では、ページの状態は、それを描くページのURLの値を読みます。次のページの読み込み中に画面に残るページは、離れる前の値のままです。次のページは最初の描画から、自分のURLの値で描かれます。- 次のページの読み込み中に、離れていくページで呼んだ
update()は何も書きません。finishedはすぐに解決します。
保証しないこと
- 同じ種類の定義が同じキーを使っても、エラーにも警告にもなりません。2つの定義は同じストアを共有します。
- サーバーの描画は、localStorageとsessionStorage、
entryの値を反映しません。サーバーはこれらの置き場所を読めません。 navigateイベントをintercept()しないルーターの下では、URLを変えるupdate()がドキュメント全体の読み込みになります。History APIで代わりに書く仕組みはありません。今のNext.jsがこれに当たります。詳しくは「Next.js」を見てください。- その場で書き換えた値は、変更として検出しません。入れ子のオブジェクトを書き換えても、再描画は起きません。
- メモリの状態の値は検証しません。スキーマを持たないので、
update()に渡した値がそのまま入ります。 - Web StorageとCookieへの書き込みは、容量の上限や4KBを超えるCookieで拒まれることがあります。そのときも描画した値は残り、
update()のハンドルがrejectします。 - サイトのデータの保存を止めたブラウザでは、localStorageとsessionStorageを読むと
SecurityErrorになります。defineLocalStateとdefineSessionStateの状態は既定値で描画します。update()で変えた値は次に読み込むまでメモリに残り、ハンドルはそのエラーでrejectします。 - どのページを描いているかを知らせないルーターの下では、ページの状態はURLに従います。
@k8ordo/routerのuseInterceptedNavigationで作った自前のホストもこれに当たります。