@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/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.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/frameworkのserverモードは、searchをexportしたページのクエリをこれで読みます。

defineLocalState

import元 @k8ordo/state

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

ts
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に置く状態を定義します。再読み込みでは残り、タブを閉じると消えます。

ts
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とは別の状態です。

import元 @k8ordo/state

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

ts
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の実行環境に置く、スキーマを持たない状態を定義します。再読み込みで初期値に戻ります。

ts
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のフックで、どの種類の定義にも使えます。

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をまとめた1つのオブジェクトです。
  • サーバーの描画とハイドレーションの描画は既定値で行います。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>
書き込みが終わったときに解決します。URLなら遷移の確定、ストレージとCookieなら保存の完了です。
finishedPromise<void>
書き込みのあとにルーターが行う処理まで、すべて終わったときに解決します。

注意

  • ハンドルを待たなくてもlintの警告にはなりません。rejectしても未処理のエラーにはなりません。
  • 後から始まった遷移に取り消された遷移はAbortErrorでrejectします。保存に失敗した書き込みは、そのエラーで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/frameworkでは、.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です。どの定義でも受け取る関数を型付けするときに使います。PageStateなどの各種類の型も、同じ入口からexportしています。

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

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