アップデートでお気に入りを消さないために — Rork 製アプリのローカルデータ・マイグレーション設計

// storage/migrations.ts — スキーママイグレーションランナー
import AsyncStorage from '@react-native-async-storage/async-storage';
 
export const SCHEMA_VERSION = 3;
 
type Envelope = { v: number; data: unknown };
 
type Migration = {
  from: number; // 適用前バージョン。from → from+1 への一段変換のみ
  migrate: (data: unknown) => unknown;
};
 
const migrations: Migration[] = [
  {
    // v1: 壁紙IDの生配列 → v2: 追加日時つきオブジェクト配列
    from: 1,
    migrate: (data) =>
      (data as string[]).map((id) => ({ id, addedAt: 0 })),
  },
  {
    // v2 → v3: addedAt 未設定に現在時刻を補い、重複IDを除去
    from: 2,
    migrate: (data) => {
      const seen = new Set<string>();
      return (data as { id: string; addedAt: number }[])
        .filter((f) => (seen.has(f.id) ? false : (seen.add(f.id), true)))
        .map((f) => ({ ...f, addedAt: f.addedAt || Date.now() }));
    },
  },
];
 
export async function readWithMigration<T>(
  key: string,
  fallback: T,
): Promise<T> {
  const raw = await AsyncStorage.getItem(key);
  if (raw === null) return fallback;
 
  let envelope: Envelope;
  try {
    const parsed = JSON.parse(raw);
    // 封筒形式の導入以前（生の配列など）は v1 とみなして拾う
    envelope =
      parsed && typeof parsed === 'object' && 'v' in parsed && 'data' in parsed
        ? (parsed as Envelope)
        : { v: 1, data: parsed };
  } catch {
    return fallback; // 壊れた JSON への対処は、触らず初期値で起動（ログは別途送る）
  }
 
  if (envelope.v === SCHEMA_VERSION) return envelope.data as T;
 
  // 未来のスキーマは読まない・書かない。
  // OTA ロールバック後の旧コードが新データを上書きする事故を防ぐ
  if (envelope.v > SCHEMA_VERSION) return fallback;
 
  // 移行前に原本を退避（後述の掃除ルールで1世代だけ保持）
  await AsyncStorage.setItem(`${key}.backup.v${envelope.v}`, raw);
 
  let { v, data } = envelope;
  while (v < SCHEMA_VERSION) {
    const step = migrations.find((m) => m.from === v);
    if (!step) return fallback; // 欠番は設計ミス。データを壊すより初期値で守る
    data = step.migrate(data);
    v += 1;
  }
 
  await AsyncStorage.setItem(key, JSON.stringify({ v, data }));
  return data as T;
}

// storage/favorites.ts — 画面からはこのモジュールだけを使う
import AsyncStorage from '@react-native-async-storage/async-storage';
import { readWithMigration, SCHEMA_VERSION } from './migrations';
 
export type Favorite = { id: string; addedAt: number };
const KEY = 'favorites';
 
export async function loadFavorites(): Promise<Favorite[]> {
  return readWithMigration<Favorite[]>(KEY, []);
}
 
export async function saveFavorites(list: Favorite[]): Promise<void> {
  await AsyncStorage.setItem(
    KEY,
    JSON.stringify({ v: SCHEMA_VERSION, data: list }),
  );
}

grep -rn "from '@react-native-async-storage" app/ components/ | grep -v storage/

// __tests__/favorites-migration.test.ts
// jest 設定で @react-native-async-storage/async-storage/jest/async-storage-mock を指定しておきます
import AsyncStorage from '@react-native-async-storage/async-storage';
import { loadFavorites } from '../storage/favorites';
 
const V1_FIXTURE = JSON.stringify(['w_001', 'w_002', 'w_001']);
 
it('v1 の生配列が現行スキーマまで移行され、重複が除かれます', async () => {
  await AsyncStorage.setItem('favorites', V1_FIXTURE);
  const result = await loadFavorites();
  expect(result.map((f) => f.id)).toEqual(['w_001', 'w_002']);
  expect(result.every((f) => f.addedAt > 0)).toBe(true);
});