What is the primary architectural purpose of the queryOptions() helper in TanStack Query v5?

queryOptions() allows developers to declare a complete query configuration (queryKey, queryFn, staleTime, gcTime, etc.) as a single reusable, strongly typed object outside components. It automatically binds and infers TQueryFnData, TError, and TData, allowing the same configuration object to be consumed by client.prefetchQuery on the server and useQuery/useSuspenseQuery on the client.

Why is 'as const' critical when building Query Key Factories?

Without 'as const', TypeScript widens string literals like 'users' to general string[] arrays. This destroys tuple length guarantees and literal markers, breaking type matching in queryOptions, preventing key type extraction via infer, and impairing hierarchical fuzzy matching during cache invalidation.

How does hierarchical fuzzy matching operate during cache invalidation?

queryClient.invalidateQueries({ queryKey: ['users'] }) evaluates active QueryCache entries, matching keys from left to right. Any key prefixed with 'users' (such as ['users', 'list'] or ['users', 'detail', '42']) is marked stale, triggering background refetches for mounted subscribers.

How do you type data transformations via selectors in useQuery?

useQuery accepts three core generics: useQuery . TQueryFnData is the raw data returned by queryFn. TData represents the transformed shape returned by the select(data) callback. When select is provided, useQuery strictly returns TData without altering underlying cached entries.

How does the Rollback mechanism work in useMutation, and how is its context typed?

onMutate executes before the network request. It captures a cache snapshot via queryClient.getQueryData and returns a context object (e.g., { previousData }). This object is typed as the 4th generic parameter in useMutation . If the mutation fails, this context is passed to onError, allowing precise rollback via setQueryData.

How does useInfiniteQuery typing differ from standard useQuery in v5?

useInfiniteQuery requires initialPageParam, and wraps return data in InfiniteData containing pages and pageParams arrays. getNextPageParam and getPreviousPageParam receive typed references to pages and must return the next pagination parameter or null/undefined.

How do you prevent race conditions during optimistic updates?

The first statement in onMutate must be await queryClient.cancelQueries({ queryKey }). This cancels any active in-flight refetches for that key, ensuring a late network response does not overwrite optimistic data before the mutation settles.

TanStack Query v5: Key Factories and End-to-End Mutation Typing — TypeScript 5.8+ Mastery

Architectural Foundation#

In large-scale web applications, TanStack Query (formerly React Query) v5 acts as an asynchronous distributed server state cache. The architectural cornerstone of this caching layer is the Query Key — a serializable array of string literals, identifiers, and filter objects acting as the primary key for request deduplication, cache storage, and invalidation.

In immature codebases, query keys are often declared ad-hoc as loose string arrays across UI components:

typescript

// Fragile code: a single typo breaks cache invalidation at runtime!
useQuery({ queryKey: ['users', id, 'detail'] });
queryClient.invalidateQueries({ queryKey: ['user', id, 'details'] }); // Silent failure!

To eliminate desynchronization and type drift, production architectures adopt the Query Key Factory Pattern paired with TanStack Query v5's core queryOptions() helper. This architectural approach delivers end-to-end type safety: from endpoint declarations to optimistic mutations backed by a strictly typed Rollback Context.

text

+-------------------------------------------------------------------------+
|                END-TO-END TYPE-SAFE CACHE ARCHITECTURE IN V5            |
+-------------------------------------------------------------------------+
| [Query Key Factory: userKeys.detail(id)]                                |
|   |--> Returns strictly typed tuple: readonly ['users', 'detail', string]
+-------------------------------------------------------------------------+
                                    |
                                    v
