// アンチパターン: useEffect + useState によるデータ取得
// 問題だらけのコード例
 
function UserList() {
  const [users, setUsers] = useState<User[]>([]);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState<Error | null>(null);
 
  useEffect(() => {
    let cancelled = false; // クリーンアップ用のフラグ
 
    const fetchUsers = async () => {
      try {
        setLoading(true);
        setError(null);
        const response = await fetch('/api/users');
        if (!response.ok) throw new Error('Failed to fetch');
        const data = await response.json();
 
        if (!cancelled) {
          setUsers(data);
        }
      } catch (err) {
        if (!cancelled) {
          setError(err as Error);
        }
      } finally {
        if (!cancelled) {
          setLoading(false);
        }
      }
    };
 
    fetchUsers();
 
    return () => {
      cancelled = true; // アンマウント時にキャンセル
    };
  }, []);
 
  // 問題点:
  // 1. キャッシュがない → 毎回ネットワークリクエストが発生
  // 2. 他のコンポーネントとデータ共有できない
  // 3. ウィンドウフォーカス時の再取得がない
  // 4. エラー時のリトライがない
  // 5. 楽観的更新が実装困難
  // 6. ローディング/エラー/データの3状態を毎回管理
  // 7. Race Conditionの処理が手動
  // 8. ページネーション/無限スクロールの実装が複雑
 
  if (loading) return <Loading />;
  if (error) return <Error message={error.message} />;
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// 推奨: TanStack Query を使った場合
// 上記の全問題が解決される
 
function UserList() {
  const { data: users, isLoading, error } = useQuery({
    queryKey: ['users'],
    queryFn: () => fetch('/api/users').then(res => res.json()),
    staleTime: 30 * 1000,          // 30秒間キャッシュを新鮮扱い
    retry: 3,                       // エラー時に3回リトライ
    refetchOnWindowFocus: true,     // ウィンドウフォーカスで再取得
  });
 
  // メリット:
  // 1. 自動キャッシュ管理
  // 2. 複数コンポーネント間でキャッシュ共有
  // 3. バックグラウンド再取得
  // 4. 自動リトライ
  // 5. DevToolsによるデバッグ
  // 6. TypeScript完全対応
 
  if (isLoading) return <Loading />;
  if (error) return <Error message={error.message} />;
  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
}

// stale-while-revalidate を体感する設定例
 
// ケース1: staleTime = 0（デフォルト）
// → キャッシュは常にstale → 毎回バックグラウンドで再取得
const { data } = useQuery({
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 0, // デフォルト値
});
 
// ケース2: staleTime = Infinity
// → キャッシュは永遠にfresh → 明示的にinvalidateしない限り再取得しない
const { data } = useQuery({
  queryKey: ['config'],
  queryFn: fetchConfig,
  staleTime: Infinity,
});
 
// ケース3: 現実的な設定
// → 5分間はfresh → 5分経過後にバックグラウンド再取得
const { data } = useQuery({
  queryKey: ['products'],
  queryFn: fetchProducts,
  staleTime: 5 * 60 * 1000, // 5分
});

// src/lib/query-client.ts
import { QueryClient } from '@tanstack/react-query';
 
export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // グローバルなデフォルト設定
      staleTime: 60 * 1000,           // 1分間はfresh
      gcTime: 5 * 60 * 1000,          // 5分間キャッシュを保持
      retry: 3,                        // 3回リトライ
      retryDelay: (attemptIndex) =>    // 指数バックオフ
        Math.min(1000 * 2 ** attemptIndex, 30000),
      refetchOnWindowFocus: true,      // ウィンドウフォーカスで再取得
      refetchOnReconnect: true,        // ネットワーク再接続で再取得
      refetchOnMount: true,            // マウント時に再取得
    },
    mutations: {
      retry: 1,                        // Mutationは1回リトライ
    },
  },
});

// src/app/providers.tsx
'use client'; // Next.js App Router の場合
 
import { QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { queryClient } from '@/lib/query-client';
 
export function Providers({ children }: { children: React.ReactNode }) {
  // 注意: QueryClientをコンポーネント内で生成しない（SSR対策）
  // useState で1回だけ生成するか、モジュールレベルで定義する
  return (
    <QueryClientProvider client={queryClient}>
      {children}
      {process.env.NODE_ENV === 'development' && (
        <ReactQueryDevtools
          initialIsOpen={false}
          position="bottom"
          buttonPosition="bottom-right"
        />
      )}
    </QueryClientProvider>
  );
}

// Query Key の設計原則
 
// 原則1: 階層構造を使う（配列で表現）
// → invalidateQueries で部分的に無効化できる
 
// 基本パターン
['users']                          // ユーザー一覧
['users', userId]                  // 特定ユーザー
['users', userId, 'posts']         // 特定ユーザーの投稿一覧
['users', userId, 'posts', postId] // 特定ユーザーの特定投稿
 
// フィルター・ソート・ページネーション含む
['users', { page: 1, sort: 'name', filter: 'active' }]
['users', { search: 'John', role: 'admin' }]
 
// 無効化の粒度
queryClient.invalidateQueries({ queryKey: ['users'] });
// → ['users'], ['users', 1], ['users', 1, 'posts'] 全て無効化
 
queryClient.invalidateQueries({ queryKey: ['users', 1] });
// → ['users', 1], ['users', 1, 'posts'] のみ無効化

// 推奨: Query Key Factory パターン
// src/lib/query-keys.ts
 
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (id: string) => [...userKeys.details(), id] as const,
  posts: (id: string) => [...userKeys.detail(id), 'posts'] as const,
} as const;
 
