Defined in: packages/db/src/local-only.ts:24
Configuration interface for Local-only collection options
Extends#
Omit<BaseCollectionConfig<T,TKey,TSchema,LocalOnlyCollectionUtils>,"gcTime"|"startSync">
Type Parameters#
T#
T extends object = object
The type of items in the collection
TSchema#
TSchema extends StandardSchemaV1 = never
The schema type for validation
TKey#
TKey extends string | number = string | number
The type of the key returned by getKey
Properties#
autoIndex?#
optional autoIndex: "off" | "eager";
Defined in: packages/db/src/types.ts:772
Auto-indexing mode for the collection. When enabled, indexes will be automatically created for simple where expressions.
Default#
"off"
Description#
- "off": No automatic indexing (default). Use explicit indexes for better bundle size.
- "eager": Automatically create indexes for simple where expressions in subscribeChanges. Requires setting defaultIndexType.
Inherited from#
BaseCollectionConfig.autoIndex
compare()?#
optional compare: (x, y) => number;
Defined in: packages/db/src/types.ts:797
Optional function to compare two items. This is used to order the items in the collection.
Parameters#
x#
T
The first item to compare
y#
T
The second item to compare
Returns#
number
A number indicating the order of the items
Example#
// For a collection with a 'createdAt' field
compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
Inherited from#
Omit.compare
defaultIndexType?#
optional defaultIndexType: IndexConstructor<TKey>;
Defined in: packages/db/src/types.ts:786
Default index type to use when creating indexes without an explicit type. Required for auto-indexing. Import from '@tanstack/db'.
Example#
import { BasicIndex } from '@tanstack/db'
const collection = createCollection({
defaultIndexType: BasicIndex,
autoIndex: 'eager',
// ...
})
Inherited from#
Omit.defaultIndexType
defaultStringCollation?#
optional defaultStringCollation: StringCollationConfig;
Defined in: packages/db/src/types.ts:992
Specifies how to compare data in the collection. This should be configured to match data ordering on the backend. E.g., when using the Electric DB collection these options should match the database's collation settings.
Inherited from#
Omit.defaultStringCollation
getKey()#
getKey: (item) => TKey;
Defined in: packages/db/src/types.ts:742
Function to extract the ID from an object This is required for update/delete operations which now only accept IDs
Parameters#
item#
T
The item to extract the ID from
Returns#
TKey
The ID string for the item
Example#
// For a collection with a 'uuid' field as the primary key
getKey: (item) => item.uuid
Inherited from#
Omit.getKey
id?#
optional id: string;
Defined in: packages/db/src/types.ts:731
Inherited from#
initialData?#
optional initialData: T[];
Defined in: packages/db/src/local-only.ts:36
Optional initial data to populate the collection with on creation This data will be applied during the initial sync process
onDelete?#
optional onDelete:
| DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
| DeleteMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
Defined in: packages/db/src/types.ts:981
Optional asynchronous handler function called before a delete operation Returning a value is deprecated; coordinate synchronization through collection utilities instead.
Examples#
// Basic delete handler
onDelete: async ({ transaction, collection }) => {
const deletedKey = transaction.mutations[0].key
await api.deleteTodo(deletedKey)
}
// Delete handler with refetch (Query Collection)
onDelete: async ({ transaction, collection }) => {
const keysToDelete = transaction.mutations.map(m => m.key)
await api.deleteTodos(keysToDelete)
// Trigger refetch to sync server state
await collection.utils.refetch()
// Prevent the pre-1.0 compatibility wrapper from refetching again.
return { refetch: false }
}
// Delete handler with sync wait (Electric Collection)
onDelete: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
const result = await api.deleteTodo(mutation.original.id)
// Wait for txid to sync
await collection.utils.awaitTxId(result.txid)
}
// Delete handler with confirmation
onDelete: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
const shouldDelete = await confirmDeletion(mutation.original)
if (!shouldDelete) {
throw new Error('Delete cancelled by user')
}
await api.deleteTodo(mutation.original.id)
}
// Delete handler with optimistic rollback
onDelete: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
try {
await api.deleteTodo(mutation.original.id)
} catch (error) {
// Transaction will automatically rollback optimistic changes
console.error('Delete failed, rolling back:', error)
throw error
}
}
Inherited from#
Omit.onDelete
onInsert?#
optional onInsert:
| InsertMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
| InsertMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
Defined in: packages/db/src/types.ts:860
Optional asynchronous handler function called before an insert operation Returning a value is deprecated; coordinate synchronization through collection utilities instead.
Examples#
// Basic insert handler
onInsert: async ({ transaction, collection }) => {
const newItem = transaction.mutations[0].modified
await api.createTodo(newItem)
}
// Insert handler with refetch (Query Collection)
onInsert: async ({ transaction, collection }) => {
const newItem = transaction.mutations[0].modified
await api.createTodo(newItem)
// Trigger refetch to sync server state
await collection.utils.refetch()
// Prevent the pre-1.0 compatibility wrapper from refetching again.
return { refetch: false }
}
// Insert handler with sync wait (Electric Collection)
onInsert: async ({ transaction, collection }) => {
const newItem = transaction.mutations[0].modified
const result = await api.createTodo(newItem)
// Wait for txid to sync
await collection.utils.awaitTxId(result.txid)
}
// Insert handler with multiple items
onInsert: async ({ transaction, collection }) => {
const items = transaction.mutations.map(m => m.modified)
await api.createTodos(items)
// Refetch to get updated data from server
await collection.utils.refetch()
return { refetch: false }
}
// Insert handler with error handling
onInsert: async ({ transaction, collection }) => {
try {
const newItem = transaction.mutations[0].modified
await api.createTodo(newItem)
} catch (error) {
console.error('Insert failed:', error)
throw error // This will cause the transaction to rollback
}
}
Inherited from#
Omit.onInsert
onUpdate?#
optional onUpdate:
| UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils, void>
| UpdateMutationFn<T, TKey, LocalOnlyCollectionUtils, any>;
Defined in: packages/db/src/types.ts:922
Optional asynchronous handler function called before an update operation Returning a value is deprecated; coordinate synchronization through collection utilities instead.
Examples#
// Basic update handler
onUpdate: async ({ transaction, collection }) => {
const updatedItem = transaction.mutations[0].modified
await api.updateTodo(updatedItem.id, updatedItem)
}
// Update handler with refetch (Query Collection)
onUpdate: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
const changes = mutation.changes // Only the changed fields
await api.updateTodo(mutation.original.id, changes)
// Trigger refetch to sync server state
await collection.utils.refetch()
// Prevent the pre-1.0 compatibility wrapper from refetching again.
return { refetch: false }
}
// Update handler with sync wait (Electric Collection)
onUpdate: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
const result = await api.updateTodo(mutation.original.id, mutation.changes)
// Wait for txid to sync
await collection.utils.awaitTxId(result.txid)
}
// Update handler with multiple items
onUpdate: async ({ transaction, collection }) => {
const updates = transaction.mutations.map(m => ({
id: m.key,
changes: m.changes
}))
await api.updateTodos(updates)
await collection.utils.refetch()
return { refetch: false }
}
// Update handler with optimistic rollback
onUpdate: async ({ transaction, collection }) => {
const mutation = transaction.mutations[0]
try {
await api.updateTodo(mutation.original.id, mutation.changes)
} catch (error) {
// Transaction will automatically rollback optimistic changes
console.error('Update failed, rolling back:', error)
throw error
}
}
Inherited from#
Omit.onUpdate
schema?#
optional schema: TSchema;
Defined in: packages/db/src/types.ts:732
Inherited from#
Omit.schema
syncMode?#
optional syncMode: SyncMode;
Defined in: packages/db/src/types.ts:806
The mode of sync to use for the collection.
Default#
eager
Description#
eager: syncs all data immediately on preloadon-demand: syncs data in incremental snapshots when the collection is queried The exact implementation of the sync mode is up to the sync implementation.
Inherited from#
utils?#
optional utils: LocalOnlyCollectionUtils;
Defined in: packages/db/src/types.ts:994
Inherited from#
Omit.utils