TanStack Query v5: фабрики ключів та наскрізна типізація мутацій

// Крихкий код: одруківка в одному символі ламає інвалідацію кешу в рантаймі!
useQuery({ queryKey: ['users', id, 'detail'] });
queryClient.invalidateQueries({ queryKey: ['user', id, 'details'] }); // Тихий збій!

+-------------------------------------------------------------------------+
|                АРХІТЕКТУРА НАСКРІЗНОЇ ТИПІЗАЦІЇ КЕШУ В V5               |
+-------------------------------------------------------------------------+
| [Query Key Factory: userKeys.detail(id)]                                |
|   |--> Повертає строго типізований кортеж: readonly ['users', 'detail', string]
+-------------------------------------------------------------------------+
                                    |
                                    v
| [queryOptions({ queryKey, queryFn })]                                   |
|   |--> Зв'язує тип ключа з параметрами queryFn                          |
|   |--> Автоматично виводить TQueryFnData, TError, TData                 |
|   `-- Ізоморфне використання: prefetchQuery (SSR) <-> useQuery (Client) |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
| [Наскрізна мутація: useMutation<User, Error, UpdatePayload, Context>]   |
|   |-- onMutate:  (vars) => Promise<{ previousUser: User | undefined }>  |
|   |-- onError:   (err, vars, context: Context | undefined) => Rollback |
|   `-- onSettled: (data, err, vars, context) => Invalidate by Factory    |
+-------------------------------------------------------------------------+

Ієрархічна структура Query Key Factory:
userKeys.all -------------------> ['users']
      |
      |-- userKeys.lists() -----> ['users', 'list']
      |     `-- userKeys.list(filter) -> ['users', 'list', { status: 'active' }]
      |
      `-- userKeys.details() ---> ['users', 'detail']
            `-- userKeys.detail(id) ----> ['users', 'detail', '42']

Інвалідація ['users'] автоматично скидає всі вкладені списки та детальні дані!

export interface UserListFilters {
  readonly role?: 'admin' | 'member';
  readonly search?: string;
  readonly page?: number;
}

/**
 * Ієрархічна фабрика ключів кешу користувачів.
 * Кожен метод повертає строго типізований незмінний кортеж readonly.
 */
export const userKeys = {
  all: ['users'] as const,
  lists: () => [...userKeys.all, 'list'] as const,
  list: (filters: UserListFilters) => [...userKeys.lists(), filters] as const,
  details: () => [...userKeys.all, 'detail'] as const,
  detail: (userId: string) => [...userKeys.details(), userId] as const,
};

export type UserKeys = typeof userKeys;

import { queryOptions } from '@tanstack/react-query';
import { userKeys, UserListFilters } from './userKeys';

export interface UserDto {
  readonly id: string;
  readonly fullName: string;
  readonly email: string;
  readonly createdAt: string;
  readonly balanceCents: number;
}

async function fetchUserById(userId: string, signal?: AbortSignal): Promise<UserDto> {
  const res = await fetch(`/api/users/${userId}`, { signal });
  if (!res.ok) {
    throw new Error(`[ApiError] Не вдалося завантажити користувача: ${res.statusText}`);
  }
  return (await res.json()) as UserDto;
}

/**
 * Типобезпечна конфігурація запиту користувача.
 * TQueryFnData = UserDto
 * TError = Error
 */
export const userDetailQueryOptions = (userId: string) =>
  queryOptions({
    queryKey: userKeys.detail(userId),
    queryFn: ({ signal }) => fetchUserById(userId, signal),
    staleTime: 60 * 1000, // 1 хвилина
  });

/**
 * Конфігурація із селектором:
 * Обирає лише форматоване ім'я та баланс у доларах.
 */
export const userBalanceSummaryOptions = (userId: string) =>
  queryOptions({
    ...userDetailQueryOptions(userId),
    // TData виводиться на основі результату select
    select: (user): { name: string; balanceUsd: string } => ({
      name: user.fullName,
      balanceUsd: `$${(user.balanceCents / 100).toFixed(2)}`,
    }),
  });

import { useMutation, useQueryClient } from '@tanstack/react-query';
import { userKeys } from './userKeys';
import { UserDto } from './userQueries';

export interface UpdateBalanceVariables {
  readonly userId: string;
  readonly deltaCents: number;
}

export interface MutationRollbackContext {
  readonly previousUser: UserDto | undefined;
}

export function useUpdateUserBalance() {
  const queryClient = useQueryClient();

  return useMutation<UserDto, Error, UpdateBalanceVariables, MutationRollbackContext>({
    mutationFn: async ({ userId, deltaCents }) => {
      const res = await fetch(`/api/users/${userId}/balance`, {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ deltaCents }),
      });

      if (!res.ok) {
        throw new Error(`[MutationError] Помилка оновлення балансу: ${res.status}`);
      }

      return (await res.json()) as UserDto;
    },

    // 1. Оптимістичне оновлення та фіксація знімка стану
    onMutate: async ({ userId, deltaCents }) => {
      const queryKey = userKeys.detail(userId);

      // Скасовуємо фонові запити, щоб вони не перезаписали локальний стан
      await queryClient.cancelQueries({ queryKey });

      // Робимо знімок поточних даних
      const previousUser = queryClient.getQueryData<UserDto>(queryKey);

      // Оптимістично оновлюємо кеш
      if (previousUser) {
        queryClient.setQueryData<UserDto>(queryKey, {
          ...previousUser,
          balanceCents: previousUser.balanceCents + deltaCents,
        });
      }

      // Повертаємо строго типізований контекст для відкату
      return { previousUser };
    },

    // 2. Відкат у разі мережевої або серверної помилки
    onError: (_err, { userId }, context) => {
      if (context?.previousUser) {
        queryClient.setQueryData(userKeys.detail(userId), context.previousUser);
      }
    },

    // 3. Інвалідація через фабрику ключів після завершення
    onSettled: (_data, _error, { userId }) => {
      void queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) });
    },
  });
}

import { useInfiniteQuery } from '@tanstack/react-query';
import { userKeys } from './userKeys';
import { UserDto } from './userQueries';

export interface PaginatedUsersResponse {
  readonly users: ReadonlyArray<UserDto>;
  readonly nextCursor: string | null;
}

export function useUserInfiniteList(role?: 'admin' | 'member') {
  return useInfiniteQuery<
    PaginatedUsersResponse, // TQueryFnData
    Error,                  // TError
    PaginatedUsersResponse, // TData
    readonly ['users', 'list', { role?: 'admin' | 'member' }], // TQueryKey
    string | null           // TPageParam
  >({
    queryKey: userKeys.list({ role }),
    initialPageParam: null,
    queryFn: async ({ pageParam, signal }) => {
      const url = new URL('/api/users', window.location.origin);
      if (role) url.searchParams.set('role', role);
      if (pageParam) url.searchParams.set('cursor', pageParam);

      const res = await fetch(url.toString(), { signal });
      if (!res.ok) throw new Error('Помилка завантаження списку');
      return (await res.json()) as PaginatedUsersResponse;
    },
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    getPreviousPageParam: () => null,
  });
}