0
# Client Management
1

2
Central client orchestration system for managing all query and mutation operations with intelligent defaults, caching strategies, and comprehensive lifecycle management.
3

4
## Capabilities
5

6
### QueryClient
7

8
The main client class that orchestrates all query and mutation operations.
9

10
```typescript { .api }
11
/**
12
 * Central client for managing queries and mutations
13
 * Provides configuration, lifecycle management, and cache access
14
 */
15
class QueryClient {
16
  constructor(config?: QueryClientConfig);
17
  
18
  // Lifecycle management
19
  mount(): void;
20
  unmount(): void;
21
  clear(): void;
22
  
23
  // Cache access
24
  getQueryCache(): QueryCache;
25
  getMutationCache(): MutationCache;
26
  
27
  // Query data operations
28
  getQueryData<T>(queryKey: QueryKey): T | undefined;
29
  setQueryData<T>(queryKey: QueryKey, updater: Updater<T>, options?: SetDataOptions): T | undefined;
30
  getQueriesData<T>(filters: QueryFilters): Array<[QueryKey, T | undefined]>;
31
  setQueriesData<T>(filters: QueryFilters, updater: Updater<T>, options?: SetDataOptions): Array<[QueryKey, T | undefined]>;
32
  getQueryState<T>(queryKey: QueryKey): QueryState<T> | undefined;
33
  
34
  // Query operations
35
  ensureQueryData<T>(options: EnsureQueryDataOptions<T>): Promise<T>;
36
  ensureInfiniteQueryData<T>(options: EnsureInfiniteQueryDataOptions<T>): Promise<InfiniteData<T>>;
37
  fetchQuery<T>(options: FetchQueryOptions<T>): Promise<T>;
38
  prefetchQuery<T>(options: FetchQueryOptions<T>): Promise<void>;
39
  fetchInfiniteQuery<T>(options: FetchInfiniteQueryOptions<T>): Promise<InfiniteData<T>>;
40
  prefetchInfiniteQuery<T>(options: FetchInfiniteQueryOptions<T>): Promise<void>;
41
  
42
  // Query lifecycle
43
  invalidateQueries(filters?: InvalidateQueryFilters, options?: InvalidateOptions): Promise<void>;
44
  refetchQueries(filters?: RefetchQueryFilters, options?: RefetchOptions): Promise<void>;
45
  cancelQueries(filters?: QueryFilters, options?: CancelOptions): Promise<void>;
46
  removeQueries(filters?: QueryFilters): void;
47
  resetQueries(filters?: QueryFilters, options?: ResetOptions): Promise<void>;
48
  
49
  // Configuration
50
  getDefaultOptions(): DefaultOptions;
51
  setDefaultOptions(options: DefaultOptions): void;
52
  setQueryDefaults(queryKey: QueryKey, options: Partial<QueryObserverOptions>): void;
53
  getQueryDefaults(queryKey: QueryKey): Partial<QueryObserverOptions>;
54
  setMutationDefaults(mutationKey: MutationKey, options: Partial<MutationObserverOptions>): void;
55
  getMutationDefaults(mutationKey: MutationKey): Partial<MutationObserverOptions>;
56
  
57
  // Status queries
58
  isFetching(filters?: QueryFilters): number;
59
  isMutating(filters?: MutationFilters): number;
60
  
61
  // Mutations
62
  resumePausedMutations(): Promise<unknown>;
63
}
64

65
interface QueryClientConfig {
66
  queryCache?: QueryCache;
67
  mutationCache?: MutationCache;
68
  defaultOptions?: DefaultOptions;
69
}
70

71
interface DefaultOptions {
72
  queries?: Partial<QueryObserverOptions>;
73
  mutations?: Partial<MutationObserverOptions>;
74
}
75

76
interface SetDataOptions {
77
  updatedAt?: number;
78
}
79
```
80

81
**Usage Examples:**
82

83
```typescript
84
import { QueryClient } from "@tanstack/query-core";
85

86
// Basic client setup
87
const queryClient = new QueryClient();
88

89
// Client with custom configuration
90
const queryClient = new QueryClient({
91
  defaultOptions: {
92
    queries: {
93
      staleTime: 5 * 60 * 1000, // 5 minutes
94
      gcTime: 10 * 60 * 1000,   // 10 minutes
95
      retry: 3,
96
    },
97
    mutations: {
98
      retry: 1,
99
    },
100
  },
101
});
102

103
// Mount client (in frameworks)
104
queryClient.mount();
105

106
// Get cached data
107
const userData = queryClient.getQueryData(['user', 123]);
108

109
// Set cached data
110
queryClient.setQueryData(['user', 123], (oldData) => ({
111
  ...oldData,
112
  name: 'Updated Name',
113
}));
114

115
// Fetch data imperatively
116
const user = await queryClient.fetchQuery({
117
  queryKey: ['user', 123],
118
  queryFn: async () => {
119
    const response = await fetch('/api/user/123');
120
    return response.json();
121
  },
122
});
123

124
// Invalidate and refetch queries
125
await queryClient.invalidateQueries({
126
  queryKey: ['user'],
127
});
128

129
// Cleanup
130
queryClient.unmount();
131
```
132

133
### Lifecycle Management
134

135
Methods for managing the client lifecycle and cleanup.
136

137
```typescript { .api }
138
/**
139
 * Mount the client and set up subscriptions
140
 * Should be called when the client is first used
141
 */
142
mount(): void;
143

144
/**
145
 * Unmount the client and cleanup subscriptions
146
 * Should be called when the client is no longer needed
147
 */
148
unmount(): void;
149

150
/**
151
 * Clear all queries and mutations from caches
152
 * Removes all cached data and resets state
153
 */
154
clear(): void;
155
```
156

