@k8ordo/state

マイグレーション

スキーマの形を変えたあとも、前のスキーマが保存した値を読めるようになります。versionとmigrateで、古い値を今の形に変換します。

このページの内容

versionが無いとき

json
{"layout":"list","pageSize":50}
前のスキーマ`{ layout, pageSize }`が保存した値
{"view":"grid","pageSize":50}
今のスキーマ`{ view, pageSize }`で読んだ値。`layout`は読まれず、`view`は既定値になる。書き戻さない

versionを渡さない定義は、値のオブジェクトをそのまま保存します。古いスキーマが保存した値も、ほかの入力と同じくフィールドごとに読みます。今のスキーマが受け付けるフィールドは値を保ち、それ以外は既定値に戻ります。

  • フィールドを足した:足したフィールドは既定値から始まり、ほかの値はそのまま残ります。
  • 制約を厳しくした:新しい制約に合わない値だけが既定値に戻ります。
  • フィールドの名前を変えた:古い名前の値は読まれず、新しいフィールドは既定値になります。上のlayoutとviewがこの場合です。
  • 値の意味を変えた:古い値がそのまま新しい意味で読まれます。合わない値は既定値に戻ります。

前の2つは、そのままで正しく動きます。後の2つはエラーにならず、値が失われるか別の意味で読まれます。versionとmigrateで今の形に変換します。

versionとmigrate

prefs.ts
export const prefs = defineLocalState(
  'prefs',
  z.object({
    view: z.enum(['grid', 'table']).default('grid'),
    pageSize: z.number().default(20),
  }),
  {
    version: 1,
    migrate: (old) => ({
      view: old['layout'] === 'list' ? 'table' : 'grid',
      pageSize: old['pageSize'],
    }),
  },
);

defineLocalStateとdefineCookieStateは、3つ目の引数にversionとmigrateを取ります。この例では、バージョンを宣言する前に保存した値が{ layout: 'list' | 'cards' }の形でした。migrateはそのlayoutを今のviewに変換します。

バージョンを持つ値は、[version, values]の形で保存されます。バージョンの無い値は、バージョン0として読まれます。形が初めて変わったときにversion: 1を宣言すると、今ある値は0から移行されます。

localStorage: k8ordo-state:prefs
{"layout":"list","pageSize":50}
バージョンを宣言する前に保存した値
[1,{"view":"table","pageSize":50}]
移行して書き戻した値

versionは1以上の整数です。それ以外を渡すと、定義の時点で"prefs" version must be a positive integer, got 0のようなエラーになります。

古い値を読む順

versionより古い値は、次の順に読まれます。

  1. migrate(old, fromVersion)が、古い値を今の形に変換します。fromVersionは、その値を保存したときのバージョンです。
  2. 返した値を、ほかの読み込みと同じくスキーマでフィールドごとに読みます。
  3. ブラウザのストアが、結果を今のバージョンで書き戻します。

migrateが返すオブジェクトのキーはスキーマのキーです。ほかのキーを返すと型エラーになります。値は古いものをそのまま渡してかまいません。

サーバーのparseCookiesも移行して読みますが、書き戻しません。ページは応答にSet-Cookieを書けないためです。ハイドレーションのあとにブラウザが書き戻します。サーバーとブラウザは同じ値を読み、ハイドレーションで表示は変わりません。

次に形を変えるとき

prefs.ts
export const prefs = defineLocalState(
  'prefs',
  z.object({
    view: z.enum(['grid', 'table']).default('grid'),
    perPage: z.number().default(20),
  }),
  {
    version: 2,
    migrate: (old, fromVersion) => {
      if (fromVersion === 0) {
        return {
          view: old['layout'] === 'list' ? 'table' : 'grid',
          perPage: old['pageSize'],
        };
      }
      return { view: old['view'], perPage: old['pageSize'] };
    },
  },
);

次に形を変えるときはバージョンを上げ、migrateの2つ目の引数fromVersionで分けます。この例では、バージョン2でpageSizeをperPageに改めています。バージョン0の値もバージョン1の値も、1回のmigrateで今の形になります。

バージョンの違いとエラー

versionを使うときは、次の点があります。

  • 新しいバージョンの値:次のデプロイを先に読み込んだタブが保存した値です。migrateを通さずにフィールドごとに読み、書き戻しません。新しいタブの値はそのまま残ります。
  • migrateの中でエラーが起きた:何も保存されていないものとして既定値で読み、保存した値には触れません。migrateを直せば、次の読み込みで移行されます。
  • バージョンを宣言したばかり:保存の形が[version, values]に変わります。宣言する前のコードで動いているタブは、再読み込みするまでその値を何も保存されていないものとして読みます。
  • inlineRead():今のバージョンの値しか返しません。ほかのバージョンの値は、ストアが移行するまでnullです。詳しくはハイドレーション前を見てください。
  • defineSessionState:versionを取りません。保存した値はタブと一緒に消えます。古い形の値を持つのはデプロイをまたいで開いていたタブだけなので、フィールドごとに読むだけで足ります。
k8ordo

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