TanStackDB v0
Auto
Framework
Version
Menu
Getting Started
Guides
API Reference

QueryCollectionConfig

Interface: QueryCollectionConfig<TItem, TError, TQueryKey>

Defined in: packages/query-db-collection/src/query.ts:26

Type Parameters

• TItem extends object

• TError = unknown

• TQueryKey extends QueryKey = QueryKey

Properties

enabled?
ts
optional enabled: boolean;

optional enabled: boolean;

Defined in: packages/query-db-collection/src/query.ts:36

getKey()
ts
getKey: (item) => string | number;

getKey: (item) => string | number;

Defined in: packages/query-db-collection/src/query.ts:68

Parameters
item

TItem

Returns

string | number

id?
ts
optional id: string;

optional id: string;

Defined in: packages/query-db-collection/src/query.ts:67

onDelete?
ts
optional onDelete: DeleteMutationFn<TItem>;

optional onDelete: DeleteMutationFn<TItem>;

Defined in: packages/query-db-collection/src/query.ts:213

Optional asynchronous handler function called before a delete operation

Param

Object containing transaction and collection information

Returns

Promise resolving to void or { refetch?: boolean } to control refetching

Examples
ts
// Basic query collection delete handler
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)
  // Automatically refetches query after delete
}

// Basic query collection delete handler
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)
  // Automatically refetches query after delete
}
ts
// Delete handler with refetch control
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)
  return { refetch: false } // Skip automatic refetch
}

// Delete handler with refetch control
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)
  return { refetch: false } // Skip automatic refetch
}
ts
// Delete handler with multiple items
onDelete: async ({ transaction }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
  // Will refetch query to get updated data
}

// Delete handler with multiple items
onDelete: async ({ transaction }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
  // Will refetch query to get updated data
}
ts
// Delete handler with related collection refetch
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)

  // Refetch related collections when this item is deleted
  await Promise.all([
    collection.utils.refetch(), // Refetch this collection
    usersCollection.utils.refetch(), // Refetch users
    projectsCollection.utils.refetch() // Refetch projects
  ])

  return { refetch: false } // Skip automatic refetch since we handled it manually
}

// Delete handler with related collection refetch
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.deleteTodo(mutation.original.id)

  // Refetch related collections when this item is deleted
  await Promise.all([
    collection.utils.refetch(), // Refetch this collection
    usersCollection.utils.refetch(), // Refetch users
    projectsCollection.utils.refetch() // Refetch projects
  ])

  return { refetch: false } // Skip automatic refetch since we handled it manually
}

onInsert?
ts
optional onInsert: InsertMutationFn<TItem>;

optional onInsert: InsertMutationFn<TItem>;

Defined in: packages/query-db-collection/src/query.ts:114

Optional asynchronous handler function called before an insert operation

Param

Object containing transaction and collection information

Returns

Promise resolving to void or { refetch?: boolean } to control refetching

Examples
ts
// Basic query collection insert handler
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
  // Automatically refetches query after insert
}

// Basic query collection insert handler
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
  // Automatically refetches query after insert
}
ts
// Insert handler with refetch control
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
  return { refetch: false } // Skip automatic refetch
}

// Insert handler with refetch control
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
  return { refetch: false } // Skip automatic refetch
}
ts
// Insert handler with multiple items
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
  // Will refetch query to get updated data
}

// Insert handler with multiple items
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
  // Will refetch query to get updated data
}
ts
// Insert handler with error handling
onInsert: async ({ transaction }) => {
  try {
    const newItem = transaction.mutations[0].modified
    await api.createTodo(newItem)
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // Transaction will rollback optimistic changes
  }
}

// Insert handler with error handling
onInsert: async ({ transaction }) => {
  try {
    const newItem = transaction.mutations[0].modified
    await api.createTodo(newItem)
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // Transaction will rollback optimistic changes
  }
}

onUpdate?
ts
optional onUpdate: UpdateMutationFn<TItem>;

optional onUpdate: UpdateMutationFn<TItem>;

Defined in: packages/query-db-collection/src/query.ts:167

Optional asynchronous handler function called before an update operation

Param

Object containing transaction and collection information

Returns

