Skip to content
Source
Sign inSign up
TanStack/query
Open History to see the last commit

queryOptions.md

332 lines12.1 KB

1---
2id: queryOptions
3title: queryOptions
4---
5​
6<!-- DO NOT EDIT: this page is autogenerated from the type comments -->
7​
8## Overview
9​
10```ts
11function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
12function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
13function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
14```
15​
16- [`DefinedInitialDataOptions` β†’ `DefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-1): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for.
17- [`UnusedSkipTokenOptions` β†’ `UnusedSkipTokenOptions & QueryKeyWithDataTag`](#call-signature-2): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for.
18- [`UndefinedInitialDataOptions` β†’ `UndefinedInitialDataOptions & QueryKeyWithDataTag`](#call-signature-3): You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is required and is the query key to generate options for.
19​
20See also: [Parameters](#parameters-summary) Β· [Returns](#returns-summary)
21​
22<a id="call-signature-1"></a>
23​
24## Call Signature
25​
26```ts
27function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): DefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
28```
29​
30Defined in: [packages/angular-query-experimental/src/query-options.ts:149](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L149)
31​
32You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
33can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
34required and is the query key to generate options for.
35​
36This overload is selected when `initialData` is known to be defined, so the resulting `data` is never
37`undefined` (unless a `select` changes `TData` to include `undefined`).
38​
39### Type Parameters
40​
41#### TQueryFnData
42​
43`TQueryFnData` = `unknown`
44​
45#### TError
46​
47`TError` = `Error`
48​
49#### TData
50​
51`TData` = `TQueryFnData`
52​
53#### TQueryKey
54​
55`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
56​
57### Parameters
58​
59#### options
60​
61[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
62​
63The [DefinedInitialDataOptions](../type-aliases/DefinedInitialDataOptions.md) to use β€” everything you can pass to `injectQuery`,
64with `initialData` known to be defined.
65​
66### Returns
67​
68[`DefinedInitialDataOptions`](../type-aliases/DefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
69​
70The same options object, typed so that `queryKey` carries the inferred data type.
71​
72### See
73​
74 - [injectQuery](injectQuery.md) to run a query with these options.
75 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
76​
77### Example
78​
79```angular-ts
80import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
81​
82export const postsOptions = queryOptions({
83 queryKey: ['posts'],
84 queryFn: fetchPosts,
85 initialData: [],
86})
87​
88@Component({
89 selector: 'posts',
90 template: `
91 <!-- `postsQuery.data()` is never `undefined`, thanks to `initialData` β€” even if a refetch
92 fails, so the list stays visible alongside the error. -->
93 @if (postsQuery.isError()) {
94 <span>Error: {{ postsQuery.error()?.message }}</span>
95 }
96 <ul>
97 @for (post of postsQuery.data(); track post.id) {
98 <li>{{ post.title }}</li>
99 }
100 </ul>
101 `,
102})
103export class Posts {
104 readonly postsQuery = injectQuery(() => postsOptions)
106```
107​
108<a id="call-signature-2"></a>
109​
110## Call Signature
111​
112```ts
113function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey>): UnusedSkipTokenOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
114```
115​
116Defined in: [packages/angular-query-experimental/src/query-options.ts:196](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L196)
117​
118You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
119can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
120required and is the query key to generate options for.
121​
122### Type Parameters
123​
124#### TQueryFnData
125​
126`TQueryFnData` = `unknown`
127​
128#### TError
129​
130`TError` = `Error`
131​
132#### TData
133​
134`TData` = `TQueryFnData`
135​
136#### TQueryKey
137​
138`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
139​
140### Parameters
141​
142#### options
143​
144[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
145​
146The [UnusedSkipTokenOptions](../type-aliases/UnusedSkipTokenOptions.md) to use β€” everything you can pass to `injectQuery`.
147​
148### Returns
149​
150[`UnusedSkipTokenOptions`](../type-aliases/UnusedSkipTokenOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
151​
152The same options object, typed so that `queryKey` carries the inferred data type.
153​
154### See
155​
156 - [injectQuery](injectQuery.md) to run a query with these options.
157 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
158​
159### Example
160​
161A parameterized factory, so the same options object can be reused per `id`:
162```angular-ts
163import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
164​
165export const postOptions = (id: string) =>
166 queryOptions({
167 queryKey: ['post', id],
168 queryFn: () => fetchPost(id),
169 })
170​
171@Component({
172 selector: 'post',
173 template: `
174 @if (postQuery.isPending()) {
175 Loading...
176 } @else if (postQuery.isError()) {
177 <span>Error: {{ postQuery.error()?.message }}</span>
178 } @else {
179 <h1>{{ postQuery.data().title }}</h1>
180 }
181 `,
182})
183export class Post {
184 readonly id = signal('1')
185 readonly postQuery = injectQuery(() => postOptions(this.id()))
187```
188​
189<a id="call-signature-3"></a>
190​
191## Call Signature
192​
193```ts
194function queryOptions<TQueryFnData = unknown, TError = Error, TData = TQueryFnData, TQueryKey extends readonly unknown[] = readonly unknown[]>(options: UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey>): UndefinedInitialDataOptions<TQueryFnData, TError, TData, TQueryKey> & QueryKeyWithDataTag<TQueryKey, TQueryFnData, TError>;
195```
196​
197Defined in: [packages/angular-query-experimental/src/query-options.ts:274](https://github.com/TanStack/query/blob/main/packages/angular-query-experimental/src/query-options.ts#L274)
198​
199You can generally pass everything to `queryOptions` that you can also pass to `injectQuery`. These options
200can be shared across functions and imperative APIs such as `queryClient.fetchQuery`. `options.queryKey` is
201required and is the query key to generate options for.
202​
203### Type Parameters
204​
205#### TQueryFnData
206​
207`TQueryFnData` = `unknown`
208​
209#### TError
210​
211`TError` = `Error`
212​
213#### TData
214​
215`TData` = `TQueryFnData`
216​
217#### TQueryKey
218​
219`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
220​
221### Parameters
222​
223#### options
224​
225[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
226​
227The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β€” everything you can pass to `injectQuery`.
228​
229### Returns
230​
231[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
232​
233The same options object, typed so that `queryKey` carries the inferred data type.
234​
235### Remarks
236​
237This is the only overload that accepts `queryFn: skipToken`, shown below.
238​
239### See
240​
241 - [injectQuery](injectQuery.md) to run a query with these options.
242 - [The Query Options API](https://tkdodo.eu/blog/the-query-options-api) for more on this pattern.
243​
244### Examples
245​
246A parameterized factory, so the same options object can be reused per `id`:
247```angular-ts
248import { queryOptions, injectQuery } from '@tanstack/angular-query-experimental'
249​
250export const postOptions = (id: string) =>
251 queryOptions({
252 queryKey: ['post', id],
253 queryFn: () => fetchPost(id),
254 })
255​
256@Component({
257 selector: 'post',
258 template: `
259 @if (postQuery.isPending()) {
260 Loading...
261 } @else if (postQuery.isError()) {
262 <span>Error: {{ postQuery.error()?.message }}</span>
263 } @else {
264 <h1>{{ postQuery.data().title }}</h1>
265 }
266 `,
267})
268export class Post {
269 readonly id = signal('1')
270 readonly postQuery = injectQuery(() => postOptions(this.id()))
272```
273​
274A factory that disables the query, type safe, until `postId` is set:
275```angular-ts
276import { queryOptions, skipToken, injectQuery } from '@tanstack/angular-query-experimental'
277​
278export const postOptions = (postId: number | undefined) =>
279 queryOptions({
280 queryKey: ['post', postId],
281 queryFn: postId != null ? () => fetchPost(postId) : skipToken,
282 })
283​
284@Component({
285 selector: 'post',
286 template: `
287 @if (postId() == null) {
288 Select a post
289 } @else if (postQuery.isPending()) {
290 Loading...
291 } @else if (postQuery.isError()) {
292 <span>Error: {{ postQuery.error()?.message }}</span>
293 } @else {
294 <h1>{{ postQuery.data().title }}</h1>
295 }
296 `,
297})
298export class Post {
299 readonly postId = signal<number | undefined>(undefined)
300 readonly postQuery = injectQuery(() => postOptions(this.postId()))
302```
303​
304<a id="parameters-summary"></a>
305​
306## Parameters
307​
308### options
309​
310[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\>
311​
312The [UndefinedInitialDataOptions](../type-aliases/UndefinedInitialDataOptions.md) to use β€” everything you can pass to `injectQuery`.
313​
314<a id="options-properties"></a>
315​
316#### `options` properties
317​
318Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties). See the type above for what it changes.
319​
320<a id="returns-summary"></a>
321​
322## Returns
323​
324[`UndefinedInitialDataOptions`](../type-aliases/UndefinedInitialDataOptions.md)\<`TQueryFnData`, `TError`, `TData`, `TQueryKey`\> & [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md)\<`TQueryKey`, `TQueryFnData`, `TError`\>
325​
326The same options object, typed so that `queryKey` carries the inferred data type.
327​
328<a id="result-properties"></a>
329​
330### Result properties
331​
332Built from [`CreateQueryOptions`](../interfaces/CreateQueryOptions.md#properties), [`QueryKeyWithDataTag`](../type-aliases/QueryKeyWithDataTag.md#properties). See the type above for what it changes.