| [queryOptions({ queryKey, queryFn })]                                   |
|   |--> Binds query key type to queryFn arguments                        |
|   |--> Automatically infers TQueryFnData, TError, TData                 |
|   `-- Isomorphically shared: prefetchQuery (SSR) <-> useQuery (Client)  |
+-------------------------------------------------------------------------+
                                    |
                                    v
+-------------------------------------------------------------------------+
| [Type-Safe Mutation: 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    |
+-------------------------------------------------------------------------+

Mental Model#

Typing in TanStack Query v5 builds upon hierarchical projections and four-parameter generics:

Query Key Factory: A tree structure that allows developers to invalidate entire domain domains (['users']) or targeted queries (['users', 'list', { role: 'admin' }]).
queryOptions Helper: Eliminates the need to manually specify verbose generic arguments when calling useQuery.
Mutation Context: A strictly typed bridge linking optimistic execution to error recovery.
Transformed Data (TData): Provides type-safe data projection without altering underlying cached responses.

text

Hierarchical Query Key Factory Structure:
userKeys.all -------------------> ['users']
      |
      |-- userKeys.lists() -----> ['users', 'list']
      |     `-- userKeys.list(filter) -> ['users', 'list', { status: 'active' }]
      |
      `-- userKeys.details() ---> ['users', 'detail']
            `-- userKeys.detail(id) ----> ['users', 'detail', '42']

Invalidating ['users'] automatically clears all nested lists and detail views!

Practical Applications#

Fintech Platforms with Optimistic Balances: Instantly updating wallet balances locally upon transfers, while ensuring a bulletproof rollback using typed MutationRollbackContext if the server returns a 500 error.
Infinite Data Catalogs: Paginating product catalogs with typed cursor calculation via getNextPageParam and strict validation across InfiniteData<PageResponse>.
Isomorphic Data Fetching in Next.js App Router: Sharing identical queryOptions declarations between server-side prefetchQuery in React Server Components and client-side useSuspenseQuery.
Real-Time DataGrid Cell Editing: Processing background mutations on data tables with deduplicated cache invalidations through centralized factory keys.

How It Works#

1. Pure TypeScript Query Key Factory#

Here is a zero-dependency, hierarchical query key factory for a User entity:

typescriptsrc/api/userKeys.ts

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

/**
 * Hierarchical query key factory for user entities.
 * Each method returns a strictly typed, immutable readonly tuple.
 */
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;

2. Typing with `queryOptions` and Data Selectors#

In TanStack Query v5, the queryOptions helper automatically binds the queryFn return type to the options structure:

typescriptsrc/api/userQueries.ts

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] Failed to load user: ${res.statusText}`);
  }
  return (await res.json()) as UserDto;
}

/**
 * Type-safe user detail query options.
 * TQueryFnData = UserDto
 * TError = Error
 */
export const userDetailQueryOptions = (userId: string) =>
  queryOptions({
    queryKey: userKeys.detail(userId),
    queryFn: ({ signal }) => fetchUserById(userId, signal),
    staleTime: 60 * 1000, // 1 minute
  });

/**
 * Query configuration with data transformation via select:
 * Selects only formatted display name and currency balance.
 */
export const userBalanceSummaryOptions = (userId: string) =>
  queryOptions({
    ...userDetailQueryOptions(userId),
    // TData is inferred from the select return type
    select: (user): { name: string; balanceUsd: string } => ({
      name: user.fullName,
      balanceUsd: `$${(user.balanceCents / 100).toFixed(2)}`,
    }),
  });

3. End-to-End Optimistic Mutation with Rollback Context#

When designing optimistic updates, you must bind the return type of onMutate to the context parameter in onError:

typescriptsrc/api/useUpdateUserBalance.ts

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] Balance update failed: ${res.status}`);
      }

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

    // 1. Optimistic update and context snapshot capture
    onMutate: async ({ userId, deltaCents }) => {
      const queryKey = userKeys.detail(userId);

      // Cancel outgoing refetches to avoid overwriting optimistic updates
      await queryClient.cancelQueries({ queryKey });

      // Snapshot current cache state
      const previousUser = queryClient.getQueryData<UserDto>(queryKey);

      // Optimistically write new balance
      if (previousUser) {
        queryClient.setQueryData<UserDto>(queryKey, {
          ...previousUser,
          balanceCents: previousUser.balanceCents + deltaCents,
        });
      }

      // Return strictly typed rollback context
      return { previousUser };
    },

    // 2. Rollback on network or server error
    onError: (_err, { userId }, context) => {
      if (context?.previousUser) {
        queryClient.setQueryData(userKeys.detail(userId), context.previousUser);
      }
    },

    // 3. Revalidate via key factory on completion
    onSettled: (_data, _error, { userId }) => {
      void queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) });
    },
  });
}