Promise resolving to void or { refetch?: boolean } to control refetching

Examples
ts
// Basic query collection update handler
onUpdate: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)
  // Automatically refetches query after update
}

// Basic query collection update handler
onUpdate: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)
  // Automatically refetches query after update
}
ts
// Update handler with multiple items
onUpdate: async ({ transaction }) => {
  const updates = transaction.mutations.map(m => ({
    id: m.key,
    changes: m.changes
  }))
  await api.updateTodos(updates)
  // Will refetch query to get updated data
}

// Update handler with multiple items
onUpdate: async ({ transaction }) => {
  const updates = transaction.mutations.map(m => ({
    id: m.key,
    changes: m.changes
  }))
  await api.updateTodos(updates)
  // Will refetch query to get updated data
}
ts
// Update handler with manual refetch
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)

  // Manually trigger refetch
  await collection.utils.refetch()

  return { refetch: false } // Skip automatic refetch
}

// Update handler with manual refetch
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)

  // Manually trigger refetch
  await collection.utils.refetch()

  return { refetch: false } // Skip automatic refetch
}
ts
// Update handler with related collection refetch
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)

  // Refetch related collections when this item changes
  await Promise.all([
    collection.utils.refetch(), // Refetch this collection
    usersCollection.utils.refetch(), // Refetch users
    tagsCollection.utils.refetch() // Refetch tags
  ])

  return { refetch: false } // Skip automatic refetch since we handled it manually
}

// Update handler with related collection refetch
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.updateTodo(mutation.original.id, mutation.changes)

  // Refetch related collections when this item changes
  await Promise.all([
    collection.utils.refetch(), // Refetch this collection
    usersCollection.utils.refetch(), // Refetch users
    tagsCollection.utils.refetch() // Refetch tags
  ])

  return { refetch: false } // Skip automatic refetch since we handled it manually
}

queryClient
ts
queryClient: QueryClient;

queryClient: QueryClient;

Defined in: packages/query-db-collection/src/query.ts:33

queryFn()
ts
queryFn: (context) => Promise<TItem[]>;

queryFn: (context) => Promise<TItem[]>;

Defined in: packages/query-db-collection/src/query.ts:32

Parameters
context
client

QueryClient

direction?

unknown

Deprecated

if you want access to the direction, you can add it to the pageParam

meta

undefined | Record<string, unknown>

pageParam?

unknown

queryKey

TQueryKey

signal

AbortSignal

Returns

Promise<TItem[]>

queryKey
ts
queryKey: TQueryKey;

queryKey: TQueryKey;

Defined in: packages/query-db-collection/src/query.ts:31

refetchInterval?
ts
optional refetchInterval: number | false | (query) => undefined | number | false;

optional refetchInterval: number | false | (query) => undefined | number | false;

Defined in: packages/query-db-collection/src/query.ts:37

retry?
ts
optional retry: RetryValue<TError>;

optional retry: RetryValue<TError>;

Defined in: packages/query-db-collection/src/query.ts:44

retryDelay?
ts
optional retryDelay: RetryDelayValue<TError>;

optional retryDelay: RetryDelayValue<TError>;

Defined in: packages/query-db-collection/src/query.ts:51

schema?
ts
optional schema: StandardSchemaV1<unknown, unknown>;

optional schema: StandardSchemaV1<unknown, unknown>;

Defined in: packages/query-db-collection/src/query.ts:69

staleTime?
ts
optional staleTime: StaleTime<TItem[], TError, TItem[], TQueryKey>;

optional staleTime: StaleTime<TItem[], TError, TItem[], TQueryKey>;

Defined in: packages/query-db-collection/src/query.ts:58

startSync?
ts
optional startSync: boolean;

optional startSync: boolean;

Defined in: packages/query-db-collection/src/query.ts:71

sync?
ts
optional sync: SyncConfig<TItem, string | number>;

optional sync: SyncConfig<TItem, string | number>;

Defined in: packages/query-db-collection/src/query.ts:70

Edit on GitHub
Home
Our Partners
Electric
Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.

Subscribe to Bytes

Your weekly dose of JavaScript news. Delivered every Monday to over 100,000 devs, for free.

Bytes

No spam. Unsubscribe at any time.