export const productKeys = {
  all: ['products'] as const,
  lists: () => [...productKeys.all, 'list'] as const,
  list: (filters: ProductFilters) => [...productKeys.lists(), filters] as const,
  details: () => [...productKeys.all, 'detail'] as const,
  detail: (id: string) => [...productKeys.details(), id] as const,
  reviews: (id: string) => [...productKeys.detail(id), 'reviews'] as const,
  related: (id: string) => [...productKeys.detail(id), 'related'] as const,
} as const;
 
// 型定義
type UserFilters = {
  page?: number;
  search?: string;
  role?: 'admin' | 'user';
  sort?: 'name' | 'createdAt';
  order?: 'asc' | 'desc';
};
 
type ProductFilters = {
  category?: string;
  minPrice?: number;
  maxPrice?: number;
  inStock?: boolean;
};

// Query Key Factory の使用例
 
// 一覧取得
const { data } = useQuery({
  queryKey: userKeys.list({ page: 1, role: 'admin' }),
  queryFn: () => api.users.list({ page: 1, role: 'admin' }),
});
 
// 詳細取得
const { data } = useQuery({
  queryKey: userKeys.detail(userId),
  queryFn: () => api.users.get(userId),
});
 
// 無効化（ユーザー関連のキャッシュを全て無効化）
queryClient.invalidateQueries({ queryKey: userKeys.all });
 
// 無効化（一覧のみ）
queryClient.invalidateQueries({ queryKey: userKeys.lists() });
 
// 無効化（特定ユーザーのみ）
queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) });

// staleTime と gcTime の関係を理解する設定例
 
// パターン1: 高頻度更新データ（チャット、通知）
const notificationsQuery = {
  queryKey: ['notifications'],
  queryFn: fetchNotifications,
  staleTime: 0,                    // 常にstale → 毎回バックグラウンド再取得
  gcTime: 5 * 60 * 1000,           // 5分間キャッシュ保持
  refetchInterval: 10 * 1000,      // 10秒ごとにポーリング
  refetchIntervalInBackground: false, // バックグラウンドタブではポーリングしない
};
 
// パターン2: 中頻度更新データ（ユーザー一覧、投稿一覧）
const usersQuery = {
  queryKey: ['users'],
  queryFn: fetchUsers,
  staleTime: 30 * 1000,            // 30秒間fresh
  gcTime: 10 * 60 * 1000,          // 10分間キャッシュ保持
};
 
// パターン3: 低頻度更新データ（マスタデータ、カテゴリ）
const categoriesQuery = {
  queryKey: ['categories'],
  queryFn: fetchCategories,
  staleTime: 24 * 60 * 60 * 1000,  // 24時間fresh
  gcTime: Infinity,                 // 永久にキャッシュ
};
 
// パターン4: ユーザー操作依存データ（CRUD対象）
const userDetailQuery = (id: string) => ({
  queryKey: userKeys.detail(id),
  queryFn: () => fetchUser(id),
  staleTime: 60 * 1000,            // 1分間fresh
  gcTime: 5 * 60 * 1000,           // 5分間キャッシュ保持
  placeholderData: keepPreviousData, // 前のデータをプレースホルダーに
});

import { useQuery, keepPreviousData } from '@tanstack/react-query';
 
const {
  // === 返却されるデータ ===
  data,                    // 取得したデータ（型安全）
  dataUpdatedAt,           // データ最終更新のタイムスタンプ
  error,                   // エラーオブジェクト
  errorUpdatedAt,          // エラー最終更新のタイムスタンプ
  failureCount,            // 連続失敗回数
  failureReason,           // 直近の失敗理由
 
  // === ステータスフラグ ===
  status,                  // 'pending' | 'error' | 'success'
  fetchStatus,             // 'fetching' | 'paused' | 'idle'
  isLoading,               // status === 'pending' && fetchStatus === 'fetching'
  isFetching,              // fetchStatus === 'fetching'（バックグラウンド再取得含む）
  isPending,               // status === 'pending'
  isError,                 // status === 'error'
  isSuccess,               // status === 'success'
  isRefetching,            // isFetching && !isLoading
  isStale,                 // データがstaleかどうか
  isPaused,                // fetchStatus === 'paused'
  isPlaceholderData,       // placeholderDataが使われているか
  isFetched,               // 最低1回はフェッチ完了したか
  isFetchedAfterMount,     // マウント後にフェッチ完了したか
 
  // === メソッド ===
  refetch,                 // 手動で再取得
} = useQuery({
  // === 必須オプション ===
  queryKey: ['users', userId],  // キャッシュキー（配列）
  queryFn: ({ signal }) =>      // データ取得関数（AbortSignal対応推奨）
    fetch(`/api/users/${userId}`, { signal }).then(r => r.json()),
 
  // === キャッシュ制御 ===
  staleTime: 60 * 1000,         // データがfreshとみなされる期間（ms）
  gcTime: 5 * 60 * 1000,        // 非活性キャッシュの保持期間（ms）
 
  // === 再取得制御 ===
  refetchOnWindowFocus: true,    // ウィンドウフォーカス時
  refetchOnReconnect: true,      // ネットワーク再接続時
  refetchOnMount: true,          // コンポーネントマウント時
  refetchInterval: false,        // ポーリング間隔（ms, falseで無効）
  refetchIntervalInBackground: false, // バックグラウンドタブでもポーリングするか
 
  // === リトライ制御 ===
  retry: 3,                      // リトライ回数（true=無限, false=0回）
  retryDelay: (attempt) =>       // リトライ間隔（指数バックオフ推奨）
    Math.min(1000 * 2 ** attempt, 30000),
  retryOnMount: true,            // マウント時にリトライするか
 
  // === 条件付きクエリ ===
  enabled: !!userId,             // falseでクエリ実行を停止
 
  // === データ変換 ===
  select: (data) => data.users,  // 返却データの変換・フィルタリング
 
  // === プレースホルダー ===
  placeholderData: keepPreviousData,  // 前のデータをプレースホルダーに
  // または固定値: placeholderData: { users: [] },
  // または関数: placeholderData: (previousData) => previousData,
 
  // === initialData ===
  initialData: undefined,        // 初期データ（キャッシュに保存される）
  initialDataUpdatedAt: undefined, // initialDataのタイムスタンプ
 
  // === 構造共有 ===
  structuralSharing: true,       // 参照同一性の最適化
 
  // === ネットワークモード ===
  networkMode: 'online',         // 'online' | 'always' | 'offlineFirst'
});

