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

LocalOnlyCollectionConfig.md

492 lines9.6 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: "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)
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)
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)
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 }
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)
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)
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 }
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 })
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)
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)
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)
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 }
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```