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: "off" | "eager";
40```
41
42Defined in: [packages/db/src/types.ts:667](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L667)
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:692](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L692)
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:681](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L681)
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:838](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L838)
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:637](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L637)
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:626](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L626)
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: DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
233```
234
235Defined in: [packages/db/src/types.ts:830](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L830)
236
237Optional asynchronous handler function called before a delete operation
238
239#### Param
240
241Object containing transaction and collection information
242
243#### Returns
244
245Promise resolving to any value
246
247#### Examples
248
249```ts
250// Basic delete handler
251onDelete: async ({ transaction, collection }) => {
252 const deletedKey = transaction.mutations[0].key
253 await api.deleteTodo(deletedKey)
254}
255```
256
257```ts
258// Delete handler with multiple items
259onDelete: async ({ transaction, collection }) => {
260 const keysToDelete = transaction.mutations.map(m => m.key)
261 await api.deleteTodos(keysToDelete)
262}
263```
264
265```ts
266// Delete handler with confirmation
267onDelete: async ({ transaction, collection }) => {
268 const mutation = transaction.mutations[0]
269 const shouldDelete = await confirmDeletion(mutation.original)
270 if (!shouldDelete) {
271 throw new Error('Delete cancelled by user')
272 }
273 await api.deleteTodo(mutation.original.id)
274}
275```
276
277```ts
278// Delete handler with optimistic rollback
279onDelete: async ({ transaction, collection }) => {
280 const mutation = transaction.mutations[0]
281 try {
282 await api.deleteTodo(mutation.original.id)
283 } catch (error) {
284 // Transaction will automatically rollback optimistic changes
285 console.error('Delete failed, rolling back:', error)
286 throw error
287 }
288}
289```
290
291#### Inherited from
292
293```ts
294Omit.onDelete
295```
296
297***
298
299### onInsert?
300
301```ts
302optional onInsert: InsertMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
303```
304
305Defined in: [packages/db/src/types.ts:743](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L743)
306
307Optional asynchronous handler function called before an insert operation
308
309#### Param
310
311Object containing transaction and collection information
312
313#### Returns
314
315Promise resolving to any value
316
317#### Examples
318
319```ts
320// Basic insert handler
321onInsert: async ({ transaction, collection }) => {
322 const newItem = transaction.mutations[0].modified
323 await api.createTodo(newItem)
324}
325```
326
327```ts
328// Insert handler with multiple items
329onInsert: async ({ transaction, collection }) => {
330 const items = transaction.mutations.map(m => m.modified)
331 await api.createTodos(items)
332}
333```
334
335```ts
336// Insert handler with error handling
337onInsert: async ({ transaction, collection }) => {
338 try {
339 const newItem = transaction.mutations[0].modified
340 const result = await api.createTodo(newItem)
341 return result
342 } catch (error) {
343 console.error('Insert failed:', error)
344 throw error // This will cause the transaction to fail
345 }
346}
347```
348
349```ts
350// Insert handler with metadata
351onInsert: async ({ transaction, collection }) => {
352 const mutation = transaction.mutations[0]
353 await api.createTodo(mutation.modified, {
354 source: mutation.metadata?.source,
355 timestamp: mutation.createdAt
356 })
357}
358```
359
360#### Inherited from
361
362```ts
363Omit.onInsert
364```
365
366***
367
368### onUpdate?
369
370```ts
371optional onUpdate: UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
372```
373
374Defined in: [packages/db/src/types.ts:787](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L787)
375
376Optional asynchronous handler function called before an update operation
377
378#### Param
379
380Object containing transaction and collection information
381
382#### Returns
383
384Promise resolving to any value
385
386#### Examples
387
388```ts
389// Basic update handler
390onUpdate: async ({ transaction, collection }) => {
391 const updatedItem = transaction.mutations[0].modified
392 await api.updateTodo(updatedItem.id, updatedItem)
393}
394```
395
396```ts
397// Update handler with partial updates
398onUpdate: async ({ transaction, collection }) => {
399 const mutation = transaction.mutations[0]
400 const changes = mutation.changes // Only the changed fields
401 await api.updateTodo(mutation.original.id, changes)
402}
403```
404
405```ts
406// Update handler with multiple items
407onUpdate: async ({ transaction, collection }) => {
408 const updates = transaction.mutations.map(m => ({
409 id: m.key,
410 changes: m.changes
411 }))
412 await api.updateTodos(updates)
413}
414```
415
416```ts
417// Update handler with optimistic rollback
418onUpdate: async ({ transaction, collection }) => {
419 const mutation = transaction.mutations[0]
420 try {
421 await api.updateTodo(mutation.original.id, mutation.changes)
422 } catch (error) {
423 // Transaction will automatically rollback optimistic changes
424 console.error('Update failed, rolling back:', error)
425 throw error
426 }
427}
428```
429
430#### Inherited from
431
432```ts
433Omit.onUpdate
434```
435
436***
437
438### schema?
439
440```ts
441optional schema: TSchema;
442```
443
444Defined in: [packages/db/src/types.ts:627](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L627)
445
446#### Inherited from
447
448```ts
449Omit.schema
450```
451
452***
453
454### syncMode?
455
456```ts
457optional syncMode: SyncMode;
458```
459
460Defined in: [packages/db/src/types.ts:701](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L701)
461
462The mode of sync to use for the collection.
463
464#### Default
465
466`eager`
467
468#### Description
469
470- `eager`: syncs all data immediately on preload
471- `on-demand`: syncs data in incremental snapshots when the collection is queried
472The exact implementation of the sync mode is up to the sync implementation.
473
474#### Inherited from
475
476[`BaseCollectionConfig`](BaseCollectionConfig.md).[`syncMode`](BaseCollectionConfig.md#syncmode)
477
478***
479
480### utils?
481
482```ts
483optional utils: LocalOnlyCollectionUtils;
484```
485
486Defined in: [packages/db/src/types.ts:840](https://github.com/TanStack/db/blob/main/packages/db/src/types.ts#L840)
487
488#### Inherited from
489
490```ts
491Omit.utils
492```