invalidateQueries vs staleTime — 自分の書き込みを即時反映

定義

サーバー状態キャッシュライブラリ（TanStack Query など）で「今書いたいいねやコメントをすぐ画面に出したい」とき、人はよく staleTime を下げようとする。だがそれは間違ったつまみだ。staleTime はデータを何秒間フレッシュとして信頼し、バックグラウンド refetch を控えるかを決める つまみであり、invalidateQueries はその staleTime を無視して該当クエリを今すぐ refetch させる。 即時反映の仕組みは staleTime ではなく invalidate だ。

ここで stale は「古くなった」と印を付けられた状態、refetch はサーバーからデータを取り直すこと、invalidate はキャッシュに「古い」と印を押して取り直させる行為を指す。

なぜ必要か

症状シナリオ: ユーザーがいいねを押すのに、画面がすぐ変わらない。「じゃあ staleTime を 0 にしよう」と考えると、今度はウィンドウフォーカスやコンポーネントマウントのたびに refetch が飛び、サーバートラフィックが爆発する。鮮度とトラフィックが対立するように見える。

正解は二つのつまみの役割を分けることだ。staleTime は鮮度 SLA（例:「10 秒以内に反映」）として保ちバックグラウンドトラフィックを抑え、書き込みミューテーションが成功したら該当クエリだけを invalidate してその瞬間だけ refetch を強制する。すると普段はトラフィックが静かで、自分の書き込み直後には即時更新される。

動作原理

• active（マウント中）クエリを invalidate すると staleTime に関係なくすぐ refetch する。
• inactive クエリは stale 印だけ付き、次の訪問時に refetch する。
• invalidate に渡す queryKey プレフィックスで影響範囲を絞る（scoped invalidation）— 無関係なクエリまで refetch しないようにする。

実務での適用

const queryClient = useQueryClient();

// 鮮度 SLA: 10 秒。フォーカスのたびの refetch はオフ。
new QueryClient({
  defaultOptions: {
    queries: { staleTime: 10_000, refetchOnWindowFocus: false },
  },
});

// 書き込みミューテーション: 成功後に該当スコープだけ invalidate
const like = useMutation({
  mutationFn: toggleLike,
  onMutate: async (vars) => {
    // 楽観的パッチ（即時反映）+ ロールバック用スナップショット
    await queryClient.cancelQueries({ queryKey: ["item", vars.id] });
    const prev = queryClient.getQueryData(["item", vars.id]);
    queryClient.setQueryData(["item", vars.id], applyLike);
    return { prev };
  },
  onError: (_e, vars, ctx) =>
    queryClient.setQueryData(["item", vars.id], ctx?.prev),
  onSettled: (_d, _e, vars) => {
    // サーバーの真実と再同期 — staleTime を無視してすぐ
    queryClient.invalidateQueries({ queryKey: ["item", vars.id] });
    queryClient.invalidateQueries({ queryKey: ["feed"] });
  },
});

体感の即時性が重要なら、onMutate の楽観的パッチで先に変え、onSettled で invalidate によりサーバーの真実と合わせる。

トレードオフ

• staleTime を下げて即時性を確保: 実装は簡単だが、あらゆる refetch ポイントでトラフィックが増える。規模が大きいとサーバーがつらい。
• staleTime を保ち書き込み後に invalidate: コードは少し増えるが、トラフィックと即時性を同時に満たす。scoped invalidation で refetch 範囲も制御できる。
• ダウンロードのバイトまで節約するなら条件付きリクエスト（ETag/304）と併用する — invalidate で refetch が走っても、内容が変わっていなければ 304 で本文を受け取らない。

使ってはいけない場合

• リアルタイム協業のように他人の変更が秒単位で流れ込む画面 — invalidate のポーリングより購読（WebSocket/Realtime）が合う。
• 書き込みの即時性が要らない純粋な読み取りダッシュボード — staleTime だけで足りるなら invalidate を乱用しない。

よくあるミス

• 即時反映されないからと staleTime を 0 にしてトラフィックを爆発させる。
• invalidate のスコープが広すぎる（全体 invalidateQueries()）て無関係なクエリまで refetch する。
• 楽観的パッチなしで invalidate だけを使い、書き込み→refetch の間にちらつきが見える。
• onError のロールバックを省いて、失敗した楽観的状態が画面に残る。

関連概念

• ssr-prefetch-query-cache-hydration — サーバーでクエリキャッシュを埋めて渡す hydration
• optimistic-outbox-rebase — オフライン/楽観的書き込みをキューで管理し収束させる
• race-safe-async-ui-requests — 楽観的ロールバックとリクエスト競合の処理