// 依存クエリ: あるクエリの結果に基づいて次のクエリを実行
 
// ステップ1: ユーザー情報を取得
function useUserWithPosts(userId: string) {
  // まずユーザー情報を取得
  const userQuery = useQuery({
    queryKey: userKeys.detail(userId),
    queryFn: () => api.users.get(userId),
  });
 
  // ユーザーの所属組織IDが取得できたら、組織情報を取得
  const organizationQuery = useQuery({
    queryKey: ['organizations', userQuery.data?.organizationId],
    queryFn: () => api.organizations.get(userQuery.data!.organizationId),
    enabled: !!userQuery.data?.organizationId, // ユーザーデータがあるときだけ実行
  });
 
  // ユーザーの投稿一覧を取得
  const postsQuery = useQuery({
    queryKey: userKeys.posts(userId),
    queryFn: () => api.users.getPosts(userId),
    enabled: userQuery.isSuccess, // ユーザー取得成功後に実行
  });
 
  return {
    user: userQuery.data,
    organization: organizationQuery.data,
    posts: postsQuery.data,
    isLoading: userQuery.isLoading,
    isError: userQuery.isError,
  };
}

// 依存クエリの別パターン: 検索フォーム
 
function useSearchResults(searchTerm: string) {
  // 検索語が2文字以上の場合のみクエリ実行
  return useQuery({
    queryKey: ['search', searchTerm],
    queryFn: () => api.search(searchTerm),
    enabled: searchTerm.length >= 2, // 2文字未満では実行しない
    staleTime: 5 * 60 * 1000,       // 検索結果は5分間キャッシュ
    placeholderData: keepPreviousData, // 検索語が変わっても前の結果を表示
  });
}
 
function SearchPage() {
  const [searchTerm, setSearchTerm] = useState('');
  const debouncedSearch = useDebounce(searchTerm, 300); // 300msデバウンス
  const { data, isLoading, isPlaceholderData } = useSearchResults(debouncedSearch);
 
  return (
    <div>
      <input
        value={searchTerm}
        onChange={(e) => setSearchTerm(e.target.value)}
        placeholder="Search..."
      />
      <div style={{ opacity: isPlaceholderData ? 0.5 : 1 }}>
        {data?.results.map(result => (
          <SearchResultCard key={result.id} result={result} />
        ))}
      </div>
    </div>
  );
}

// select を使ってサーバーレスポンスをクライアント用に変換
 
// 例1: 必要なフィールドだけ抽出
const { data: userNames } = useQuery({
  queryKey: userKeys.lists(),
  queryFn: () => api.users.list(),
  select: (data) => data.map(user => ({
    id: user.id,
    name: `${user.firstName} ${user.lastName}`,
  })),
});
 
// 例2: フィルタリング
const { data: activeUsers } = useQuery({
  queryKey: userKeys.lists(),
  queryFn: () => api.users.list(),
  select: (data) => data.filter(user => user.status === 'active'),
});
 
// 例3: 集計
const { data: userCount } = useQuery({
  queryKey: userKeys.lists(),
  queryFn: () => api.users.list(),
  select: (data) => data.length,
});
 
// 重要: select はキャッシュされたデータに対して実行される
// → 同じqueryKeyで異なるselectを使う複数のコンポーネントは
//   ネットワークリクエストを1回しか発行しない
 
// パフォーマンス注意: selectの安定した参照
// useCallback で参照を安定させることで不要な再計算を防ぐ
const selectActiveUsers = useCallback(
  (data: User[]) => data.filter(u => u.status === 'active'),
  []
);
 
const { data } = useQuery({
  queryKey: userKeys.lists(),
  queryFn: () => api.users.list(),
  select: selectActiveUsers,
});

import { useMutation, useQueryClient } from '@tanstack/react-query';
 
// 基本的なMutationの定義
function useCreateUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    // === Mutation関数 ===
    mutationFn: (newUser: CreateUserInput) =>
      api.users.create(newUser),
 
    // === コールバック ===
    onMutate: async (variables) => {
      // Mutationが開始される前に呼ばれる
      // 楽観的更新のためのキャッシュ操作に使う
      console.log('Creating user:', variables);
    },
 
    onSuccess: (data, variables, context) => {
      // Mutation成功時に呼ばれる
      // data: サーバーからの応答
      // variables: mutationFnに渡した引数
      // context: onMutateの返り値
 
      // キャッシュを無効化して再取得をトリガー
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
 
      // または直接キャッシュを更新
      queryClient.setQueryData(
        userKeys.detail(data.id),
        data
      );
    },
 
    onError: (error, variables, context) => {
      // Mutation失敗時に呼ばれる
      console.error('Failed to create user:', error);
    },
 
    onSettled: (data, error, variables, context) => {
      // 成功・失敗に関わらず最後に呼ばれる
      // キャッシュの無効化はここで行うのも良い
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
 
    // === リトライ ===
    retry: 1,
 
    // === ネットワークモード ===
    networkMode: 'online',
  });
}

