@k8ordo/state

API

@k8ordo/stateがexportする関数と型の一覧です。useAppStateだけはClient Componentの中で使うフックで、ほかの関数はサーバーでもクライアントでも呼べます。

このページの内容

definePageState

import元 @k8ordo/state

ページの状態を定義します。urlはURLのクエリに、entryは履歴エントリの隠れた状態に置きます。

ts
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/serverのsearchや、@k8ordo/formのformFieldsに渡します。
entryEntry
渡したentryのスキーマ。
parseUrl(input: UrlInput) => OutputOf<Url>
urlを読みます。欠けたパラメータには既定値を入れ、スキーマに合わない値はフィールドごとに既定値に戻します。投げることはありません。
href(path, values?) => string
リンクを作ります。指定しなかったフィールドは既定値として扱い、既定値と同じフィールドはクエリから省きます。Viteのbaseを前に付けます。
search(values?) => string
クエリ文字列だけを、?を付けずに返します。

注意

  • どのフィールドも.default()か.optional()を持たなければなりません。無いと、モジュールの読み込みで投げます。
  • urlの真偽値はz.stringbool()で、配列は.default([])で書きます。ほかの綴りは、読み込みで拒まれます。
  • 同じフィールドをurlとentryの両方に書くと、型エラーになり、実行時にも投げます。どちらも渡さないときも投げます。
  • 戻り値の型はPageStateとしてexportしています。
state.ts
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([]),
  }),
});

urlReader

import元 @k8ordo/state

urlのスキーマだけから、parseUrlと同じ読み方をする関数を作ります。定義ではなく、スキーマだけを渡されたコードのためのものです。

ts
urlReader<Url extends StateSchema>(
  schema: Url,
): (input: UrlInput) => output<Url>

引数

schemaStateSchema
urlのスキーマ。

戻り値

(input: UrlInput) => output<Url> — クエリを読む関数。読み方を組み立てるのは、urlReaderを呼んだときの1回だけです。

注意

  • @k8ordo/serverは、searchをexportしたページのクエリをこれで読んでいます。

defineLocalState

import元 @k8ordo/state

localStorageに置く状態を定義します。消すまで残り、同じ端末のすべてのタブで共有されます。

ts
defineLocalState<Schema>(
  key: string,
  schema: Schema,
  versioning?: Versioning<Schema>,
): LocalState<Schema>

引数

keystring
状態の名前。localStorageのキーはk8ordo-state:<key>になります。
schemaStateSchema
保存する値のスキーマ。どのフィールドも.default()か.optional()を持たなければなりません。
versioningVersioning
保存した形を変えたときのversionとmigrate。省くと、行は値のオブジェクトそのものになります。

戻り値

LocalState<Schema> — localStorageの状態の定義。

フィールド

kind'local'
定義の種類。useAppStateは、これを見てストアを選びます。
keystring
1つ目の引数に渡したキー。
schemaSchema
渡したスキーマ。
storageKeystring
値を保存するlocalStorageのキー。k8ordo-state:<key>です。
inlineRead() => string
インラインの<script>に埋め込むJavaScriptの式。ブラウザで評価すると、保存された行のオブジェクトかnullになります。

注意

  • 値はJSONで保存するので、フィールドはJSONで表せる型にします。スキーマは、自分の出力を受け付けなければなりません。
  • ほかのタブの書き込みは、storageイベントで届きます。
  • 戻り値の型はLocalStateとしてexportしています。

defineSessionState

import元 @k8ordo/state

sessionStorageに置く状態を定義します。再読み込みでは残り、タブを閉じると消えます。

ts
defineSessionState<Schema>(
  key: string,
  schema: Schema,
): SessionState<Schema>

引数

keystring
状態の名前。sessionStorageのキーはk8ordo-state:<key>になります。
schemaStateSchema
保存する値のスキーマ。どのフィールドも.default()か.optional()を持たなければなりません。

戻り値

SessionState<Schema> — sessionStorageの状態の定義。

フィールド

kind'session'
定義の種類。useAppStateは、これを見てストアを選びます。
keystring
1つ目の引数に渡したキー。
schemaSchema
渡したスキーマ。
storageKeystring
値を保存するsessionStorageのキー。k8ordo-state:<key>です。
inlineRead() => string
インラインの<script>に埋め込むJavaScriptの式。sessionStorageを読みます。

注意

  • versionとmigrateは取りません。
  • 同じキーのdefineLocalStateとは、別の状態です。
  • 戻り値の型はSessionStateとしてexportしています。

defineCookieState

import元 @k8ordo/state

Cookieに置く状態を定義します。ブラウザが書き、リクエストのたびにサーバーへ届きます。

ts
defineCookieState<Schema>(
  key: string,
  schema: Schema,
  versioning?: Versioning<Schema>,
): CookieState<Schema>

引数

keystring
状態の名前。Cookieの名前はk8ordo-state.<key>になります。英数字と、HTTPのtokenに入る記号だけが使えます。
schemaStateSchema
保存する値のスキーマ。どのフィールドも.default()か.optional()を持たなければなりません。
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/serverならrequest.cookiesをそのまま渡せます。古い版の値は移行して読みますが、書き戻しません。
cookieValue(values?) => string
サーバーが同じCookieを書くときの値。スキーマに通してから、エンコードしていないJSONを返します。指定しなかったフィールドは既定値です。

