置き場所
状態をどこに置くかで、保存される期間と共有される範囲が決まります。7つの置き場所の違いを知り、選べるようになります。
このページの内容
7つの置き場所
src/state.tsimport {
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とは別の関数で定義します。
置き場所の選び方
次の問いを上から順に当てはめ、最初に当てはまったものを置き場所にします。
- リンクを開いた人にも同じ画面を見せたいなら、
urlです。検索語や絞り込み、ページ番号、選んでいるタブが当てはまります。サーバーが描画に使う値もここに置きます。 - 戻るボタンでは戻ってほしいが、リンクには含めたくないなら
entryです。開いている行や広げたパネルのように、その画面を見ている間だけの状態が当てはまります。 - その端末を使う人の好みなら、localStorageかCookieです。表示密度のように、サーバーの描画が既定値のままだと困るものはCookieに置きます。そうでなければlocalStorageで足ります。
- そのタブを使っている間だけ覚えておけばよいなら、sessionStorageです。閉じたお知らせや、そのタブで書きかけの下書きが当てはまります。
- 再読み込みで消えてよく、離れたコンポーネントの間で共有したいだけなら、メモリです。たとえばコマンドパレットの開閉です。
落とし穴
セッションやトークンのような秘密は、どの置き場所にも置かないでください。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.tsimport * 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.tsimport * 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に書かれる値も読み方も変わりません。