// Mutationの使用例
function CreateUserForm() {
  const createUser = useCreateUser();
 
  const handleSubmit = async (formData: CreateUserInput) => {
    try {
      const newUser = await createUser.mutateAsync(formData);
      // mutateAsync は Promise を返す → try/catch で使える
      toast.success(`ユーザー「${newUser.name}」を作成しました`);
      router.push(`/users/${newUser.id}`);
    } catch (error) {
      toast.error('ユーザーの作成に失敗しました');
    }
  };
 
  return (
    <form onSubmit={handleSubmit}>
      {/* フォームフィールド */}
      <button
        type="submit"
        disabled={createUser.isPending}
      >
        {createUser.isPending ? '作成中...' : 'ユーザーを作成'}
      </button>
      {createUser.isError && (
        <p className="error">{createUser.error.message}</p>
      )}
    </form>
  );
}

// src/hooks/useUserMutations.ts
// CRUD操作を1つのカスタムフックにまとめるパターン
 
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { userKeys } from '@/lib/query-keys';
import { api } from '@/lib/api';
 
// === Create ===
export function useCreateUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: api.users.create,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
}
 
// === Update ===
export function useUpdateUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: UpdateUserInput }) =>
      api.users.update(id, data),
    onSuccess: (updatedUser) => {
      // 詳細キャッシュを直接更新
      queryClient.setQueryData(
        userKeys.detail(updatedUser.id),
        updatedUser
      );
      // 一覧キャッシュを無効化
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
}
 
// === Delete ===
export function useDeleteUser() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (id: string) => api.users.delete(id),
    onSuccess: (_, deletedId) => {
      // 詳細キャッシュを削除
      queryClient.removeQueries({ queryKey: userKeys.detail(deletedId) });
      // 一覧キャッシュを無効化
      queryClient.invalidateQueries({ queryKey: userKeys.lists() });
    },
  });
}
 
// === Bulk Operations ===
export function useBulkDeleteUsers() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (ids: string[]) => api.users.bulkDelete(ids),
    onSuccess: () => {
      // ユーザー関連のキャッシュを全て無効化
      queryClient.invalidateQueries({ queryKey: userKeys.all });
    },
  });
}

// 楽観的更新の完全な実装パターン
 
export function useUpdateTodo() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: ({ id, data }: { id: string; data: Partial<Todo> }) =>
      api.todos.update(id, data),
 
    // ステップ1: onMutate で楽観的にキャッシュを更新
    onMutate: async ({ id, data }) => {
      // 進行中のリフェッチをキャンセル（楽観的更新を上書きしないように）
      await queryClient.cancelQueries({ queryKey: ['todos'] });
      await queryClient.cancelQueries({ queryKey: ['todos', id] });
 
      // 現在のキャッシュを保存（ロールバック用）
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
      const previousTodo = queryClient.getQueryData<Todo>(['todos', id]);
 
      // 一覧キャッシュを楽観的に更新
      if (previousTodos) {
        queryClient.setQueryData<Todo[]>(['todos'], (old) =>
          old?.map(todo =>
            todo.id === id ? { ...todo, ...data } : todo
          )
        );
      }
 
      // 詳細キャッシュを楽観的に更新
      if (previousTodo) {
        queryClient.setQueryData<Todo>(['todos', id], (old) =>
          old ? { ...old, ...data } : old
        );
      }
 
      // ロールバック用のコンテキストを返す
      return { previousTodos, previousTodo };
    },
 
    // ステップ2: onError でロールバック
    onError: (error, { id }, context) => {
      // エラー時にキャッシュを元に戻す
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos);
      }
      if (context?.previousTodo) {
        queryClient.setQueryData(['todos', id], context.previousTodo);
      }
 
      // エラー通知
      toast.error('更新に失敗しました。変更を元に戻しました。');
    },
 
    // ステップ3: onSettled でキャッシュを再検証
    onSettled: (_, __, { id }) => {
      // 成功/失敗に関わらず、サーバーの最新データで同期
      queryClient.invalidateQueries({ queryKey: ['todos'] });
      queryClient.invalidateQueries({ queryKey: ['todos', id] });
    },
  });
}

// 楽観的更新: リスト要素の追加
 
export function useAddTodo() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (newTodo: CreateTodoInput) => api.todos.create(newTodo),
 
    onMutate: async (newTodo) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });
 
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
 
      // 仮のIDでリストに追加（UIがすぐに反映される）
      const optimisticTodo: Todo = {
        id: `temp-${Date.now()}`, // 仮のID
        ...newTodo,
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString(),
      };
 
      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
        old ? [...old, optimisticTodo] : [optimisticTodo]
      );
 
      return { previousTodos };
    },
 
    onSuccess: (serverTodo) => {
      // サーバーから返された正式なデータでキャッシュを更新
      // （仮IDが本物のIDに置き換わる）
      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
        old?.map(todo =>
          todo.id.startsWith('temp-') ? serverTodo : todo
        )
      );
    },
 
    onError: (error, newTodo, context) => {
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos);
      }
      toast.error('追加に失敗しました');
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });
}

// 楽観的更新: リスト要素の削除
 
export function useDeleteTodo() {
  const queryClient = useQueryClient();
 
  return useMutation({
    mutationFn: (id: string) => api.todos.delete(id),
 
    onMutate: async (id) => {
      await queryClient.cancelQueries({ queryKey: ['todos'] });
 
      const previousTodos = queryClient.getQueryData<Todo[]>(['todos']);
 
      // リストから即座に削除
      queryClient.setQueryData<Todo[]>(['todos'], (old) =>
        old?.filter(todo => todo.id !== id)
      );
 
      return { previousTodos };
    },
 
    onError: (error, id, context) => {
      // 失敗時にリストを復元
      if (context?.previousTodos) {
        queryClient.setQueryData(['todos'], context.previousTodos);
      }
      toast.error('削除に失敗しました');
    },
 
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['todos'] });
    },
  });
}

// Mutationの全状態を活用したUI表示
 
