@k8ordo/state

更新

useAppStateが返すupdate()は、どの置き場所でも同じ書き方で状態を変えます。値が画面に反映される時点と置き場所に書き込まれる時点を知り、それに合わせた書き方ができるようになります。

このページの内容

変えるフィールドだけ

tsx
const [{ inStock, page }, update] = useAppState(listState);

update({ inStock: true, page: 1 });

update()には、変えるフィールドだけのオブジェクトを渡します。渡さなかったフィールドは今の値のまま残ります。

渡した値はその場で状態に入り、次の描画に反映されます。置き場所への書き込みはそのあとに行われるので、画面がURLやストレージの書き込みを待つことはありません。

定義に無いフィールドは型エラーになります。型チェックを通さずに渡すと、"product-list" has no field "sort"のようなTypeErrorになります。

書き込みの検証

tsx
update({ page: 0 });
`page`が`.min(1)`なら、既定値の`1`になる

update()は、まとめた状態をスキーマに通してから次の描画に反映します。urlのフィールドはURLから読むときと同じ手順で検証されるので、update({ page: 0 })は?page=0を開いたときと同じ結果になります。

URLで表せない値を渡すと、update()の呼び出しそのものがhas no URL serializationで終わるTypeErrorになります。何も書き込まれません。

メモリの状態にはスキーマが無いので、渡した値がそのまま入ります。

replaceとpush

tsx
update({ inStock: true, page: 1 });
今の履歴エントリを書き換える
update({ page: page + 1 }, { history: 'push' });
新しい履歴エントリを追加する

update()は、既定では今の履歴エントリを書き換えます。ブラウザの戻るで取り消したい更新にだけ、{ history: 'push' }を付けます。ページ送りがその例です。

このオプションはdefinePageStateのupdate()にだけあり、urlの値が変わるときにだけ効きます。entryの値だけを変える更新は、今の履歴エントリをその場で書き換えます。同じバッチで1回でもpushを指定すれば、そのバッチの遷移はpushになります。

ページを移るときは、@k8ordo/routerのnavigateToを使います。こちらは既定でpushです。

書き込みのまとめ

tsx
const clear = () => {
  update({ inStock: false });
  update({ page: 1 });
};

同じハンドラの中で続けて呼んだupdate()は、ReactのsetStateと同じように1回にまとまります。上の2回の呼び出しも、書き込みは1回です。

1回の書き込みが何になるかは、置き場所と変わった値で決まります。

  • urlの値が変わるとき:navigation.navigate()を1回。entryの変更も一緒に書き込みます。
  • entryの値だけが変わるとき:navigation.updateCurrentEntry()を1回。
  • localStorageとsessionStorage:setItemを1回。
  • Cookie:cookieStore.set()を1回。
  • メモリ:まとめません。呼ぶたびにその場で置き換え、呼ぶたびに解決済みのハンドルを返します。

スライダーのようにハンドラをまたいで続けて書くときは、URLへの書き込みが間引かれます。URLの値を変えるreplaceの書き込みは、前の書き込みから100msたつまで待ち、そのあいだのupdate()を1回の遷移にまとめます。画面の値はupdate()のたびにすぐ変わります。WebKitが同じ文書への遷移を10秒に200回までしか通さないためです。{ history: 'push' }の書き込みは待ちません。

ページの状態のバッチの結果が今の値と同じなら、遷移も履歴エントリの書き換えも起きません。localStorageとsessionStorage、Cookieは、値が変わらなくても保存した値を書き直します。ほかの定義やルーターのパラメータが残る仕組みは仕組みを見てください。

committedとfinished

ts
const { committed, finished } = update({ page: 2 });

update()は、navigation.navigate()と同じ形の、2つのPromiseを持つオブジェクトを返します。Promiseそのものではないので、無視してもno-floating-promisesのlintには掛かりません。無視するのが普通の使い方です。

  • committed:書き込みが置き場所に入ったときに解決します。
  • finished:書き込みのあとにルーターが行う処理まで終わったときに解決します。

書き込みを待つときはfinishedを待ちます。下の例では、ページ送りのあとに見出しへフォーカスを移しています。

pager.tsx
const heading = useRef<HTMLHeadingElement>(null);

const onNext = async () => {
  await update({ page: page + 1 }, { history: 'push' }).finished;
  heading.current?.focus();
};

