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

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

+-------------------------------------------------------------------------+
|                АРХИТЕКТУРА СКВОЗНОЙ ТИПИЗАЦИИ КЭША В V5                 |
+-------------------------------------------------------------------------+
| [Query Key Factory: usersKeys.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 минута
  });

/**
 * Конфигурация с трансформацией данных через select:
 * Выбирает только форматированное имя и баланс в долларах.
 */
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, userDetailQueryOptions } 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);

      // Отменяем фоновые refetch-запросы, чтобы они не затерли оптимистичный UI
      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,
  });
}