function TodoItem({ todo }: { todo: Todo }) {
  const updateTodo = useUpdateTodo();
  const deleteTodo = useDeleteTodo();
 
  return (
    <div
      className={cn(
        'flex items-center gap-2 p-3 rounded-lg',
        deleteTodo.isPending && 'opacity-50 pointer-events-none',
      )}
    >
      <Checkbox
        checked={todo.completed}
        disabled={updateTodo.isPending}
        onCheckedChange={(checked) => {
          updateTodo.mutate({
            id: todo.id,
            data: { completed: checked as boolean },
          });
        }}
      />
 
      <span className={cn(
        todo.completed && 'line-through text-muted-foreground',
        updateTodo.isPending && 'animate-pulse',
      )}>
        {todo.title}
      </span>
 
      <button
        onClick={() => {
          if (confirm('本当に削除しますか？')) {
            deleteTodo.mutate(todo.id);
          }
        }}
        disabled={deleteTodo.isPending}
      >
        {deleteTodo.isPending ? <Spinner /> : <TrashIcon />}
      </button>
 
      {/* エラー表示 */}
      {updateTodo.isError && (
        <span className="text-red-500 text-sm">
          更新失敗
          <button onClick={() => updateTodo.reset()}>閉じる</button>
        </span>
      )}
    </div>
  );
}

import { useInfiniteQuery, keepPreviousData } from '@tanstack/react-query';
 
// カーソルベースの無限スクロール
function useInfiniteUsers(filters?: UserFilters) {
  return useInfiniteQuery({
    queryKey: ['users', 'infinite', filters],
 
    queryFn: async ({ pageParam, signal }) => {
      const response = await api.users.list({
        cursor: pageParam,
        limit: 20,
        ...filters,
        signal, // AbortSignal を渡してキャンセル対応
      });
      return response;
    },
 
    // 初期ページパラメータ
    initialPageParam: undefined as string | undefined,
 
    // 次のページパラメータを決定
    getNextPageParam: (lastPage) =>
      lastPage.meta.hasNextPage ? lastPage.meta.nextCursor : undefined,
 
    // 前のページパラメータ（双方向スクロールの場合）
    getPreviousPageParam: (firstPage) =>
      firstPage.meta.hasPreviousPage ? firstPage.meta.previousCursor : undefined,
 
    // キャッシュ設定
    staleTime: 30 * 1000,
    gcTime: 10 * 60 * 1000,
 
    // 最大ページ数を制限（メモリ対策）
    maxPages: 10,
  });
}

// Intersection Observer による自動読み込み
 
import { useInView } from 'react-intersection-observer';
 
function UserInfiniteList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
    isLoading,
    isError,
    error,
    isFetching,
  } = useInfiniteUsers();
 
  // Intersection Observer: 要素が画面に表示されたら次のページを読み込む
  const { ref: loadMoreRef } = useInView({
    threshold: 0,
    rootMargin: '200px', // 200px手前で発火（先読み）
    onChange: (inView) => {
      if (inView && hasNextPage && !isFetchingNextPage) {
        fetchNextPage();
      }
    },
  });
 
  // 全ページのデータをフラットに結合
  const allUsers = data?.pages.flatMap(page => page.data) ?? [];
 
  if (isLoading) {
    return (
      <div className="grid grid-cols-3 gap-4">
        {Array.from({ length: 6 }).map((_, i) => (
          <UserCardSkeleton key={i} />
        ))}
      </div>
    );
  }
 
  if (isError) {
    return (
      <ErrorMessage
        error={error}
        onRetry={() => fetchNextPage()}
      />
    );
  }
 
  return (
    <div>
      {/* バックグラウンド再取得インジケーター */}
      {isFetching && !isFetchingNextPage && (
        <div className="fixed top-0 left-0 right-0 h-1 bg-blue-500 animate-pulse" />
      )}
 
      {/* ユーザーリスト */}
      <div className="grid grid-cols-3 gap-4">
        {allUsers.map(user => (
          <UserCard key={user.id} user={user} />
        ))}
      </div>
 
      {/* 読み込みトリガー */}
      <div ref={loadMoreRef} className="py-8 text-center">
        {isFetchingNextPage ? (
          <Spinner />
        ) : hasNextPage ? (
          <p className="text-muted-foreground">
            スクロールして続きを読み込む
          </p>
        ) : (
          <p className="text-muted-foreground">
            すべてのユーザーを表示しました（{allUsers.length}件）
          </p>
        )}
      </div>
    </div>
  );
}

// オフセットベースのページネーション（従来型）
 
function usePagedUsers(page: number, pageSize: number = 20) {
  return useQuery({
    queryKey: ['users', 'paged', { page, pageSize }],
    queryFn: () => api.users.list({
      offset: (page - 1) * pageSize,
      limit: pageSize,
    }),
    placeholderData: keepPreviousData, // ページ遷移時にちらつかない
    staleTime: 30 * 1000,
  });
}
 
function UserPagedList() {
  const [page, setPage] = useState(1);
  const pageSize = 20;
 
  const {
    data,
    isLoading,
    isPlaceholderData,
    isFetching,
  } = usePagedUsers(page, pageSize);
 
  // 次のページをプリフェッチ
  const queryClient = useQueryClient();
  useEffect(() => {
    if (data?.meta.hasNextPage) {
      queryClient.prefetchQuery({
        queryKey: ['users', 'paged', { page: page + 1, pageSize }],
        queryFn: () => api.users.list({
          offset: page * pageSize,
          limit: pageSize,
        }),
      });
    }
  }, [data, page, pageSize, queryClient]);
 
  if (isLoading) return <TableSkeleton rows={pageSize} />;
 
  return (
    <div style={{ opacity: isPlaceholderData ? 0.7 : 1 }}>
      {isFetching && <ProgressBar />}
 
      <table>
        <thead>
          <tr>
            <th>名前</th>
            <th>メール</th>
            <th>ロール</th>
          </tr>
        </thead>
        <tbody>
          {data?.data.map(user => (
            <tr key={user.id}>
              <td>{user.name}</td>
              <td>{user.email}</td>
              <td>{user.role}</td>
            </tr>
          ))}
        </tbody>
      </table>
 
      <Pagination
        currentPage={page}
        totalPages={data?.meta.totalPages ?? 1}
        onPageChange={setPage}
        disabled={isPlaceholderData}
      />
    </div>
  );
}

