Rork で出したアプリにオフライン優先を後付けする — 永続キャッシュと書き込みキューの設計

// guarded/offline/queryClient.ts
import { QueryClient } from "@tanstack/react-query";
import { persistQueryClient } from "@tanstack/react-query-persist-client";
import { createAsyncStoragePersister } from "@tanstack/query-async-storage-persister";
import AsyncStorage from "@react-native-async-storage/async-storage";
 
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // メモリ上のキャッシュ寿命。永続キャッシュとは別物
      gcTime: 1000 * 60 * 60 * 24, // 24時間（旧 cacheTime）
      staleTime: 1000 * 60 * 5,    // 5分は再取得しない
      retry: 2,
    },
  },
});
 
const persister = createAsyncStoragePersister({
  storage: AsyncStorage,
  key: "RORK_RQ_CACHE_V1", // スキーマ変更時はサフィックスを上げて捨てる
  throttleTime: 1000,      // 書き込みを1秒間引く（過剰書き込み防止）
});
 
export function setupPersistence() {
  persistQueryClient({
    queryClient,
    persister,
    maxAge: 1000 * 60 * 60 * 24, // 24時間より古い永続キャッシュは復元しない
    dehydrateOptions: {
      // 成功したクエリだけ永続化する（エラー状態を焼き付けない）
      shouldDehydrateQuery: (q) => q.state.status === "success",
    },
  });
}

// app/_layout.tsx の最小の接続点
import { PersistQueryClientProvider } from "@tanstack/react-query-persist-client";
import { queryClient, persister } from "../guarded/offline/queryClient";
 
export default function RootLayout() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{ persister, maxAge: 1000 * 60 * 60 * 24 }}
    >
      {/* Rork が生成する既存のツリー */}
    </PersistQueryClientProvider>
  );
}

// guarded/offline/mutationQueue.ts
import AsyncStorage from "@react-native-async-storage/async-storage";
 
export type PendingMutation = {
  id: string;          // 重複送信を弾くための一意キー
  kind: "favorite.add" | "favorite.remove";
  payload: Record<string, unknown>;
  createdAt: number;
};
 
const QUEUE_KEY = "RORK_PENDING_MUTATIONS_V1";
 
export async function enqueue(m: PendingMutation): Promise<void> {
  const raw = await AsyncStorage.getItem(QUEUE_KEY);
  const list: PendingMutation[] = raw ? JSON.parse(raw) : [];
  // 同一 id が既にあれば積み直さない（二重タップ・再試行対策）
  if (list.some((x) => x.id === m.id)) return;
  list.push(m);
  await AsyncStorage.setItem(QUEUE_KEY, JSON.stringify(list));
}
 
export async function getQueue(): Promise<PendingMutation[]> {
  const raw = await AsyncStorage.getItem(QUEUE_KEY);
  return raw ? JSON.parse(raw) : [];
}
 
export async function removeFromQueue(id: string): Promise<void> {
  const list = await getQueue();
  await AsyncStorage.setItem(
    QUEUE_KEY,
    JSON.stringify(list.filter((x) => x.id !== id)),
  );
}

// guarded/offline/useFavoriteMutation.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { enqueue } from "./mutationQueue";
import { addFavoriteRequest } from "../../app/api/favorites"; // 生成コード側の送信関数
 
export function useAddFavorite() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: (itemId: string) => addFavoriteRequest(itemId),
    onMutate: async (itemId) => {
      await qc.cancelQueries({ queryKey: ["favorites"] });
      const prev = qc.getQueryData<string[]>(["favorites"]) ?? [];
      // 画面を即座に更新（楽観的更新）
      qc.setQueryData<string[]>(["favorites"], [...prev, itemId]);
      return { prev };
    },
    onError: async (_err, itemId, ctx) => {
      // 送信に失敗 = 圏外の可能性。UI は戻さずキューへ退避する
      await enqueue({
        id: `fav-add-${itemId}`,
        kind: "favorite.add",
        payload: { itemId },
        createdAt: Date.now(),
      });
      // ※ ここで ctx.prev に巻き戻さないのが肝。巻き戻すと「押したのに消える」体験になる
    },
    onSettled: () => {
      qc.invalidateQueries({ queryKey: ["favorites"] });
    },
  });
}