0
# TanStack Angular Query (Experimental)
1

2
TanStack Angular Query (Experimental) is an Angular adapter for TanStack Query that enables reactive data fetching, caching, and state management using Angular's signals system. It provides transport-agnostic data fetching capabilities supporting REST, GraphQL, and any promise-based data sources, with automatic caching and refetching strategies.
3

4
## Package Information
5

6
- **Package Name**: @tanstack/angular-query-experimental
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tanstack/angular-query-experimental`
10
- **Minimum Requirements**: Angular 16+ (for signals support)
11

12
## Core Imports
13

14
```typescript
15
import { 
16
  provideTanStackQuery, 
17
  QueryClient,
18
  injectQuery,
19
  injectMutation,
20
  injectInfiniteQuery
21
} from "@tanstack/angular-query-experimental";
22
```
23

24
For CommonJS:
25

26
```javascript
27
const { 
28
  provideTanStackQuery, 
29
  QueryClient,
30
  injectQuery,
31
  injectMutation 
32
} = require("@tanstack/angular-query-experimental");
33
```
34

35
## Basic Usage
36

37
```typescript
38
// 1. Bootstrap with TanStack Query
39
import { provideTanStackQuery, QueryClient } from "@tanstack/angular-query-experimental";
40

41
bootstrapApplication(AppComponent, {
42
  providers: [provideTanStackQuery(new QueryClient())],
43
});
44

45
// 2. Use in components/services
46
import { injectQuery, injectMutation } from "@tanstack/angular-query-experimental";
47
import { Component, inject } from "@angular/core";
48
import { HttpClient } from "@angular/common/http";
49

50
@Component({
51
  selector: 'app-todos',
52
  template: `
53
    <div *ngIf="todosQuery.isPending()">Loading...</div>
54
    <div *ngIf="todosQuery.isError()">Error: {{ todosQuery.error()?.message }}</div>
55
    <div *ngIf="todosQuery.isSuccess()">
56
      <ul>
57
        <li *ngFor="let todo of todosQuery.data()">{{ todo.title }}</li>
58
      </ul>
59
    </div>
60
  `
61
})
62
export class TodosComponent {
63
  #http = inject(HttpClient);
64
  
65
  // Query with signals - automatically reactive
66
  todosQuery = injectQuery(() => ({
67
    queryKey: ['todos'],
68
    queryFn: () => this.#http.get<Todo[]>('/api/todos')
69
  }));
70

71
  // Mutation for creating todos
72
  createTodoMutation = injectMutation(() => ({
73
    mutationFn: (todo: CreateTodo) => this.#http.post<Todo>('/api/todos', todo),
74
    onSuccess: () => {
75
      // Invalidate and refetch todos
76
      inject(QueryClient).invalidateQueries({ queryKey: ['todos'] });
77
    }
78
  }));
79
}
80

81
interface Todo {
82
  id: number;
83
  title: string;
84
  completed: boolean;
85
}
86

87
interface CreateTodo {
88
  title: string;
89
}
90
```
91

92
## Architecture
93

94
TanStack Angular Query is built around several key components:
95

96
- **Injection Functions**: Primary API using Angular's dependency injection (`injectQuery`, `injectMutation`, etc.)
97
- **Signals Integration**: All hooks return Angular signals for reactive data access  
98
- **QueryClient**: Core client for managing queries, mutations, and cache
99
- **Provider System**: Angular provider functions for app-wide setup
100
- **Transport Agnostic**: Works with any promise-based data source (HTTP, GraphQL, etc.)
101
- **Developer Tools**: Optional devtools for debugging and monitoring
102

103
## Capabilities
104

105
### Query Management
106

107
Core query functionality for fetching and caching data with automatic refetching, stale-while-revalidate patterns, and reactive updates.
108

109
```typescript { .api }
110
function injectQuery<TQueryFnData, TError, TData, TQueryKey>(
111
  injectQueryFn: () => CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
112
  options?: InjectQueryOptions
113
): CreateQueryResult<TData, TError>;
114

115
interface CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> {
116
  queryKey: TQueryKey;
117
  queryFn: QueryFunction<TQueryFnData, TQueryKey>;
118
  enabled?: boolean;
119
  staleTime?: number;
120
  refetchOnWindowFocus?: boolean;
121
  // ... other query options
122
}
123

124
interface CreateQueryResult<TData, TError> {
125
  data: Signal<TData | undefined>;
126
  error: Signal<TError | null>;
127
  isLoading: Signal<boolean>;
128
  isPending: Signal<boolean>;
129
  isSuccess: Signal<boolean>;
130
  isError: Signal<boolean>;
131
  // ... other result properties
132
}
133
```
134

135
[Query Management](./query-management.md)
136

137
### Mutation Management
138

139
Mutation functionality for server-side effects with optimistic updates, error handling, and automatic query invalidation.
140

141
```typescript { .api }
142
function injectMutation<TData, TError, TVariables, TContext>(
143
  injectMutationFn: () => CreateMutationOptions<TData, TError, TVariables, TContext>,
144
  options?: InjectMutationOptions
145
): CreateMutationResult<TData, TError, TVariables, TContext>;
146

147
interface CreateMutationOptions<TData, TError, TVariables, TContext> {
148
  mutationFn: MutationFunction<TData, TVariables>;
149
  onSuccess?: (data: TData, variables: TVariables, context: TContext) => void;
150
  onError?: (error: TError, variables: TVariables, context: TContext) => void;
151
  // ... other mutation options
152
}
153