// @tanstack/react-virtual との組み合わせ
 
import { useVirtualizer } from '@tanstack/react-virtual';
 
function VirtualizedInfiniteList() {
  const {
    data,
    fetchNextPage,
    hasNextPage,
    isFetchingNextPage,
  } = useInfiniteUsers();
 
  const allItems = data?.pages.flatMap(page => page.data) ?? [];
 
  const parentRef = useRef<HTMLDivElement>(null);
 
  const virtualizer = useVirtualizer({
    count: hasNextPage ? allItems.length + 1 : allItems.length,
    getScrollElement: () => parentRef.current,
    estimateSize: () => 80, // 各行の推定高さ（px）
    overscan: 5,            // 画面外に余分にレンダリングする行数
  });
 
  // 最後の要素が表示されたら次のページを読み込む
  useEffect(() => {
    const lastItem = virtualizer.getVirtualItems().at(-1);
    if (!lastItem) return;
 
    if (
      lastItem.index >= allItems.length - 1 &&
      hasNextPage &&
      !isFetchingNextPage
    ) {
      fetchNextPage();
    }
  }, [
    virtualizer.getVirtualItems(),
    hasNextPage,
    isFetchingNextPage,
    allItems.length,
    fetchNextPage,
  ]);
 
  return (
    <div
      ref={parentRef}
      className="h-[600px] overflow-auto"
    >
      <div
        style={{
          height: `${virtualizer.getTotalSize()}px`,
          width: '100%',
          position: 'relative',
        }}
      >
        {virtualizer.getVirtualItems().map((virtualRow) => {
          const isLoaderRow = virtualRow.index > allItems.length - 1;
          const item = allItems[virtualRow.index];
 
          return (
            <div
              key={virtualRow.index}
              data-index={virtualRow.index}
              ref={virtualizer.measureElement}
              style={{
                position: 'absolute',
                top: 0,
                left: 0,
                width: '100%',
                transform: `translateY(${virtualRow.start}px)`,
              }}
            >
              {isLoaderRow ? (
                isFetchingNextPage ? <Spinner /> : null
              ) : (
                <UserCard user={item} />
              )}
            </div>
          );
        })}
      </div>
    </div>
  );
}

// パターン1: マウスホバーでプリフェッチ
function UserListItem({ user }: { user: User }) {
  const queryClient = useQueryClient();
 
  const prefetchUserDetail = () => {
    queryClient.prefetchQuery({
      queryKey: userKeys.detail(user.id),
      queryFn: () => api.users.get(user.id),
      staleTime: 60 * 1000, // 1分間はキャッシュを新鮮扱い
    });
  };
 
  return (
    <Link
      to={`/users/${user.id}`}
      onMouseEnter={prefetchUserDetail}  // hover でプリフェッチ開始
      onFocus={prefetchUserDetail}       // キーボードフォーカスでもプリフェッチ
    >
      <div className="flex items-center gap-3 p-3 hover:bg-gray-50 rounded-lg">
        <Avatar src={user.avatarUrl} alt={user.name} />
        <div>
          <p className="font-medium">{user.name}</p>
          <p className="text-sm text-muted-foreground">{user.email}</p>
        </div>
      </div>
    </Link>
  );
}

// パターン2: ルート遷移時のプリフェッチ（React Router v6）
 
import { useQueryClient } from '@tanstack/react-query';
 
// loader 関数でプリフェッチ
export const userDetailLoader =
  (queryClient: QueryClient) =>
  async ({ params }: LoaderFunctionArgs) => {
    const userId = params.userId!;
 
    // キャッシュが新鮮ならリクエストしない
    await queryClient.ensureQueryData({
      queryKey: userKeys.detail(userId),
      queryFn: () => api.users.get(userId),
      staleTime: 60 * 1000,
    });
 
    // 関連データも並列でプリフェッチ
    await Promise.all([
      queryClient.prefetchQuery({
        queryKey: userKeys.posts(userId),
        queryFn: () => api.users.getPosts(userId),
      }),
      queryClient.prefetchQuery({
        queryKey: ['organizations', userId],
        queryFn: () => api.users.getOrganization(userId),
      }),
    ]);
 
    return null; // loader の返り値は使わない（TanStack Query のキャッシュを使う）
  };
 
// ルーター設定
const router = createBrowserRouter([
  {
    path: '/users/:userId',
    element: <UserDetailPage />,
    loader: userDetailLoader(queryClient),
  },
]);

// パターン3: スクロール位置に基づくプリフェッチ
 
function ProductGrid({ products }: { products: Product[] }) {
  const queryClient = useQueryClient();
 
  // 画面に近づいた商品のデータをプリフェッチ
  const prefetchProduct = useCallback((productId: string) => {
    queryClient.prefetchQuery({
      queryKey: productKeys.detail(productId),
      queryFn: () => api.products.get(productId),
      staleTime: 5 * 60 * 1000,
    });
  }, [queryClient]);
 
  return (
    <div className="grid grid-cols-4 gap-4">
      {products.map((product) => (
        <ProductCard
          key={product.id}
          product={product}
          onVisible={() => prefetchProduct(product.id)} // 画面に表示されたらプリフェッチ
        />
      ))}
    </div>
  );
}
 
