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

LocalOnlyCollectionConfig.md

520 lines11.3 KB

1---
2id: LocalOnlyCollectionConfig
3title: LocalOnlyCollectionConfig
4---
5​
6Defined in: [packages/db/src/local-only.ts:24](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L24)
7​
8Configuration interface for Local-only collection options
9​
10## Extends
11​
12- `Omit`\<[`BaseCollectionConfig`](BaseCollectionConfig.md)\<`T`, `TKey`, `TSchema`, [`LocalOnlyCollectionUtils`](LocalOnlyCollectionUtils.md)\>, `"gcTime"` \| `"startSync"`\>
13​
14## Type Parameters
15​
16### T
17​
18`T` *extends* `object` = `object`
19​
20The type of items in the collection
21​
22### TSchema
23​
24`TSchema` *extends* `StandardSchemaV1` = `never`
25​
26The schema type for validation
27​
28### TKey
29​
30`TKey` *extends* `string` \| `number` = `string` \| `number`
31​
32The type of the key returned by `getKey`
33​
34## Properties
35​
36### autoIndex?
37​
38```ts
39optional autoIndex: "eager" | "off";
40```
41​
42Defined in: [packages/db/src/types.ts:816](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L816)
43​
44Auto-indexing mode for the collection.
45When enabled, indexes will be automatically created for simple where expressions.
46​
47#### Default
48​
49```ts
50"off"
51```
52​
53#### Description
54​
55- "off": No automatic indexing (default). Use explicit indexes for better bundle size.
56- "eager": Automatically create indexes for simple where expressions in subscribeChanges.
57 Requires setting defaultIndexType.
58​
59#### Inherited from
60​
61[`BaseCollectionConfig`](BaseCollectionConfig.md).[`autoIndex`](BaseCollectionConfig.md#autoindex)
62​
63***
64​
65### compare()?
66​
67```ts
68optional compare: (x, y) => number;
69```
70​
71Defined in: [packages/db/src/types.ts:841](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L841)
72​
73Optional function to compare two items.
74This is used to order the items in the collection.
75​
76#### Parameters
77​
78##### x
79​
80`T`
81​
82The first item to compare
83​
84##### y
85​
86`T`
87​
88The second item to compare
89​
90#### Returns
91​
92`number`
93​
94A number indicating the order of the items
95​
96#### Example
97​
98```ts
99// For a collection with a 'createdAt' field
100compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
101```
102​
103#### Inherited from
104​
105```ts
106Omit.compare
107```
108​
109***
110​
111### defaultIndexType?
112​
113```ts
114optional defaultIndexType: IndexConstructor<TKey>;
115```
116​
117Defined in: [packages/db/src/types.ts:830](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L830)
118​
119Default index type to use when creating indexes without an explicit type.
120Required for auto-indexing. Import from '@tanstack/db'.
121​
122#### Example
123​
124```ts
125import { BasicIndex } from '@tanstack/db'
126const collection = createCollection({
127 defaultIndexType: BasicIndex,
128 autoIndex: 'eager',
129 // ...
130})
131```
132​
133#### Inherited from
134​
135```ts
136Omit.defaultIndexType
137```
138​
139***
140​
141### defaultStringCollation?
142​
143```ts
144optional defaultStringCollation: StringCollationConfig;
145```
146​
147Defined in: [packages/db/src/types.ts:1036](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1036)
148​
149Specifies how to compare data in the collection.
150This should be configured to match data ordering on the backend.
151E.g., when using the Electric DB collection these options
152 should match the database's collation settings.
153​
154#### Inherited from
155​
156```ts
157Omit.defaultStringCollation
158```
159​
160***
161​
162### getKey()
163​
164```ts
165getKey: (item) => TKey;
166```
167​
168Defined in: [packages/db/src/types.ts:786](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L786)
169​
170Function to extract the ID from an object
171This is required for update/delete operations which now only accept IDs
172​
173#### Parameters
174​
175##### item
176​
177`T`
178​
179The item to extract the ID from
180​
181#### Returns
182​
183`TKey`
184​
185The ID string for the item
186​
187#### Example
188​
189```ts
190// For a collection with a 'uuid' field as the primary key
191getKey: (item) => item.uuid
192```
193​
194#### Inherited from
195​
196```ts
197Omit.getKey
198```
199​
200***
201​
202### id?
203​
204```ts
205optional id: string;
206```
207​
208Defined in: [packages/db/src/types.ts:775](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L775)
209​
210#### Inherited from
211​
212[`BaseCollectionConfig`](BaseCollectionConfig.md).[`id`](BaseCollectionConfig.md#id)
213​
214***
215​
216### initialData?
217​
218```ts
219optional initialData: T[];
220```
221​
222Defined in: [packages/db/src/local-only.ts:36](https://github.com/TanStack/db/blob/main/packages/db/src/local-only.ts#L36)
223​
224Optional initial data to populate the collection with on creation
225This data will be applied during the initial sync process
226​
227***
228​
229### onDelete?
230​
231```ts
232optional onDelete:
233 | DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
234| DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
235```
236​
237Defined in: [packages/db/src/types.ts:1025](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1025)
238​
239Optional asynchronous handler function called before a delete operation
240Returning a value is deprecated; coordinate synchronization through collection utilities instead.
241​
242#### Examples
243​
244```ts
245// Basic delete handler
246onDelete: async ({ transaction, collection }) => {
247 const deletedKey = transaction.mutations[0].key
248 await api.deleteTodo(deletedKey)
250```
251​
252```ts
253// Delete handler with refetch (Query Collection)
254onDelete: async ({ transaction, collection }) => {
255 const keysToDelete = transaction.mutations.map(m => m.key)
256 await api.deleteTodos(keysToDelete)
257 // Trigger refetch to sync server state
258 await collection.utils.refetch()
259 // Prevent the pre-1.0 compatibility wrapper from refetching again.
260 return { refetch: false }
262```
263​
264```ts
265// Delete handler with sync wait (Electric Collection)
266onDelete: async ({ transaction, collection }) => {
267 const mutation = transaction.mutations[0]
268 const result = await api.deleteTodo(mutation.original.id)
269 // Wait for txid to sync
270 await collection.utils.awaitTxId(result.txid)
272```
273​
274```ts
275// Delete handler with confirmation
276onDelete: async ({ transaction, collection }) => {
277 const mutation = transaction.mutations[0]
278 const shouldDelete = await confirmDeletion(mutation.original)
279 if (!shouldDelete) {
280 throw new Error('Delete cancelled by user')
281 }
282 await api.deleteTodo(mutation.original.id)
284```
285​
286```ts
287// Delete handler with optimistic rollback
288onDelete: async ({ transaction, collection }) => {
289 const mutation = transaction.mutations[0]
290 try {
291 await api.deleteTodo(mutation.original.id)
292 } catch (error) {
293 // Transaction will automatically rollback optimistic changes
294 console.error('Delete failed, rolling back:', error)
295 throw error
296 }
298```
299​
300#### Inherited from
301​
302```ts
303Omit.onDelete
304```
305​
306***
307​
308### onInsert?
309​
310```ts
311optional onInsert:
312 | InsertMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
313| InsertMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
314```
315​
316Defined in: [packages/db/src/types.ts:904](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L904)
317​
318Optional asynchronous handler function called before an insert operation
319Returning a value is deprecated; coordinate synchronization through collection utilities instead.
320​
321#### Examples
322​
323```ts
324// Basic insert handler
325onInsert: async ({ transaction, collection }) => {
326 const newItem = transaction.mutations[0].modified
327 await api.createTodo(newItem)
329```
330​
331```ts
332// Insert handler with refetch (Query Collection)
333onInsert: async ({ transaction, collection }) => {
334 const newItem = transaction.mutations[0].modified
335 await api.createTodo(newItem)
336 // Trigger refetch to sync server state
337 await collection.utils.refetch()
338 // Prevent the pre-1.0 compatibility wrapper from refetching again.
339 return { refetch: false }
341```
342​
343```ts
344// Insert handler with sync wait (Electric Collection)
345onInsert: async ({ transaction, collection }) => {
346 const newItem = transaction.mutations[0].modified
347 const result = await api.createTodo(newItem)
348 // Wait for txid to sync
349 await collection.utils.awaitTxId(result.txid)
351```
352​
353```ts
354// Insert handler with multiple items
355onInsert: async ({ transaction, collection }) => {
356 const items = transaction.mutations.map(m => m.modified)
357 await api.createTodos(items)
358 // Refetch to get updated data from server
359 await collection.utils.refetch()
360 return { refetch: false }
362```
363​
364```ts
365// Insert handler with error handling
366onInsert: async ({ transaction, collection }) => {
367 try {
368 const newItem = transaction.mutations[0].modified
369 await api.createTodo(newItem)
370 } catch (error) {
371 console.error('Insert failed:', error)
372 throw error // This will cause the transaction to rollback
373 }
375```
376​
377#### Inherited from
378​
379```ts
380Omit.onInsert
381```
382​
383***
384​
385### onUpdate?
386​
387```ts
388optional onUpdate:
389 | UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
390| UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
391```
392​
393Defined in: [packages/db/src/types.ts:966](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L966)
394​
395Optional asynchronous handler function called before an update operation
396Returning a value is deprecated; coordinate synchronization through collection utilities instead.
397​
398#### Examples
399​
400```ts
401// Basic update handler
402onUpdate: async ({ transaction, collection }) => {
403 const updatedItem = transaction.mutations[0].modified
404 await api.updateTodo(updatedItem.id, updatedItem)
406```
407​
408```ts
409// Update handler with refetch (Query Collection)
410onUpdate: async ({ transaction, collection }) => {
411 const mutation = transaction.mutations[0]
412 const changes = mutation.changes // Only the changed fields
413 await api.updateTodo(mutation.original.id, changes)
414 // Trigger refetch to sync server state
415 await collection.utils.refetch()
416 // Prevent the pre-1.0 compatibility wrapper from refetching again.
417 return { refetch: false }
419```
420​
421```ts
422// Update handler with sync wait (Electric Collection)
423onUpdate: async ({ transaction, collection }) => {
424 const mutation = transaction.mutations[0]
425 const result = await api.updateTodo(mutation.original.id, mutation.changes)
426 // Wait for txid to sync
427 await collection.utils.awaitTxId(result.txid)
429```
430​
431```ts
432// Update handler with multiple items
433onUpdate: async ({ transaction, collection }) => {
434 const updates = transaction.mutations.map(m => ({
435 id: m.key,
436 changes: m.changes
437 }))
438 await api.updateTodos(updates)
439 await collection.utils.refetch()
440 return { refetch: false }
442```
443​
444```ts
445// Update handler with optimistic rollback
446onUpdate: async ({ transaction, collection }) => {
447 const mutation = transaction.mutations[0]
448 try {
449 await api.updateTodo(mutation.original.id, mutation.changes)
450 } catch (error) {
451 // Transaction will automatically rollback optimistic changes
452 console.error('Update failed, rolling back:', error)
453 throw error
454 }
456```
457​
458#### Inherited from
459​
460```ts
461Omit.onUpdate
462```
463​
464***
465​
466### schema?
467​
468```ts
469optional schema: TSchema;
470```
471​
472Defined in: [packages/db/src/types.ts:776](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L776)
473​
474#### Inherited from
475​
476```ts
477Omit.schema
478```
479​
480***
481​
482### syncMode?
483​
484```ts
485optional syncMode: SyncMode;
486```
487​
488Defined in: [packages/db/src/types.ts:850](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L850)
489​
490The mode of sync to use for the collection.
491​
492#### Default
493​
494`eager`
495​
496#### Description
497​
498- `eager`: syncs all data immediately on preload
499- `on-demand`: syncs data in incremental snapshots when the collection is queried
500The exact implementation of the sync mode is up to the sync implementation.
501​
502#### Inherited from
503​
504[`BaseCollectionConfig`](BaseCollectionConfig.md).[`syncMode`](BaseCollectionConfig.md#syncmode)
505​
506***
507​
508### utils?
509​
510```ts
511optional utils: LocalOnlyCollectionUtils;
512```
513​
514Defined in: [packages/db/src/types.ts:1038](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L1038)
515​
516#### Inherited from
517​
518```ts
519Omit.utils
520```