157
### Data Access Methods
158

159
Direct access to cached query data with type safety.
160

161
```typescript { .api }
162
/**
163
 * Get cached data for a specific query
164
 * @param queryKey - The query key to retrieve data for
165
 * @returns The cached data or undefined if not found
166
 */
167
getQueryData<T>(queryKey: QueryKey): T | undefined;
168

169
/**
170
 * Set or update cached data for a specific query
171
 * @param queryKey - The query key to set data for
172
 * @param updater - New data or function to update existing data
173
 * @param options - Additional options for setting data
174
 * @returns The updated data
175
 */
176
setQueryData<T>(
177
  queryKey: QueryKey,
178
  updater: Updater<T>,
179
  options?: SetDataOptions
180
): T | undefined;
181

182
/**
183
 * Get cached data for multiple queries matching filters
184
 * @param filters - Query filters to match against
185
 * @returns Array of [queryKey, data] tuples
186
 */
187
getQueriesData<T>(filters: QueryFilters): Array<[QueryKey, T | undefined]>;
188

189
/**
190
 * Set cached data for multiple queries matching filters
191
 * @param filters - Query filters to match against
192
 * @param updater - New data or function to update existing data
193
 * @param options - Additional options for setting data
194
 * @returns Array of [queryKey, data] tuples
195
 */
196
setQueriesData<T>(
197
  filters: QueryFilters,
198
  updater: Updater<T>,
199
  options?: SetDataOptions
200
): Array<[QueryKey, T | undefined]>;
201

202
/**
203
 * Get the complete state for a specific query
204
 * @param queryKey - The query key to get state for
205
 * @returns The query state or undefined if not found
206
 */
207
getQueryState<T>(queryKey: QueryKey): QueryState<T> | undefined;
208
```
209

210
### Configuration Management
211

212
Methods for managing default options and query-specific defaults.
213

214
```typescript { .api }
215
/**
216
 * Get current default options for queries and mutations
217
 * @returns Current default options
218
 */
219
getDefaultOptions(): DefaultOptions;
220

221
/**
222
 * Set default options for all queries and mutations
223
 * @param options - New default options to merge
224
 */
225
setDefaultOptions(options: DefaultOptions): void;
226

227
/**
228
 * Set default options for queries matching a specific key
229
 * @param queryKey - Query key pattern to set defaults for
230
 * @param options - Default options for matching queries
231
 */
232
setQueryDefaults(queryKey: QueryKey, options: Partial<QueryObserverOptions>): void;
233

234
/**
235
 * Get default options for queries matching a specific key
236
 * @param queryKey - Query key pattern to get defaults for
237
 * @returns Default options for matching queries
238
 */
239
getQueryDefaults(queryKey: QueryKey): Partial<QueryObserverOptions>;
240

241
/**
242
 * Set default options for mutations matching a specific key
243
 * @param mutationKey - Mutation key pattern to set defaults for
244
 * @param options - Default options for matching mutations
245
 */
246
setMutationDefaults(mutationKey: MutationKey, options: Partial<MutationObserverOptions>): void;
247

248
/**
249
 * Get default options for mutations matching a specific key
250
 * @param mutationKey - Mutation key pattern to get defaults for
251
 * @returns Default options for matching mutations
252
 */
253
getMutationDefaults(mutationKey: MutationKey): Partial<MutationObserverOptions>;
254
```
255

256
### Status Queries
257

258
Methods for checking the status of queries and mutations.
259

260
```typescript { .api }
261
/**
262
 * Count the number of queries currently fetching
263
 * @param filters - Optional filters to narrow the count
264
 * @returns Number of fetching queries
265
 */
266
isFetching(filters?: QueryFilters): number;
267

268
/**
269
 * Count the number of mutations currently pending
270
 * @param filters - Optional filters to narrow the count
271
 * @returns Number of pending mutations
272
 */
273
isMutating(filters?: MutationFilters): number;
274
```
275

276
## Types
277

278
```typescript { .api }
279
interface QueryState<TData = unknown, TError = Error> {
280
  data: TData | undefined;
281
  dataUpdateCount: number;
282
  dataUpdatedAt: number;
283
  error: TError | null;
284
  errorUpdateCount: number;
285
  errorUpdatedAt: number;
286
  fetchFailureCount: number;
287
  fetchFailureReason: TError | null;
288
  fetchMeta: FetchMeta | null;
289
  isInvalidated: boolean;
290
  status: QueryStatus;
291
  fetchStatus: FetchStatus;
292
}
293

294
type MutationKey = ReadonlyArray<unknown>;
295

296
interface EnsureQueryDataOptions<T> extends FetchQueryOptions<T> {
297
  revalidateIfStale?: boolean;
298
}
299

300
interface EnsureInfiniteQueryDataOptions<T> extends FetchInfiniteQueryOptions<T> {
301
  revalidateIfStale?: boolean;
302
}
303

304
interface InvalidateOptions {
305
  refetchType?: 'active' | 'inactive' | 'all' | 'none';
306
}
307

308
interface RefetchOptions extends CancelOptions {
309
  throwOnError?: boolean;
310
}
311

312
interface CancelOptions {
313
  revert?: boolean;
314
  silent?: boolean;
315
}
316

317
interface ResetOptions extends RefetchOptions {}
318
```