4. Typed Infinite Queries with Cursors#

typescriptsrc/api/useUserInfiniteList.ts

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('Failed to load user list');
      return (await res.json()) as PaginatedUsersResponse;
    },
    getNextPageParam: (lastPage) => lastPage.nextCursor,
    getPreviousPageParam: () => null,
  });
}

Architecture Pipeline

End-to-End Query Lifecycle Typing Pipeline

4 stages

1. Key Generation via Factory

as const TupleCore / System

The factory generates an immutable key tuple, preventing string literal desynchronization during invalidation.

Artifacts:userKeys.detail('42') -> readonly ['users', 'detail', '42']

2. Encapsulation with queryOptions

queryOptions()Template / UI

Combines the key, network promise, and cache policy into an isomorphic options bundle, auto-inferring payload types.

Artifacts:TQueryFnData = UserDtoTError = Error

3. Typed Optimistic Mutation

Mutation Context GuardAutonomous Agent

onMutate cancels active queries, captures a cache snapshot into MutationRollbackContext, and writes local updates.

Artifacts:context: { previousUser: UserDto }

4. Rollback or Revalidation

Cache SynchronizationCore / System

On failure, onError uses context to restore the cache. onSettled invalidates the target slice using the factory key.

Artifacts:queryClient.setQueryData(key, context.previousUser)

Comparison: Raw String Keys vs Query Key Factory#

Comparison of Cache Key Architecture Strategies

Критерий	Raw String Arrays (['users', id])	Query Key Factory (userKeys.detail(id))
Typo resilience	Zero: A single typographical error silently breaks cache invalidation	Absolute: Full TypeScript compiler autocompletion across methods and params
Cascading subtree invalidation	Fragile: Developers must manually remember array prefix conventions	Deterministic: Calling invalidateQueries(userKeys.lists()) invalidates all lists
SSR and client sharing	Duplicate parameter declarations across page.tsx and client components	Single queryOptions object reused across prefetchQuery and useQuery
Endpoint refactoring	Requires searching and replacing string literals across the entire codebase	Updating the factory tuple in one file automatically updates project types

Production Artifact: Typed Entity Cache Manager#

Production Artifactsrc/api/entityCacheManager.ts

Coordinator class providing type-safe cache invalidation, hierarchical subtree flushes, and memory cleanup.

typescript

import { QueryClient } from '@tanstack/react-query';
import { userKeys } from './userKeys';

export class EntityCacheManager {
  constructor(private readonly queryClient: QueryClient) {}

  /**
   * Invalidates all cached queries related to users
   */
  public async invalidateAllUsers(): Promise<void> {
    await this.queryClient.invalidateQueries({
      queryKey: userKeys.all,
    });
  }

  /**
   * Invalidates all user lists while leaving active detail views cached
   */
  public async invalidateUserLists(): Promise<void> {
    await this.queryClient.invalidateQueries({
      queryKey: userKeys.lists(),
    });
  }

  /**
   * Forcibly purges a specific user's detail record from memory
   */
  public removeUserDetail(userId: string): void {
    this.queryClient.removeQueries({
      queryKey: userKeys.detail(userId),
      exact: true,
    });
  }
}

Common Pitfalls#

Ошибка: Tuple type widening caused by missing 'as const'

If you omit as const when declaring query keys, TypeScript widens string literals like 'users' and 'detail' to string[]. This breaks fuzzy matching, type narrowing, and tuple autocompletion.

typescript

// ❌ WRONG: Widened to generic string[]
export const badKeys = {
  all: ['users'], // string[]
};

// ✅ CORRECT: Preserved as immutable literal tuple
export const goodKeys = {
  all: ['users'] as const, // readonly ['users']
};

Ошибка: Untyped Mutation Context causing unhandled exceptions

