Open History to see the last commit
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)
249}
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 }
261}
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)
271}
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)
283}
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 }
297}
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)
328}
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 }
340}
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)
350}
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 }
361}
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 }
374}
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)
405}
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 }
418}
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)
428}
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 }
441}
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 }
455}
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```