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

LocalOnlyCollectionConfig.md

494 lines9.7 KB

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)
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)
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)
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 }
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)
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)
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 }
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 })
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)
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)
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)
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 }
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```