Omitting the 4th generic parameter in useMutation<TData, TError, TVariables, TContext> causes TypeScript to assign unknown to context. Accessing context.previousUser in onError will produce compiler error TS2339.

typescript

// ❌ WRONG: Context omitted, defaults to unknown
useMutation({
  onMutate: () => ({ prev: 10 }),
  onError: (err, vars, context) => {
    // context.prev -> Error TS2339: Property 'prev' does not exist on type 'unknown'
  }
});

// ✅ CORRECT: Explicit context generic declaration
useMutation<Data, Error, Vars, { prev: number }>({ ... });

Ошибка: Omitting AbortSignal in queryFn

If your fetcher function ignores the signal argument, the browser cannot abort in-flight network requests when a component unmounts or navigation occurs.

typescript

// ❌ WRONG: Non-cancellable request
queryFn: () => fetch('/api/data').then(r => r.json());

// ✅ CORRECT: Forwarding the AbortSignal
queryFn: ({ signal }) => fetch('/api/data', { signal }).then(r => r.json());

Ошибка: Directly mutating cache references instead of returning new objects

Mutating properties on objects retrieved from getQueryData breaks React Fiber referential equality and stops subscriber components from re-rendering.

typescript

// ❌ WRONG: Direct cache mutation
const user = queryClient.getQueryData(['users', id]);
user.balance = 500; // FORBIDDEN: Mutates cache reference directly!

// ✅ CORRECT: Functional immutable update
queryClient.setQueryData(['users', id], (old: User | undefined) =>
  old ? { ...old, balance: 500 } : undefined
);

Step-by-Step Architecture for TanStack Query Layers

Define Query Key Factory

Declare a hierarchical object returning immutable readonly tuples with as const.

Encapsulate via queryOptions

Define query configurations pairing queryKey, typed queryFn, staleTime, and selectors.

Integrate with Server Components

Pass queryOptions to server-side prefetchQuery to eliminate client waterfall requests.

Implement Optimistic Mutations

Configure useMutation with typed TContext for robust rollback during network errors.

Coordinate Cache Invalidation

Use key factory methods inside onSettled callbacks for deterministic cache invalidations.

Interview Questions: Advanced TanStack Query v5 Typing7 questions

TanStack Query v5: Key Factories and End-to-End Mutation Typing

Architectural Foundation#

Mental Model#

Practical Applications#

How It Works#

1. Pure TypeScript Query Key Factory#

2. Typing with queryOptions and Data Selectors#

3. End-to-End Optimistic Mutation with Rollback Context#

4. Typed Infinite Queries with Cursors#

End-to-End Query Lifecycle Typing Pipeline

1. Key Generation via Factory

2. Encapsulation with queryOptions

3. Typed Optimistic Mutation

4. Rollback or Revalidation

Comparison: Raw String Keys vs Query Key Factory#

Production Artifact: Typed Entity Cache Manager#

Common Pitfalls#

Ошибка: Tuple type widening caused by missing 'as const'

Ошибка: Untyped Mutation Context causing unhandled exceptions

Ошибка: Omitting AbortSignal in queryFn

Ошибка: Directly mutating cache references instead of returning new objects

Architectural Foundation#

Mental Model#

Practical Applications#

How It Works#

1. Pure TypeScript Query Key Factory#

2. Typing with queryOptions and Data Selectors#

3. End-to-End Optimistic Mutation with Rollback Context#

4. Typed Infinite Queries with Cursors#

End-to-End Query Lifecycle Typing Pipeline

1. Key Generation via Factory

2. Encapsulation with queryOptions

3. Typed Optimistic Mutation

4. Rollback or Revalidation

Comparison: Raw String Keys vs Query Key Factory#

Production Artifact: Typed Entity Cache Manager#

Common Pitfalls#

Ошибка: Tuple type widening caused by missing 'as const'

Ошибка: Untyped Mutation Context causing unhandled exceptions

Ошибка: Omitting AbortSignal in queryFn

Ошибка: Directly mutating cache references instead of returning new objects

2. Typing with `queryOptions` and Data Selectors#

2. Typing with `queryOptions` and Data Selectors#