URL
urlに置く状態のスキーマを書けるようになります。URLはリンクを渡した相手に同じ画面を見せますが、文字列しか運ばず、誰でも書き換えられます。
このページの内容
既定値
page: z.coerce.number().int().min(1).default(1),
sort: z.enum(['price', 'name']).optional(),フィールドを足す前に作られたリンクも開かれるので、URLのパラメータは欠けていることがあります。どのフィールドにも.default()か.optional()を付けます。付け忘れたときのエラーは置き場所を見てください。
既定値を決められないフィールドは、上のsortのように.optional()にします。パラメータが無ければ、値はundefinedです。
パラメータの型
catalog-state.tsimport { definePageState } from '@k8ordo/state';
import * as z from 'zod';
export const catalogState = definePageState('catalog', {
url: z.object({
q: z.string().default(''),
page: z.coerce.number().int().min(1).default(1),
inStock: z.stringbool().default(false),
tags: z.array(z.enum(['sale', 'new'])).default([]),
}),
});各フィールドは、文字列から値を読める書き方にします。
- 文字列:
z.string()で受けます。選択肢が決まっていればz.enum()です。 - 数:
z.coerce.number()で受けます。?page=2の"2"が2になります。 - 真偽値:
z.stringbool()で受けます。"true"をtrueと読み、trueを"true"と書きます。 - 配列:
z.array()で受けます。同じ名前のパラメータを繰り返して書き(?tags=sale&tags=new)、既定値は[]にします。
配列ではないフィールドのパラメータが繰り返されたときは、最初の値を読みます。update()はスキーマに無いパラメータを書き換えないので、utm_sourceのようなほかの用途のパラメータと並べられます。
拒まれる書き方
inStock: z.boolean().default(false),
inStock: z.stringbool().default(false),update()は書いた値をいったんクエリ文字列にしてから読み直すので、URLの"false"を読み戻せる書き方が要ります。z.boolean()は"false"を受け付けず、z.coerce.boolean()はtrueと読みます。どちらもフィールドにも配列の要素にも使えません。モジュールを読み込んだ時点でurl boolean fields must use z.stringbool()で始まるエラーになります。
tags: z.array(z.string()).optional(),
tags: z.array(z.string()).default([]),.optional()の配列や、[]以外を既定値にした配列も拒まれます。パラメータが無いことと空の配列は同じURLなので、既定値が[]でないと空の配列を書けません。エラーはurl array fields must default to []で始まります。
URLで表せない値は、書こうとした時点で拒まれます。z.date()のフィールドにDateを渡すと、update()やhrefがエラーになります。エラー文はフィールドの名前とhas no URL serializationを含みます。
スキーマに合わない値
const read = (query: string) =>
catalogState.parseUrl(new URLSearchParams(query));
read('q=lamp&page=0');
// { q: 'lamp', page: 1, inStock: false, tags: [] }
read('page=abc&inStock=true');
// { q: '', page: 1, inStock: true, tags: [] }
read('tags=sale&tags=new');
// { q: '', page: 1, inStock: false, tags: ['sale', 'new'] }
read('tags=sale&tags=old');
// { q: '', page: 1, inStock: false, tags: [] }
read('q=red&q=blue');
// { q: 'red', page: 1, inStock: false, tags: [] }スキーマに合わない値は、そのフィールドだけが既定値に戻ります。ほかのフィールドは読めた値を保ちます。読むときにエラーにはなりません。
配列は1つのフィールドとして扱います。要素が1つでも合わなければ、配列全体が[]に戻ります。
price-state.tsexport const priceState = definePageState('price', {
url: z
.object({
min: z.coerce.number().min(0).default(0),
max: z.coerce.number().min(0).default(1000),
})
.refine((range) => range.min <= range.max),
});
priceState.parseUrl(new URLSearchParams('min=500&max=100'));
// { min: 0, max: 1000 }スキーマ全体に付けた.refine()は、フィールドごとに読んだあとの組み合わせを検証します。組み合わせが拒まれると、すべてのフィールドが既定値に戻ります。すべてが既定値の状態を.refine()が受け付けないと、モジュールを読み込んだ時点でurl schema rejects its own defaultsで始まるエラーになります。
URLの正規化
catalogState.search({ page: 1, tags: ['sale'] });
// 'tags=sale'
catalogState.search({ tags: ['sale'], q: 'desk lamp' });
// 'q=desk+lamp&tags=sale'searchとhrefは、既定値と同じフィールドをクエリから省きます。同じ状態からはいつも同じ、いちばん短いURLができます。同じ状態を指すリンクやブックマーク、キャッシュのキーが一致します。
パラメータは、スキーマに書いた順に並びます。既定値を手で書いた?page=1のようなURLも、省いたURLと同じ値に読めます。urlの値を変える次のupdate()がクエリを書き直すとき、このpage=1は省かれます。
クエリの読み取りデモ
入力したクエリを上のcatalogStateと同じ定義のparseUrlで読み、searchで作り直したクエリと並べて表示します(このページのURLは変わりません)。
q'lamp'page2inStockfalsetags[]
- 作り直したクエリ
q=lamp&page=2
試してみる
page=2をpage=0に書き換えると、pageだけが既定値の1に戻り、qは"lamp"のまま残ります。- 末尾に
&inStock=yesを足すと、inStockがtrueになります。作り直したクエリではinStock=trueと書かれます。 - さらに
&tags=sale&tags=newを足すと、tagsが配列として読まれます。newをoldに変えると選択肢に無い値が混ざり、tags全体が[]に戻ります。