// Intersection Observer で可視性を検知するProductCard
function ProductCard({
  product,
  onVisible,
}: {
  product: Product;
  onVisible: () => void;
}) {
  const { ref } = useInView({
    triggerOnce: true, // 1回だけ発火
    rootMargin: '100px',
    onChange: (inView) => {
      if (inView) onVisible();
    },
  });
 
  return (
    <div ref={ref}>
      <Link to={`/products/${product.id}`}>
        <img src={product.imageUrl} alt={product.name} />
        <h3>{product.name}</h3>
        <p>{product.price}円</p>
      </Link>
    </div>
  );
}

// Next.js Server Component でのプリフェッチ（App Router）
// app/users/page.tsx
 
import {
  HydrationBoundary,
  QueryClient,
  dehydrate,
} from '@tanstack/react-query';
import { UserList } from '@/components/UserList';
 
export default async function UsersPage() {
  // Server Component ではリクエストごとに新しい QueryClient を生成
  const queryClient = new QueryClient();
 
  // サーバー側でデータを取得
  await queryClient.prefetchQuery({
    queryKey: userKeys.lists(),
    queryFn: () => fetchUsersFromDB(), // サーバー側で直接DB/APIにアクセス
  });
 
  return (
    // dehydrate でサーバー側のキャッシュをクライアントに引き渡す
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserList />
    </HydrationBoundary>
  );
}

// app/users/[userId]/page.tsx
// 動的ルートのプリフェッチ
 
import {
  HydrationBoundary,
  QueryClient,
  dehydrate,
} from '@tanstack/react-query';
 
interface PageProps {
  params: { userId: string };
}
 
export default async function UserDetailPage({ params }: PageProps) {
  const queryClient = new QueryClient();
 
  // 並列でデータを取得
  await Promise.all([
    queryClient.prefetchQuery({
      queryKey: userKeys.detail(params.userId),
      queryFn: () => fetchUserFromDB(params.userId),
    }),
    queryClient.prefetchQuery({
      queryKey: userKeys.posts(params.userId),
      queryFn: () => fetchUserPostsFromDB(params.userId),
    }),
  ]);
 
  return (
    <HydrationBoundary state={dehydrate(queryClient)}>
      <UserDetail userId={params.userId} />
    </HydrationBoundary>
  );
}
 
// クライアントコンポーネント
// components/UserDetail.tsx
'use client';
 
export function UserDetail({ userId }: { userId: string }) {
  // サーバーでプリフェッチされたデータがキャッシュから即座に返される
  // → 初期レンダリングでローディング表示がない
  const { data: user } = useQuery({
    queryKey: userKeys.detail(userId),
    queryFn: () => api.users.get(userId), // クライアント側のフォールバック
  });
 
  const { data: posts } = useQuery({
    queryKey: userKeys.posts(userId),
    queryFn: () => api.users.getPosts(userId),
  });
 
  if (!user) return null;
 
  return (
    <div>
      <h1>{user.name}</h1>
      <p>{user.email}</p>
      <h2>投稿一覧</h2>
      {posts?.map(post => (
        <PostCard key={post.id} post={post} />
      ))}
    </div>
  );
}

// 重要: SSR環境での QueryClient 生成パターン
 
// アンチパターン: モジュールレベルで1つだけ生成
// → リクエスト間でキャッシュが共有されてしまう！
// const queryClient = new QueryClient(); // 危険！
 
// 推奨パターン1: Server Component で毎回生成
export default async function Page() {
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60 * 1000, // SSRデータは1分間fresh
      },
    },
  });
  // ...
}
 
// 推奨パターン2: Provider で useState を使って1回だけ生成
'use client';
 
export function QueryProvider({ children }: { children: React.ReactNode }) {
  // useState で初期化することで、コンポーネントのライフタイム中は同じインスタンスを使用
  // かつ、SSR時にリクエスト間で共有されない
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000,
          },
        },
      })
  );
 
  return (
    <QueryClientProvider client={queryClient}>
      {children}
    </QueryClientProvider>
  );
}

// 基本的なポーリング
function useNotifications() {
  return useQuery({
    queryKey: ['notifications'],
    queryFn: fetchNotifications,
    refetchInterval: 30 * 1000,            // 30秒ごとに再取得
    refetchIntervalInBackground: false,     // バックグラウンドタブでは停止
  });
}

// 条件付きポーリング: 処理状況に応じて間隔を変更
 
function useJobStatus(jobId: string) {
  return useQuery({
    queryKey: ['jobs', jobId],
    queryFn: () => api.jobs.getStatus(jobId),
 
    // ジョブが完了したらポーリングを停止
    refetchInterval: (query) => {
      const status = query.state.data?.status;
 
      if (status === 'completed' || status === 'failed') {
        return false; // ポーリング停止
      }
      if (status === 'processing') {
        return 2 * 1000; // 処理中は2秒間隔
      }
      return 10 * 1000; // それ以外は10秒間隔
    },
 
    // 初期データなしの場合のみfetch
    enabled: !!jobId,
  });
}
 
// 使用例: ファイルアップロード進捗の監視
function UploadProgress({ jobId }: { jobId: string }) {
  const { data: job } = useJobStatus(jobId);
 
  if (!job) return <Spinner />;
 
  return (
    <div>
      <ProgressBar value={job.progress} max={100} />
      <p>ステータス: {job.status}</p>
      {job.status === 'completed' && <p>完了しました！</p>}
      {job.status === 'failed' && <p>エラー: {job.error}</p>}
    </div>
  );
}

// WebSocket でリアルタイム更新を受信してキャッシュを更新
 
// src/hooks/useRealtimeUpdates.ts
import { useQueryClient } from '@tanstack/react-query';
import { useEffect } from 'react';
 
