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