API
@k8ordo/stateがexportする関数と型の一覧です。useAppStateだけはClient Componentのフックで、ほかはサーバーでもクライアントでも呼べます。
このページの内容
definePageState
import元 @k8ordo/state
ページの状態を定義します。urlの値はURLのクエリに、entryの値は履歴エントリの状態に保存します。
definePageState<Url, Entry>(
key: string,
config: { url?: Url; entry?: Entry },
): PageState<Url, Entry>引数
keystring- 状態の名前。
entryの値を置く名前空間と、ストアの登録に使います。 config{ url?: StateSchema; entry?: StateSchema }urlとentryのスキーマ。少なくともどちらか1つを渡します。
戻り値
PageState<Url, Entry> — サーバーからもクライアントからもimportできる定義。
フィールド
kind'page'- 定義の種類。
useAppStateはこれを見てストアを選びます。 keystring- 1つ目の引数に渡したキー。
urlUrl- 渡した
urlのスキーマ。@k8ordo/frameworkのserverモードでページがexportするsearchや、@k8ordo/formのformFieldsに渡します。 entryEntry- 渡した
entryのスキーマ。 parseUrl(input: UrlInput) => OutputOf<Url>urlの値を読みます。欠けたパラメータは既定値になります。スキーマに合わない値は、フィールドごとに既定値に戻ります。読むときにエラーにはなりません。href(path, values?) => string- リンクを作ります。省いたフィールドは既定値として扱い、既定値と同じフィールドはクエリに出しません。先頭にViteの
baseを付けます。 search(values?) => string- クエリ文字列だけを、
?を付けずに返します。
注意
- どのフィールドにも
.default()か.optional()が要ります。無いと、モジュールの読み込みでfields must tolerate absenceを含むエラーになります。 urlの真偽値はz.stringbool()で、配列は.default([])で書きます。ほかの書き方は、モジュールの読み込みでエラーになります。- 同じフィールドを
urlとentryの両方に書くと型エラーになります。実行時にもdeclares in both url and entryを含むエラーになります。どちらも渡さないときはdeclares neither url nor entryを含むエラーになります。
src/state.tsexport 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([]),
}),
});urlReader
import元 @k8ordo/state
urlのスキーマだけから、parseUrlと同じ手順でクエリを読む関数を作ります。定義を持たず、スキーマだけを渡されたコードで使います。
urlReader<Url extends StateSchema>(
schema: Url,
): (input: UrlInput) => output<Url>引数
schemaStateSchemaurlのスキーマ。
戻り値
(input: UrlInput) => output<Url> — クエリを読む関数。読む手順はurlReaderを呼んだときに1回だけ組み立てます。
注意
@k8ordo/frameworkのserverモードは、searchをexportしたページのクエリをこれで読みます。
defineLocalState
import元 @k8ordo/state
localStorageに置く状態を定義します。消すまで残り、同じ端末のすべてのタブで共有されます。
defineLocalState<Schema>(
key: string,
schema: Schema,
versioning?: Versioning<Schema>,
): LocalState<Schema>引数
keystring- 状態の名前。
schemaStateSchema- 保存する値のスキーマ。フィールドの書き方は
definePageStateの注意と同じです。 versioningVersioning- 保存した形を変えたときの
versionとmigrate。省くと、値のオブジェクトをそのまま保存します。
戻り値
LocalState<Schema> — localStorageの状態の定義。
フィールド
kind'local'- 定義の種類。
useAppStateはこれを見てストアを選びます。 keystring- 1つ目の引数に渡したキー。
schemaSchema- 渡したスキーマ。
storageKeystring- 値を保存するlocalStorageのキー。
k8ordo-state:<key>です。 inlineRead() => string- インラインの
<script>に埋め込むJavaScriptの式。ブラウザで評価すると、保存したオブジェクトかnullになります。スキーマもmigrateも通りません。
注意
- 値はJSONで保存するので、フィールドはJSONで表せる型にします。スキーマは自分の出力を受け付ける必要があります。
- ほかのタブの書き込みは、
storageイベントで受け取ります。
defineSessionState
import元 @k8ordo/state
sessionStorageに置く状態を定義します。再読み込みでは残り、タブを閉じると消えます。
defineSessionState<Schema>(
key: string,
schema: Schema,
): SessionState<Schema>引数
keystring- 状態の名前。
schemaStateSchema- 保存する値のスキーマ。フィールドの書き方は
definePageStateの注意と同じです。
戻り値
SessionState<Schema> — sessionStorageの状態の定義。
フィールド
kind'session'- 定義の種類。
useAppStateはこれを見てストアを選びます。 keystring- 1つ目の引数に渡したキー。
schemaSchema- 渡したスキーマ。
storageKeystring- 値を保存するsessionStorageのキー。
k8ordo-state:<key>です。 inlineRead() => string- インラインの
<script>に埋め込むJavaScriptの式。ブラウザで評価すると、保存したオブジェクトかnullになります。スキーマは通りません。
注意
versionとmigrateは取りません。- 同じキーの
defineLocalStateとは別の状態です。
defineCookieState
import元 @k8ordo/state
Cookieに置く状態を定義します。ブラウザが書き、リクエストのたびにサーバーへ送られます。
defineCookieState<Schema>(
key: string,
schema: Schema,
versioning?: Versioning<Schema>,
): CookieState<Schema>引数
keystring- 状態の名前。使える文字は英数字と、HTTPのtokenに入る記号だけです。ほかの文字があると、モジュールの読み込みで
cannot name a cookieを含むエラーになります。 schemaStateSchema- 保存する値のスキーマ。フィールドの書き方は
definePageStateの注意と同じです。 versioningVersioning- 保存した形を変えたときの
versionとmigrate。省くと、値のオブジェクトをそのまま保存します。
戻り値
CookieState<Schema> — Cookieの状態の定義。
フィールド
kind'cookie'- 定義の種類。
useAppStateはこれを見てストアを選びます。 keystring- 1つ目の引数に渡したキー。
schemaSchema- 渡したスキーマ。
cookieNamestring- 値を保存するCookieの名前。
k8ordo-state.<key>です。 parseCookies(cookies: ReadonlyMap<string, string>) => output<Schema>- リクエストのCookieから値を読みます。パーセントデコード済みの値の
Mapを渡します。@k8ordo/frameworkのserverモードならrequest.cookiesをそのまま渡せます。古いバージョンの値は移行して読みますが、書き戻しません。 cookieValue(values?) => string- サーバーが同じCookieを書くときの値。スキーマに通した値を、エンコードしていないJSONで返します。省いたフィールドは既定値になります。
注意
- ブラウザはCookie Store APIで書きます。属性は
Path=/とSameSite=Lax、400日のMax-Ageです。SecureはAPIが必ず付けます。 HttpOnlyにはできません。秘密は置かないでください。- 名前と値を合わせて4KBを超えると、
update()が返すハンドルがrejectします。
defineMemoryState
import元 @k8ordo/state
JavaScriptの実行環境に置く、スキーマを持たない状態を定義します。再読み込みで初期値に戻ります。
defineMemoryState<Values>(
key: string,
initial: Values,
): MemoryState<Values>引数
keystring- 状態の名前。ストアの登録に使います。
initialValues- 初期値。値の型とキーの集まりを、この初期値から決めます。サーバーの描画にも使います。
戻り値
MemoryState<Values> — メモリの状態の定義。
フィールド
kind'memory'- 定義の種類。
useAppStateはこれを見てストアを選びます。 keystring- 1つ目の引数に渡したキー。
initialReadonly<Values>- 渡した初期値の写し。
注意
- スキーマはありません。値は実行環境の外に出ません。
- 値は書き換えずに
update()で置き換えます。update()はまとめず、呼ぶたびにその場で反映します。
useAppState
import元 @k8ordo/state
定義の今の値と、値を変えるupdateを返します。Client Componentのフックで、どの種類の定義にも使えます。
useAppState(def, options?): [state, update]
useAppState(def, keys, options?): [Pick<state, Key>, update]引数
defAnyState- 読み書きする定義。
keysreadonly Key[]- 購読するキー。そのキーが変わったときだけ再描画します。
[]なら何も購読しません。 options{ initialUrl? } | { initialCookie? }- サーバーで読んだ値。
initialUrlはurlを持つページの状態にだけ、initialCookieはCookieの状態にだけ渡せます。
戻り値
[state, update] — 今の値と、値を変える関数。
注意
- ページの状態の値は、
urlとentryをまとめた1つのオブジェクトです。 - サーバーの描画とハイドレーションの描画は既定値で行います。
initialUrlかinitialCookieを渡すとその値で、メモリの状態なら初期値で描画します。 update(patch, options?)はその場で値を反映し、UpdateHandleを返します。メモリの状態を除き、同じハンドラの中の呼び出しは1回の書き込みにまとめます。optionsはページの状態にだけあります。- Providerは要りません。ストアは最初に呼ばれたときに作られます。
pager.tsxconst [{ page }, update] = useAppState(listState, ['page']);
update({ page: page + 1 }, { history: 'push' });UpdateHandle
import元 @k8ordo/state
update()が返すオブジェクトで、2つのPromiseを持ちます。navigation.navigate()の戻り値と同じ形です。
type UpdateHandle = {
committed: Promise<void>;
finished: Promise<void>;
};フィールド
committedPromise<void>- 書き込みが終わったときに解決します。URLなら遷移の確定、ストレージとCookieなら保存の完了です。
finishedPromise<void>- 書き込みのあとにルーターが行う処理まで、すべて終わったときに解決します。
注意
- ハンドルを待たなくてもlintの警告にはなりません。rejectしても未処理のエラーにはなりません。
- 後から始まった遷移に取り消された遷移は
AbortErrorでrejectします。保存に失敗した書き込みは、そのエラーでrejectします。
UpdateOptions
import元 @k8ordo/state
ページの状態のupdate()が取る、2つ目の引数の型です。
type UpdateOptions = {
history?: 'push' | 'replace';
};フィールド
history'push' | 'replace'- 既定は
'replace'です。'push'は、urlの値が変わるときだけ新しい履歴エントリを追加します。
注意
- ページの状態以外の
update()には、この引数がありません。
Versioning
import元 @k8ordo/state
defineLocalStateとdefineCookieStateが取る、3つ目の引数の型です。
type Versioning<Schema> = {
version: number;
migrate: (
old: Readonly<Record<string, unknown>>,
fromVersion: number,
) => { readonly [Key in keyof input<Schema>]?: unknown };
};フィールド
versionnumber- 今のバージョン。1以上の整数です。
migrate(old, fromVersion) => values- 古いバージョンの値を今の形に読み替えます。
fromVersionは値を書いたときのバージョンで、バージョンを付けずに保存した値は0です。
注意
- 返した値は、スキーマでフィールドごとに読みます。合わないフィールドは既定値に戻ります。
migrateの中で例外が起きると、何も保存されていないものとして読みます。保存した値には触りません。
Register
import元 @k8ordo/state
hrefに渡すパスを型で検査するために、アプリケーションが拡張するインターフェースです。
declare module '@k8ordo/state' {
interface Register {
routes: typeof routes;
}
}フィールド
routestypeof routes@k8ordo/routerのルート表の型。パスは表のパターンと、セグメントごとに比べます。pathstring- 表を持たないルーターのパスのunion。
routesがあればそちらを優先します。
注意
@k8ordo/frameworkでは、.k8ordo/register.gen.tsに生成されます。- 拡張はアプリケーションの中でだけ行います。
- 検査は
RegisteredPath<Path>としてもexportしています。受け付けるパスならPathに、拒むならneverになります。
resetStateRegistry
import元 @k8ordo/state
ブラウザのストアの登録表を空にします。テストの間で状態を持ち越さないために使います。
resetStateRegistry(): void注意
- 先にコンポーネントをアンマウントしてください。
- 保存した値は消えません。
storageKeyやcookieNameを使って消します。
OutputOf
import元 @k8ordo/state
スキーマの出力の型です。initialUrlやinitialCookieを受け取るpropsの型を書くときに使います。
type OutputOf<Schema> = Schema extends StateSchema
? output<Schema>
: Record<never, never>;注意
OutputOf<typeof listState.url>のように、定義のスキーマを渡します。スキーマがundefinedなら、空のオブジェクトの型になります。
StateSchema
import元 @k8ordo/state
定義が受け取るスキーマの型です。zodとzod/miniのz.object()に共通する部分なので、どちらで書いたスキーマも渡せます。
type StateSchema<Shape extends $ZodShape = $ZodShape> =
$ZodObject<Shape> & { shape: Shape };UrlInput
import元 @k8ordo/state
parseUrlと、urlReaderが返す関数が受け取るクエリの型です。URLSearchParamsか、フレームワークがページに渡す形のオブジェクトです。
type UrlInput =
| URLSearchParams
| Readonly<Record<string, string | readonly string[] | undefined>>;AnyState
import元 @k8ordo/state
すべての種類の定義のunionです。どの定義でも受け取る関数を型付けするときに使います。PageStateなどの各種類の型も、同じ入口からexportしています。
type AnyState =
| PageState
| LocalState
| SessionState
| CookieState
| MemoryState;