@k8ordo/state

仕組み

@k8ordo/stateが状態の読み書きをいつ、どこで行うかと、保証することとしないことが分かります。

このページの内容

定義とストア

text
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から読み戻した値は入力として扱います。次の順に読みます。

  1. スキーマ全体で読みます。通ればそれで終わりです。
  2. 通らなければ、各フィールドをそのフィールドのスキーマで読み、読めたものだけを残します。
  3. 残したフィールドで、もう一度スキーマ全体を通します。オブジェクト全体の.refine()はここで走ります。
  4. それでも通らなければ、すべてを既定値に戻します。すべてが既定値の状態は、定義の時点でスキーマを通ることを確かめてあります。

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で作った自前のホストもこれに当たります。
k8ordo

Baselineに入った機能を、制限なく使うReactのライブラリ群。