遷移を伴わない書き込みのハンドルは、バッチを書き込んだ時点で解決します。Cookieは、Cookie Store APIが書き終えた時点です。ハンドルがrejectするのは次の2つの場合です。

  • あとから来た遷移に追い越された遷移:AbortError。たとえば同じハンドラで別のページの状態も書いたときです。間引かれて待っているあいだにページを離れた書き込みも、書かれずにAbortErrorになります。ハンドルを待たなければ気づくことはありません。
  • localStorage、sessionStorage、Cookieへの書き込みの失敗:その書き込みのエラーでrejectします。容量の上限やサイトのデータの保存を止めたブラウザ、4KBを超えるCookie、書き込む値でスキーマが例外を出したときです。描画した値はそのまま残ります。
情報

メモ

非同期のアクションの中でも同じように待てます。startTransition(async …)やuseTransition、@k8ordo/uiのButtonのonActionがそうです。ただし@k8ordo/routerの下では、別のページを読み込んでいる最中のurlの更新はページの切り替えになります。そのfinishedは、アクションの終わりを待たずに、そのページが表示された時点で解決します。

関数形式の更新

tsx
update((current) => ({ page: current.page + 1 }));

今の値を元に次の値を作るときは、update()に関数を渡します。関数が受け取るのは、同じバッチでまだ書き込まれていない更新も反映した状態です。

描画で読んだpageを使ってupdate({ page: page + 1 })を同じハンドラで2回呼ぶと、1つしか増えません。関数で書けば2つ増えます。

キーの購読

tsx
useAppState(listState);
どのフィールドが変わっても再描画
useAppState(listState, ['page']);
`page`が変わったときだけ再描画
useAppState(listState, []);
何も購読しない(書き込み専用)
useAppState(listState, ['page'], { initialUrl });
オプションはキーの配列のあと

useAppStateの2つ目の引数にキーの配列を渡すと、そのキーが変わったときだけ再描画されます。配列はインラインで書いてかまいません。内部で正規化してから比べるので、useMemoは要りません。

変わらなかったフィールドは前と同じ参照を保つので、memoや依存配列にそのまま渡せます。フィールドの比べ方は仕組みを見てください。

更新の頻度が大きく違う状態は、定義を分けます。再描画は定義の単位で決まるからです。

入力中の値

search-box.tsx
export function SearchBox() {
  const [{ q }, update] = useAppState(catalogState, ['q']);

  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const data = new FormData(event.currentTarget);
        update({ q: String(data.get('q') ?? ''), page: 1 });
      }}
    >
      <input defaultValue={q} key={q} name="q" type="search" />
      <button type="submit">Search</button>
    </form>
  );
}

キーを押すたびにupdate()を呼ぶと、URLの書き換えも1文字ごとに起きます。入力中の値はDOMかReactのローカルな状態に持たせ、送信やページ送りの区切りでupdate()を呼びます。

key={q}は、戻るボタンなどで外からqが変わったときに、入力欄を新しいdefaultValueで作り直します。

JavaScriptが読み込まれる前から動かすなら、GETフォームでURLを書き換えます。@k8ordo/formと組み合わせる書き方は「検索フォーム」にあります。

警告

落とし穴

定義の値をuseStateに写して同期させないでください。写した値は、戻るボタンやほかのタブの書き込みで更新されません。値が要るところでuseAppStateを呼びます。

Playground

書き込みの記録

このページのURLと履歴エントリを実際に書き換えるdefinePageStateで、aとbはURLに、cは履歴エントリに置いています。

  • useAppState(def){ a: 0, b: 0, c: 0 }描画回数
  • useAppState(def, ['a']){ a: 0 }描画回数
  • useAppState(def, ['b']){ b: 0 }描画回数
ブラウザが受け取った書き込み(新しい順)
まだありません

試してみる

  1. 「a + 1」を押すと、記録にnavigate · replaceで始まる行が1つ足されます。続けて「a + 1を3回」を押すと、aは3増えますが、足される行は1つだけです。
  2. 「c + 1」を押すと、URLは変わらず、記録にはupdateCurrentEntryが足されます。
  3. 「b + 1」を押すと、['a']を購読している行の描画回数は増えず、ほかの2行だけが増えます。
  4. 「a = -1」を押すと、aは既定値の0になります。スキーマが負の数を拒むからです。
  5. 「a + 1(push)」を押してから、ブラウザの戻るを押します。aが1つ前の値に戻ります。
k8ordo

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