LocalOnlyCollectionConfig | TanStack DB Русский

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: "eager" | "off";

Defined in: packages/db/src/types.ts:773

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:798

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:787

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:993

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:743

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:732

Inherited from

BaseCollectionConfig.id

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:982

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:861

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:923

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:733

Inherited from

Omit.schema

syncMode?

optional syncMode: SyncMode;

Defined in: packages/db/src/types.ts:807

The mode of sync to use for the collection.

Default

eager

Description

eager: syncs all data immediately on preload
on-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

BaseCollectionConfig.syncMode

utils?

optional utils: LocalOnlyCollectionUtils;

Defined in: packages/db/src/types.ts:995

Inherited from

Omit.utils