注意

  • ブラウザはCookie Store APIで、Path=/とSameSite=Lax、400日のMax-Ageを付けて書きます。APIがSecureも付けます。
  • HttpOnlyにはできないので、秘密は置かないでください。
  • 名前と値を合わせて4KBを超えると、書き込みのハンドルがrejectします。
  • 戻り値の型はCookieStateとしてexportしています。

defineMemoryState

import元 @k8ordo/state

JavaScriptの実行環境に置く、型の付いた共有の箱を定義します。再読み込みで初期値に戻ります。

ts
defineMemoryState<Values>(
  key: string,
  initial: Values,
): MemoryState<Values>

引数

keystring
状態の名前。ストアの登録に使います。
initialValues
初期値。型とキーの集まりもここから決まり、サーバーの描画にも使います。

戻り値

MemoryState<Values> — メモリの状態の定義。

フィールド

kind'memory'
定義の種類。useAppStateは、これを見てストアを選びます。
keystring
1つ目の引数に渡したキー。
initialReadonly<Values>
渡した初期値の写し。

注意

  • スキーマはありません。値が実行環境の外へ出ないからです。
  • 値は書き換えずに、update()で置き換えます。update()はまとめず、呼ぶたびにその場で反映します。
  • 戻り値の型はMemoryStateとしてexportしています。

useAppState

import元 @k8ordo/state

定義の今の値と、値を変えるupdateを返します。どの種類の定義にも使える、Client Componentのフックです。

ts
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を平らにまとめたものです。
  • サーバーの描画とハイドレーションの描画は、既定値で行います。initialUrlやinitialCookieを渡せばその値で、メモリなら初期値で描きます。
  • update(patch, options?)は、その場で値を反映してUpdateHandleを返します。同じハンドラの中の呼び出しは、1回の書き込みにまとめます。optionsはページの状態にだけあります。
  • Providerは要りません。ストアは、最初に呼ばれたときに作られます。
pager.tsx
const [{ page }, update] = useAppState(listState, ['page']);

update({ page: page + 1 }, { history: 'push' });

UpdateHandle

import元 @k8ordo/state

update()が返す、2つのPromiseを持つオブジェクトです。navigation.navigate()が返すものと同じ形です。

ts
type UpdateHandle = {
  committed: Promise<void>;
  finished: Promise<void>;
};

フィールド

committedPromise<void>
書き込みが置き場所に入ったときに解決します。
finishedPromise<void>
書き込みのあとでルーターがする処理まで、すべて終わったときに解決します。

注意

  • 無視してもlintに掛からず、rejectも表に出ません。
  • 追い越された遷移はAbortErrorで、保存に失敗した書き込みはそのエラーでrejectします。

UpdateOptions

import元 @k8ordo/state

ページの状態のupdate()が取る、2つ目の引数の型です。

ts
type UpdateOptions = {
  history?: 'push' | 'replace';
};

フィールド

history'push' | 'replace'
既定は'replace'です。'push'は、urlの値が変わるときだけ新しい履歴エントリを積みます。

注意

  • ページの状態以外のupdate()には、この引数がありません。

Versioning

import元 @k8ordo/state

defineLocalStateとdefineCookieStateが取る、3つ目の引数の型です。

ts
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に渡すパスを型で確かめるために、アプリが拡張するインターフェースです。

ts
declare module '@k8ordo/state' {
  interface Register {
    routes: typeof routes;
  }
}

フィールド

routestypeof routes
@k8ordo/routerのルート表の型。パスを、表のパターンと区切りごとに照らし合わせます。
pathstring
表を持たないルーターのパスのunion。routesがあれば、そちらが優先されます。

注意

  • @k8ordo/staticと@k8ordo/serverでは、.k8ordo/register.gen.tsに生成されます。
  • 拡張はアプリケーションの中でだけ行います。
  • 検査はRegisteredPath<Path>としてもexportしています。受け付けるパスならPathに、拒むならneverになります。

resetStateRegistry

import元 @k8ordo/state

ブラウザのストアの登録表を空にします。テストの間で、状態を持ち越さないためのものです。

ts
resetStateRegistry(): void

注意

  • 先にコンポーネントをアンマウントしてください。
  • 保存した行は消えません。storageKeyやcookieNameで消します。

OutputOf

import元 @k8ordo/state

スキーマの出力の型です。initialUrlやinitialCookieを受け取るpropsの型を書くときに使います。

ts
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()に共通する部分なので、どちらで書いたスキーマも渡せます。

ts
type StateSchema<Shape extends $ZodShape = $ZodShape> =
  $ZodObject<Shape> & { shape: Shape };

UrlInput

import元 @k8ordo/state

parseUrlと、urlReaderが返す関数が受け取るクエリの型です。URLSearchParamsか、フレームワークがページに渡す形のオブジェクトです。

ts
type UrlInput =
  | URLSearchParams
  | Readonly<Record<string, string | readonly string[] | undefined>>;

AnyState

import元 @k8ordo/state

すべての種類の定義のunionです。どの定義でも受け取る関数を型付けするときに使います。

ts
type AnyState =
  | PageState
  | LocalState
  | SessionState
  | CookieState
  | MemoryState;
k8ordo

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

© 2026 k8o — MIT License

組版：Noto Sans JP / M PLUS 2

@k8ordo/state