@k8ordo/state

置き場所

状態をどこに置くかで、保存される期間と共有される範囲が決まります。7つの置き場所の違いを知り、選べるようになります。

このページの内容

7つの置き場所

src/state.ts
import {
  defineCookieState,
  defineLocalState,
  defineMemoryState,
  definePageState,
  defineSessionState,
} from '@k8ordo/state';
import * as z from 'zod';

export const listState = definePageState('product-list', {
  url: z.object({
    page: z.coerce.number().int().min(1).default(1),
  }),
  entry: z.object({
    expanded: z.array(z.string()).default([]),
  }),
});

export const prefs = defineLocalState(
  'prefs',
  z.object({ view: z.enum(['grid', 'table']).default('grid') }),
);

export const notices = defineSessionState(
  'notices',
  z.object({ dismissed: z.array(z.string()).default([]) }),
);

export const density = defineCookieState(
  'density',
  z.object({
    density: z
      .enum(['comfortable', 'compact'])
      .default('comfortable'),
  }),
);

export const palette = defineMemoryState('command-palette', {
  open: false,
});

状態を定義する関数が、そのまま置き場所を表します。

  • definePageStateのurl:URLのクエリに置きます。戻る/進むで元に戻り、リンクを受け取った人にも同じ値が見えます。@k8ordo/frameworkのserverモードでsearchをexportしたページなら、サーバーでも読めます。
  • definePageStateのentry:履歴エントリの状態に置きます。戻る/進むと再読み込みでは残ります。URLには出ないので、共有したリンクには含まれません。
  • definePageStateのhash:URLのフラグメント(#の後ろ)に置きます。値は1つだけで、戻る/進むで元に戻り、リンクを受け取った人も同じ値で開きます。サーバーには送られません。
  • defineLocalState:localStorageに置きます。消すまで残り、同じ端末のすべてのタブに同じ値が見えます。
  • defineSessionState:sessionStorageに置きます。再読み込みでは残り、タブを閉じると消えます。ほかのタブからは見えません。
  • defineCookieState:Cookieに置きます。最後に書いてから400日残り、同じ端末のすべてのタブに同じ値が見えます。リクエストのたびにサーバーへ送られるので、サーバーでも読めます。
  • defineMemoryState:JavaScriptの実行環境に置きます。そのタブの中だけで共有され、再読み込みで初期値に戻ります。

どこに置いた状態も、読み書きには同じuseAppStateを使います。

ページ単位とアプリ単位

urlとentryは、同じ履歴エントリに属します。1つの定義にまとめて書き、両方にまたがる更新は一度に反映されます。

Web StorageとCookie、メモリはアプリ全体に属します。どのページから読んでも同じ値です。ページに属さないので、definePageStateとは別の関数で定義します。

置き場所の選び方

次の問いを上から順に当てはめ、最初に当てはまったものを置き場所にします。

  1. リンクを開いた人にも同じ画面を見せたいなら、urlです。検索語や絞り込み、ページ番号、選んでいるタブが当てはまります。サーバーが描画に使う値もここに置きます。
  2. 戻るボタンでは戻ってほしいが、リンクには含めたくないならentryです。開いている行や広げたパネルのように、その画面を見ている間だけの状態が当てはまります。
  3. その端末を使う人の好みなら、localStorageかCookieです。表示密度のように、サーバーの描画が既定値のままだと困るものはCookieに置きます。そうでなければlocalStorageで足ります。
  4. そのタブを使っている間だけ覚えておけばよいなら、sessionStorageです。閉じたお知らせや、そのタブで書きかけの下書きが当てはまります。
  5. 再読み込みで消えてよく、離れたコンポーネントの間で共有したいだけなら、メモリです。たとえばコマンドパレットの開閉です。
警告

落とし穴

セッションやトークンのような秘密は、どの置き場所にも置かないでください。CookieをHttpOnlyにできない理由はCookieを見てください。

状態のキー

どの定義も、1つ目の引数に文字列のキーを取ります。このキーが、その状態を保存する名前になります。

  • definePageState:履歴エントリの状態の中で、entryの値を置く名前空間
  • defineLocalStateとdefineSessionState:Web Storageのキーk8ordo-state:<key>。定義のstorageKeyで読めます
  • defineCookieState:Cookieの名前k8ordo-state.<key>。定義のcookieNameで読めます
  • どの種類でも:ブラウザの中でストアを登録する名前

キーを変えると、保存されるデータの名前も変わります。古いキーで保存した値は、新しい定義からは読めません。

同じ種類の定義が同じキーを使うと、同じストアを共有します。localStorageやsessionStorage、Cookieなら、保存した値も1つです。種類が違えば、同じキーでも別の状態です。モジュールの仕組みでは重なりを見つけられないので、キーはアプリ全体で重ならない名前にしてください。

情報

メモ

@k8ordo/color-schemeは、color-schemeというキーのdefineLocalStateで好みを保存しています。同じアプリでは、このキーをlocalStorageの状態に使わないでください。

スキーマの要る置き場所

src/state.ts
import * as z from 'zod';

export const listState = definePageState('product-list', {
  url: z.object({
    page: z.coerce.number().int().min(1),
  }),
});

スキーマを持つのは、URLやストレージ、履歴エントリから値を読み戻す置き場所です。読み戻す値には、利用者が書き換えたURLや古いスキーマが書いたストレージ、セッションの復元で戻った履歴エントリの状態があります。こうした値は入力として扱われ、読むたびにスキーマを通ります。

どのフィールドも、値が無くても読めるようにします。ハイライトしたpageのように.default()も.optional()も無いフィールドがあると、モジュールの読み込みの時点でエラーになります。エラー文はurl fields must tolerate absence — add .default() or .optional() to: pageのように、フィールド名を挙げます。

メモリだけはスキーマを持ちません。値が実行環境の外へ出ず、型の付いたupdate()だけが書き込むので、確かめ直すものがありません。

zod/mini

src/state.ts
import * as z from 'zod/mini';

export const listState = definePageState('product-list', {
  url: z.object({
    inStock: z._default(z.stringbool(), false),
    page: z._default(
      z.coerce.number().check(z.int(), z.gte(1)),
      1,
    ),
  }),
});

スキーマはzodとzod/miniのどちらで書いても動きます。ブラウザがスキーマで値を読み書きするので、スキーマはバンドルに入ります。アプリがほかでzodを使っていなければ、zod/miniを選んでください。ふつうの定義のモジュールなら、gzipした大きさはzodのおよそ3分の1で済みます。

zod/miniでは、.default()をz._default()と、.int().min(1)を.check(z.int(), z.gte(1))と書きます。どちらで書いても、URLに書かれる値も読み方も変わりません。

k8ordo

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