@k8ordo/state

URL

urlに置く状態のスキーマを書けるようになります。URLはリンクを渡した相手に同じ画面を見せますが、文字列しか運ばず、誰でも書き換えられます。

このページの内容

既定値

ts
page: z.coerce.number().int().min(1).default(1),
sort: z.enum(['price', 'name']).optional(),

フィールドを足す前に作られたリンクも開かれるので、URLのパラメータは欠けていることがあります。どのフィールドにも.default()か.optional()を付けます。付け忘れたときのエラーは置き場所を見てください。

既定値を決められないフィールドは、上のsortのように.optional()にします。パラメータが無ければ、値はundefinedです。

パラメータの型

catalog-state.ts
import { 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のようなほかの用途のパラメータと並べられます。

拒まれる書き方

ts
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()で始まるエラーになります。

ts
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を含みます。

スキーマに合わない値

ts
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.ts
export 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の正規化

ts
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は省かれます。

Playground

クエリの読み取りデモ

入力したクエリを上のcatalogStateと同じ定義のparseUrlで読み、searchで作り直したクエリと並べて表示します(このページのURLは変わりません)。

q
'lamp'
page
2
inStock
false
tags
[]
作り直したクエリ
q=lamp&page=2

試してみる

  1. page=2をpage=0に書き換えると、pageだけが既定値の1に戻り、qは"lamp"のまま残ります。
  2. 末尾に&inStock=yesを足すと、inStockがtrueになります。作り直したクエリではinStock=trueと書かれます。
  3. さらに&tags=sale&tags=newを足すと、tagsが配列として読まれます。newをoldに変えると選択肢に無い値が混ざり、tags全体が[]に戻ります。
k8ordo

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