function useRealtimeUpdates() {
  const queryClient = useQueryClient();
 
  useEffect(() => {
    const ws = new WebSocket(process.env.NEXT_PUBLIC_WS_URL!);
 
    ws.onmessage = (event) => {
      const message = JSON.parse(event.data);
 
      switch (message.type) {
        case 'USER_UPDATED':
          // 特定ユーザーのキャッシュを直接更新
          queryClient.setQueryData(
            userKeys.detail(message.payload.id),
            message.payload
          );
          // ユーザー一覧も無効化
          queryClient.invalidateQueries({ queryKey: userKeys.lists() });
          break;
 
        case 'USER_CREATED':
          // 一覧キャッシュを無効化して再取得をトリガー
          queryClient.invalidateQueries({ queryKey: userKeys.lists() });
          break;
 
        case 'USER_DELETED':
          // キャッシュから削除
          queryClient.removeQueries({
            queryKey: userKeys.detail(message.payload.id),
          });
          queryClient.invalidateQueries({ queryKey: userKeys.lists() });
          break;
 
        case 'NOTIFICATION':
          // 通知キャッシュを無効化
          queryClient.invalidateQueries({ queryKey: ['notifications'] });
          break;
      }
    };
 
    ws.onclose = () => {
      // 再接続ロジック
      console.log('WebSocket closed, attempting reconnect...');
    };
 
    return () => {
      ws.close();
    };
  }, [queryClient]);
}
 
// App.tsx で使用
function App() {
  useRealtimeUpdates();
  return <RouterProvider router={router} />;
}

// Server-Sent Events (SSE) との統合
 
function useSSEUpdates() {
  const queryClient = useQueryClient();
 
  useEffect(() => {
    const eventSource = new EventSource('/api/events');
 
    eventSource.addEventListener('data-update', (event) => {
      const data = JSON.parse(event.data);
 
      // 関連するクエリを無効化
      queryClient.invalidateQueries({
        queryKey: [data.entity],
      });
    });
 
    eventSource.addEventListener('cache-invalidate', (event) => {
      const { queryKey } = JSON.parse(event.data);
      queryClient.invalidateQueries({ queryKey });
    });
 
    eventSource.onerror = () => {
      console.error('SSE connection error');
      eventSource.close();
      // 再接続ロジック
      setTimeout(() => {
        // 再接続
      }, 5000);
    };
 
    return () => {
      eventSource.close();
    };
  }, [queryClient]);
}

// src/lib/query-client.ts
// グローバルなエラーハンドリング設定
 
import { QueryClient, QueryCache, MutationCache } from '@tanstack/react-query';
 
export const queryClient = new QueryClient({
  queryCache: new QueryCache({
    onError: (error, query) => {
      // 全てのクエリエラーをここでハンドリング
 
      // 認証エラー: ログインページにリダイレクト
      if (error instanceof ApiError && error.status === 401) {
        // トークン失効 → ログインページにリダイレクト
        window.location.href = '/login';
        return;
      }
 
      // 403 Forbidden: 権限不足の通知
      if (error instanceof ApiError && error.status === 403) {
        toast.error('この操作を行う権限がありません');
        return;
      }
 
      // 既にキャッシュにデータがある場合のみエラー通知
      // （初回ロードのエラーはコンポーネントレベルでハンドリング）
      if (query.state.data !== undefined) {
        toast.error(`データの更新に失敗しました: ${error.message}`);
      }
    },
  }),
 
  mutationCache: new MutationCache({
    onError: (error, variables, context, mutation) => {
      // 全てのMutationエラーをここでハンドリング
 
      // 認証エラー
      if (error instanceof ApiError && error.status === 401) {
        window.location.href = '/login';
        return;
      }
 
      // バリデーションエラーはコンポーネントレベルでハンドリング
      if (error instanceof ApiError && error.status === 422) {
        return; // グローバルではスキップ
      }
 
      // その他のエラー
      toast.error(`操作に失敗しました: ${error.message}`);
    },
  }),
 
  defaultOptions: {
    queries: {
      retry: (failureCount, error) => {
        // 特定のHTTPステータスではリトライしない
        if (error instanceof ApiError) {
          if ([400, 401, 403, 404, 422].includes(error.status)) {
            return false; // リトライしない
          }
        }
        // それ以外は3回までリトライ
        return failureCount < 3;
      },
      retryDelay: (attemptIndex) =>
        Math.min(1000 * 2 ** attemptIndex, 30000),
    },
  },
});

// Error Boundary と Suspense を使ったエラーハンドリング
 
import { QueryErrorResetBoundary } from '@tanstack/react-query';
import { ErrorBoundary } from 'react-error-boundary';
import { Suspense } from 'react';
 
function UserSection() {
  return (
    <QueryErrorResetBoundary>
      {({ reset }) => (
        <ErrorBoundary
          onReset={reset}
          fallbackRender={({ error, resetErrorBoundary }) => (
            <div className="p-4 border border-red-300 rounded-lg bg-red-50">
              <h3 className="font-bold text-red-800">
                データの取得に失敗しました
              </h3>
              <p className="text-red-600 mt-1">{error.message}</p>
              <button
                onClick={resetErrorBoundary}
                className="mt-3 px-4 py-2 bg-red-600 text-white rounded hover:bg-red-700"
              >
                再試行
              </button>
            </div>
          )}
        >
          <Suspense fallback={<UserListSkeleton />}>
            <UserList />
          </Suspense>
        </ErrorBoundary>
      )}
    </QueryErrorResetBoundary>
  );
}
 
// useSuspenseQuery でSuspense対応
function UserList() {
  // useSuspenseQuery は data が必ず存在する（undefined にならない）
  const { data: users } = useSuspenseQuery({
    queryKey: userKeys.lists(),
    queryFn: () => api.users.list(),
  });
 
  return (
    <ul>
      {users.map(user => (
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
}