154
interface CreateMutationResult<TData, TError, TVariables, TContext> {
155
  mutate: CreateMutateFunction<TData, TError, TVariables, TContext>;
156
  mutateAsync: CreateMutateAsyncFunction<TData, TError, TVariables, TContext>;
157
  data: Signal<TData | undefined>;
158
  error: Signal<TError | null>;
159
  isSuccess: Signal<boolean>;
160
  isError: Signal<boolean>;
161
  isPending: Signal<boolean>;
162
  // ... other result properties
163
}
164
```
165

166
[Mutation Management](./mutation-management.md)
167

168
### Infinite Queries
169

170
Infinite query functionality for pagination and infinite scrolling with automatic data accumulation and page management.
171

172
```typescript { .api }
173
function injectInfiniteQuery<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
174
  injectInfiniteQueryFn: () => CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>,
175
  options?: InjectInfiniteQueryOptions
176
): CreateInfiniteQueryResult<TData, TError>;
177

178
interface CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> {
179
  queryKey: TQueryKey;
180
  queryFn: InfiniteQueryFunction<TQueryFnData, TQueryKey, TPageParam>;
181
  initialPageParam: TPageParam;
182
  getNextPageParam: (lastPage: TQueryFnData, allPages: TQueryFnData[], lastPageParam: TPageParam) => TPageParam | null;
183
  getPreviousPageParam?: (firstPage: TQueryFnData, allPages: TQueryFnData[], firstPageParam: TPageParam) => TPageParam | null;
184
  // ... other infinite query options
185
}
186
```
187

188
[Infinite Queries](./infinite-queries.md)
189

190
### Provider Setup
191

192
Provider functions for setting up TanStack Query in Angular applications with optional features like developer tools.
193

194
```typescript { .api }
195
function provideTanStackQuery(
196
  queryClient: QueryClient | InjectionToken<QueryClient>,
197
  ...features: Array<QueryFeatures>
198
): Array<Provider>;
199

200
function withDevtools(
201
  withDevtoolsFn?: () => DevtoolsOptions
202
): DeveloperToolsFeature;
203

204
interface DevtoolsOptions {
205
  initialIsOpen?: boolean;
206
  buttonPosition?: DevtoolsButtonPosition;
207
  position?: DevtoolsPosition;
208
  loadDevtools?: 'auto' | boolean;
209
  // ... other devtools options
210
}
211
```
212

213
[Provider Setup](./provider-setup.md)
214

215
### Status Monitoring
216

217
Functions for monitoring query and mutation states across the application for loading indicators and debugging.
218

219
```typescript { .api }
220
function injectIsFetching(
221
  filters?: QueryFilters,
222
  options?: InjectIsFetchingOptions
223
): Signal<number>;
224

225
function injectIsMutating(
226
  filters?: MutationFilters,
227
  options?: InjectIsMutatingOptions
228
): Signal<number>;
229

230
function injectIsRestoring(
231
  options?: InjectIsRestoringOptions
232
): Signal<boolean>;
233
```
234

235
[Status Monitoring](./status-monitoring.md)
236

237
### Multi-Query Operations
238

239
Functions for handling multiple queries simultaneously with type-safe results and combined operations.
240

241
```typescript { .api }
242
function injectQueries<T extends Array<any>, TCombinedResult = QueriesResults<T>>(
243
  config: {
244
    queries: Signal<[...QueriesOptions<T>]>;
245
    combine?: (result: QueriesResults<T>) => TCombinedResult;
246
  },
247
  injector?: Injector
248
): Signal<TCombinedResult>;
249

250
function injectMutationState<TResult = MutationState>(
251
  injectMutationStateFn?: () => MutationStateOptions<TResult>,
252
  options?: InjectMutationStateOptions
253
): Signal<Array<TResult>>;
254
```
255

256
[Multi-Query Operations](./multi-query-operations.md)
257

258
### Options Helpers
259

260
Type-safe utility functions for creating reusable query and mutation options with proper type inference.
261

262
```typescript { .api }
263
function queryOptions<TQueryFnData, TError, TData, TQueryKey>(
264
  options: CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey>
265
): CreateQueryOptions<TQueryFnData, TError, TData, TQueryKey> & {
266
  queryKey: DataTag<TQueryKey, TQueryFnData, TError>;
267
};
268

269
function infiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>(
270
  options: CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
271
): CreateInfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam> & {
272
  queryKey: DataTag<TQueryKey, InfiniteData<TQueryFnData>, TError>;
273
};
274

275
function mutationOptions<TData, TError, TVariables, TContext>(
276
  options: CreateMutationOptions<TData, TError, TVariables, TContext>
277
): CreateMutationOptions<TData, TError, TVariables, TContext>;
278
```
279

280
[Options Helpers](./options-helpers.md)
281

282
## Core Type Definitions
283

284
```typescript { .api }
285
// Re-exported from @tanstack/query-core
286
class QueryClient {
287
  constructor(config?: QueryClientConfig);
288
  getQueryData<TData>(queryKey: QueryKey): TData | undefined;
289
  setQueryData<TData>(queryKey: QueryKey, data: TData): TData;
290
  invalidateQueries(filters?: QueryFilters): Promise<void>;
291
  // ... other QueryClient methods
292
}
293

294
// Angular-specific injection options
295
interface InjectQueryOptions {
296
  injector?: Injector;
297
}
298

299
interface InjectMutationOptions {
300
  injector?: Injector;
301
}
302

303
interface InjectInfiniteQueryOptions {
304
  injector?: Injector;
305
}
306

307
// Common type aliases
308
type QueryKey = ReadonlyArray<unknown>;
309
type DefaultError = Error;
310
```