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

queryCollectionOptions.md

550 lines14.4 KB

1---
2id: queryCollectionOptions
3title: queryCollectionOptions
4---
5​
6# Function: queryCollectionOptions()
7​
8## Call Signature
9​
10```ts
11function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
12```
13​
14Defined in: [packages/query-db-collection/src/query.ts:535](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L535)
15​
16Creates query collection options for use with a standard Collection.
17This integrates TanStack Query with TanStack DB for automatic synchronization.
18​
19Supports automatic type inference following the priority order:
201. Schema inference (highest priority)
212. QueryFn return type inference (second priority)
22​
23### Type Parameters
24​
25#### T
26​
27`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
28​
29Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
30​
31#### TQueryFn
32​
33`TQueryFn` *extends* (`context`) => `any`
34​
35#### TError
36​
37`TError` = `unknown`
38​
39The type of errors that can occur during queries
40​
41#### TQueryKey
42​
43`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
44​
45The type of the query key
46​
47#### TKey
48​
49`TKey` *extends* `string` \| `number` = `string` \| `number`
50​
51The type of the item keys
52​
53#### TQueryData
54​
55`TQueryData` = `Awaited`\<`ReturnType`\<`TQueryFn`\>\>
56​
57### Parameters
58​
59#### config
60​
61[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`InferSchemaOutput`\<`T`\>, `TQueryFn`, `TError`, `TQueryKey`, `TKey`, `T`, `Awaited`\<`ReturnType`\<`TQueryFn`\>\>\> & `object`
62​
63Configuration options for the Query collection
64​
65### Returns
66​
67`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
68​
69Collection options with utilities for direct writes and manual operations
70​
71### Examples
72​
73```ts
74// Type inferred from queryFn return type (NEW!)
75const todosCollection = createCollection(
76 queryCollectionOptions({
77 queryKey: ['todos'],
78 queryFn: async () => {
79 const response = await fetch('/api/todos')
80 return response.json() as Todo[] // Type automatically inferred!
81 },
82 queryClient,
83 getKey: (item) => item.id, // item is typed as Todo
84 })
86```
87​
88```ts
89// Explicit type
90const todosCollection = createCollection<Todo>(
91 queryCollectionOptions({
92 queryKey: ['todos'],
93 queryFn: async () => fetch('/api/todos').then(r => r.json()),
94 queryClient,
95 getKey: (item) => item.id,
96 })
98```
99​
100```ts
101// Schema inference
102const todosCollection = createCollection(
103 queryCollectionOptions({
104 queryKey: ['todos'],
105 queryFn: async () => fetch('/api/todos').then(r => r.json()),
106 queryClient,
107 schema: todoSchema, // Type inferred from schema
108 getKey: (item) => item.id,
109 })
111```
112​
113```ts
114// With persistence handlers
115const todosCollection = createCollection(
116 queryCollectionOptions({
117 queryKey: ['todos'],
118 queryFn: fetchTodos,
119 queryClient,
120 getKey: (item) => item.id,
121 onInsert: async ({ transaction }) => {
122 await api.createTodos(transaction.mutations.map(m => m.modified))
123 },
124 onUpdate: async ({ transaction }) => {
125 await api.updateTodos(transaction.mutations)
126 },
127 onDelete: async ({ transaction }) => {
128 await api.deleteTodos(transaction.mutations.map(m => m.key))
129 }
130 })
132```
133​
134```ts
135// The select option extracts the items array from a response with metadata
136const todosCollection = createCollection(
137 queryCollectionOptions({
138 queryKey: ['todos'],
139 queryFn: async () => fetch('/api/todos').then(r => r.json()),
140 select: (data) => data.items, // Extract the array of items
141 queryClient,
142 schema: todoSchema,
143 getKey: (item) => item.id,
144 })
146```
147​
148## Call Signature
149​
150```ts
151function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
152```
153​
154Defined in: [packages/query-db-collection/src/query.ts:570](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L570)
155​
156Creates query collection options for use with a standard Collection.
157This integrates TanStack Query with TanStack DB for automatic synchronization.
158​
159Supports automatic type inference following the priority order:
1601. Schema inference (highest priority)
1612. QueryFn return type inference (second priority)
162​
163### Type Parameters
164​
165#### T
166​
167`T` *extends* `object`
168​
169Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
170​
171#### TQueryFn
172​
173`TQueryFn` *extends* (`context`) => `any` = (`context`) => `any`
174​
175#### TError
176​
177`TError` = `unknown`
178​
179The type of errors that can occur during queries
180​
181#### TQueryKey
182​
183`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
184​
185The type of the query key
186​
187#### TKey
188​
189`TKey` *extends* `string` \| `number` = `string` \| `number`
190​
191The type of the item keys
192​
193#### TQueryData
194​
195`TQueryData` = `Awaited`\<`ReturnType`\<`TQueryFn`\>\>
196​
197### Parameters
198​
199#### config
200​
201[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`T`, `TQueryFn`, `TError`, `TQueryKey`, `TKey`, `never`, `TQueryData`\> & `object`
202​
203Configuration options for the Query collection
204​
205### Returns
206​
207`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
208​
209Collection options with utilities for direct writes and manual operations
210​
211### Examples
212​
213```ts
214// Type inferred from queryFn return type (NEW!)
215const todosCollection = createCollection(
216 queryCollectionOptions({
217 queryKey: ['todos'],
218 queryFn: async () => {
219 const response = await fetch('/api/todos')
220 return response.json() as Todo[] // Type automatically inferred!
221 },
222 queryClient,
223 getKey: (item) => item.id, // item is typed as Todo
224 })
226```
227​
228```ts
229// Explicit type
230const todosCollection = createCollection<Todo>(
231 queryCollectionOptions({
232 queryKey: ['todos'],
233 queryFn: async () => fetch('/api/todos').then(r => r.json()),
234 queryClient,
235 getKey: (item) => item.id,
236 })
238```
239​
240```ts
241// Schema inference
242const todosCollection = createCollection(
243 queryCollectionOptions({
244 queryKey: ['todos'],
245 queryFn: async () => fetch('/api/todos').then(r => r.json()),
246 queryClient,
247 schema: todoSchema, // Type inferred from schema
248 getKey: (item) => item.id,
249 })
251```
252​
253```ts
254// With persistence handlers
255const todosCollection = createCollection(
256 queryCollectionOptions({
257 queryKey: ['todos'],
258 queryFn: fetchTodos,
259 queryClient,
260 getKey: (item) => item.id,
261 onInsert: async ({ transaction }) => {
262 await api.createTodos(transaction.mutations.map(m => m.modified))
263 },
264 onUpdate: async ({ transaction }) => {
265 await api.updateTodos(transaction.mutations)
266 },
267 onDelete: async ({ transaction }) => {
268 await api.deleteTodos(transaction.mutations.map(m => m.key))
269 }
270 })
272```
273​
274```ts
275// The select option extracts the items array from a response with metadata
276const todosCollection = createCollection(
277 queryCollectionOptions({
278 queryKey: ['todos'],
279 queryFn: async () => fetch('/api/todos').then(r => r.json()),
280 select: (data) => data.items, // Extract the array of items
281 queryClient,
282 schema: todoSchema,
283 getKey: (item) => item.id,
284 })
286```
287​
288## Call Signature
289​
290```ts
291function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;
292```
293​
294Defined in: [packages/query-db-collection/src/query.ts:603](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L603)
295​
296Creates query collection options for use with a standard Collection.
297This integrates TanStack Query with TanStack DB for automatic synchronization.
298​
299Supports automatic type inference following the priority order:
3001. Schema inference (highest priority)
3012. QueryFn return type inference (second priority)
302​
303### Type Parameters
304​
305#### T
306​
307`T` *extends* `StandardSchemaV1`\<`unknown`, `unknown`\>
308​
309Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
310​
311#### TError
312​
313`TError` = `unknown`
314​
315The type of errors that can occur during queries
316​
317#### TQueryKey
318​
319`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
320​
321The type of the query key
322​
323#### TKey
324​
325`TKey` *extends* `string` \| `number` = `string` \| `number`
326​
327The type of the item keys
328​
329### Parameters
330​
331#### config
332​
333[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`InferSchemaOutput`\<`T`\>, (`context`) => `InferSchemaOutput`\<`T`\>[] \| `Promise`\<`InferSchemaOutput`\<`T`\>[]\>, `TError`, `TQueryKey`, `TKey`, `T`, `InferSchemaOutput`\<`T`\>[]\> & `object`
334​
335Configuration options for the Query collection
336​
337### Returns
338​
339`CollectionConfig`\<`InferSchemaOutput`\<`T`\>, `TKey`, `T`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`InferSchemaOutput`\<`T`\>, `TKey`, `InferSchemaInput`\<`T`\>, `TError`\>\> & `object`
340​
341Collection options with utilities for direct writes and manual operations
342​
343### Examples
344​
345```ts
346// Type inferred from queryFn return type (NEW!)
347const todosCollection = createCollection(
348 queryCollectionOptions({
349 queryKey: ['todos'],
350 queryFn: async () => {
351 const response = await fetch('/api/todos')
352 return response.json() as Todo[] // Type automatically inferred!
353 },
354 queryClient,
355 getKey: (item) => item.id, // item is typed as Todo
356 })
358```
359​
360```ts
361// Explicit type
362const todosCollection = createCollection<Todo>(
363 queryCollectionOptions({
364 queryKey: ['todos'],
365 queryFn: async () => fetch('/api/todos').then(r => r.json()),
366 queryClient,
367 getKey: (item) => item.id,
368 })
370```
371​
372```ts
373// Schema inference
374const todosCollection = createCollection(
375 queryCollectionOptions({
376 queryKey: ['todos'],
377 queryFn: async () => fetch('/api/todos').then(r => r.json()),
378 queryClient,
379 schema: todoSchema, // Type inferred from schema
380 getKey: (item) => item.id,
381 })
383```
384​
385```ts
386// With persistence handlers
387const todosCollection = createCollection(
388 queryCollectionOptions({
389 queryKey: ['todos'],
390 queryFn: fetchTodos,
391 queryClient,
392 getKey: (item) => item.id,
393 onInsert: async ({ transaction }) => {
394 await api.createTodos(transaction.mutations.map(m => m.modified))
395 },
396 onUpdate: async ({ transaction }) => {
397 await api.updateTodos(transaction.mutations)
398 },
399 onDelete: async ({ transaction }) => {
400 await api.deleteTodos(transaction.mutations.map(m => m.key))
401 }
402 })
404```
405​
406```ts
407// The select option extracts the items array from a response with metadata
408const todosCollection = createCollection(
409 queryCollectionOptions({
410 queryKey: ['todos'],
411 queryFn: async () => fetch('/api/todos').then(r => r.json()),
412 select: (data) => data.items, // Extract the array of items
413 queryClient,
414 schema: todoSchema,
415 getKey: (item) => item.id,
416 })
418```
419​
420## Call Signature
421​
422```ts
423function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;
424```
425​
426Defined in: [packages/query-db-collection/src/query.ts:637](https://github.com/TanStack/db/blob/main/packages/query-db-collection/src/query.ts#L637)
427​
428Creates query collection options for use with a standard Collection.
429This integrates TanStack Query with TanStack DB for automatic synchronization.
430​
431Supports automatic type inference following the priority order:
4321. Schema inference (highest priority)
4332. QueryFn return type inference (second priority)
434​
435### Type Parameters
436​
437#### T
438​
439`T` *extends* `object`
440​
441Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn
442​
443#### TError
444​
445`TError` = `unknown`
446​
447The type of errors that can occur during queries
448​
449#### TQueryKey
450​
451`TQueryKey` *extends* readonly `unknown`[] = readonly `unknown`[]
452​
453The type of the query key
454​
455#### TKey
456​
457`TKey` *extends* `string` \| `number` = `string` \| `number`
458​
459The type of the item keys
460​
461### Parameters
462​
463#### config
464​
465[`QueryCollectionConfig`](../interfaces/QueryCollectionConfig.md)\<`T`, (`context`) => `T`[] \| `Promise`\<`T`[]\>, `TError`, `TQueryKey`, `TKey`, `never`, `T`[]\> & `object`
466​
467Configuration options for the Query collection
468​
469### Returns
470​
471`CollectionConfig`\<`T`, `TKey`, `never`, [`QueryCollectionUtils`](../interfaces/QueryCollectionUtils.md)\<`T`, `TKey`, `T`, `TError`\>\> & `object`
472​
473Collection options with utilities for direct writes and manual operations
474​
475### Examples
476​
477```ts
478// Type inferred from queryFn return type (NEW!)
479const todosCollection = createCollection(
480 queryCollectionOptions({
481 queryKey: ['todos'],
482 queryFn: async () => {
483 const response = await fetch('/api/todos')
484 return response.json() as Todo[] // Type automatically inferred!
485 },
486 queryClient,
487 getKey: (item) => item.id, // item is typed as Todo
488 })
490```
491​
492```ts
493// Explicit type
494const todosCollection = createCollection<Todo>(
495 queryCollectionOptions({
496 queryKey: ['todos'],
497 queryFn: async () => fetch('/api/todos').then(r => r.json()),
498 queryClient,
499 getKey: (item) => item.id,
500 })
502```
503​
504```ts
505// Schema inference
506const todosCollection = createCollection(
507 queryCollectionOptions({
508 queryKey: ['todos'],
509 queryFn: async () => fetch('/api/todos').then(r => r.json()),
510 queryClient,
511 schema: todoSchema, // Type inferred from schema
512 getKey: (item) => item.id,
513 })
515```
516​
517```ts
518// With persistence handlers
519const todosCollection = createCollection(
520 queryCollectionOptions({
521 queryKey: ['todos'],
522 queryFn: fetchTodos,
523 queryClient,
524 getKey: (item) => item.id,
525 onInsert: async ({ transaction }) => {
526 await api.createTodos(transaction.mutations.map(m => m.modified))
527 },
528 onUpdate: async ({ transaction }) => {
529 await api.updateTodos(transaction.mutations)
530 },
531 onDelete: async ({ transaction }) => {
532 await api.deleteTodos(transaction.mutations.map(m => m.key))
533 }
534 })
536```
537​
538```ts
539// The select option extracts the items array from a response with metadata
540const todosCollection = createCollection(
541 queryCollectionOptions({
542 queryKey: ['todos'],
543 queryFn: async () => fetch('/api/todos').then(r => r.json()),
544 select: (data) => data.items, // Extract the array of items
545 queryClient,
546 schema: todoSchema,
547 getKey: (item) => item.id,
548 })
550```