TanStack
DB v0v0
Documentation
Framework
Version
Menu
Getting Started
Guides
Collections
Community
API Reference

queryCollectionOptions

Function: queryCollectionOptions()

Call Signature
ts
function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;

function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;

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

Creates query collection options for use with a standard Collection. This integrates TanStack Query with TanStack DB for automatic synchronization.

Supports automatic type inference following the priority order:

  1. Schema inference (highest priority)
  2. QueryFn return type inference (second priority)

Type Parameters

T

T extends StandardSchemaV1<unknown, unknown>

Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn

TQueryFn

TQueryFn extends (context) => Promise<any>

TError

TError = unknown

The type of errors that can occur during queries

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

The type of the query key

TKey

TKey extends string | number = string | number

The type of the item keys

TQueryData

TQueryData = Awaited<ReturnType<TQueryFn>>

Parameters

config

QueryCollectionConfig<InferSchemaOutput<T>, TQueryFn, TError, TQueryKey, TKey, T, Awaited<ReturnType<TQueryFn>>> & object

Configuration options for the Query collection

Returns

CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object

Collection options with utilities for direct writes and manual operations

Examples
ts
// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)

// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)
ts
// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)

// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)
ts
// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)

// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)
ts
// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)

// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)
ts
// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

Call Signature
ts
function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;

function queryCollectionOptions<T, TQueryFn, TError, TQueryKey, TKey, TQueryData>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;

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

Creates query collection options for use with a standard Collection. This integrates TanStack Query with TanStack DB for automatic synchronization.

Supports automatic type inference following the priority order:

  1. Schema inference (highest priority)
  2. QueryFn return type inference (second priority)

Type Parameters

T

T extends object

Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn

TQueryFn

TQueryFn extends (context) => Promise<any> = (context) => Promise<any>

TError

TError = unknown

The type of errors that can occur during queries

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

The type of the query key

TKey

TKey extends string | number = string | number

The type of the item keys

TQueryData

TQueryData = Awaited<ReturnType<TQueryFn>>

Parameters

config

QueryCollectionConfig<T, TQueryFn, TError, TQueryKey, TKey, never, TQueryData> & object

Configuration options for the Query collection

Returns

CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object

Collection options with utilities for direct writes and manual operations

Examples
ts
// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)

// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)
ts
// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)

// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)
ts
// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)

// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)
ts
// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)

// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)
ts
// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

Call Signature
ts
function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;

function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object;

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

Creates query collection options for use with a standard Collection. This integrates TanStack Query with TanStack DB for automatic synchronization.

Supports automatic type inference following the priority order:

  1. Schema inference (highest priority)
  2. QueryFn return type inference (second priority)

Type Parameters

T

T extends StandardSchemaV1<unknown, unknown>

Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn

TError

TError = unknown

The type of errors that can occur during queries

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

The type of the query key

TKey

TKey extends string | number = string | number

The type of the item keys

Parameters

config

QueryCollectionConfig<InferSchemaOutput<T>, (context) => Promise<InferSchemaOutput<T>[]>, TError, TQueryKey, TKey, T, InferSchemaOutput<T>[]> & object

Configuration options for the Query collection

Returns

CollectionConfig<InferSchemaOutput<T>, TKey, T, QueryCollectionUtils<InferSchemaOutput<T>, TKey, InferSchemaInput<T>, TError>> & object

Collection options with utilities for direct writes and manual operations

Examples
ts
// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)

// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)
ts
// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)

// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)
ts
// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)

// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)
ts
// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)

// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)
ts
// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

Call Signature
ts
function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;

function queryCollectionOptions<T, TError, TQueryKey, TKey>(config): CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object;

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

Creates query collection options for use with a standard Collection. This integrates TanStack Query with TanStack DB for automatic synchronization.

Supports automatic type inference following the priority order:

  1. Schema inference (highest priority)
  2. QueryFn return type inference (second priority)

Type Parameters

T

T extends object

Type of the schema if a schema is provided otherwise it is the type of the values returned by the queryFn

TError

TError = unknown

The type of errors that can occur during queries

TQueryKey

TQueryKey extends readonly unknown[] = readonly unknown[]

The type of the query key

TKey

TKey extends string | number = string | number

The type of the item keys

Parameters

config

QueryCollectionConfig<T, (context) => Promise<T[]>, TError, TQueryKey, TKey, never, T[]> & object

Configuration options for the Query collection

Returns

CollectionConfig<T, TKey, never, QueryCollectionUtils<T, TKey, T, TError>> & object

Collection options with utilities for direct writes and manual operations

Examples
ts
// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)

// Type inferred from queryFn return type (NEW!)
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json() as Todo[] // Type automatically inferred!
    },
    queryClient,
    getKey: (item) => item.id, // item is typed as Todo
  })
)
ts
// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)

// Explicit type
const todosCollection = createCollection<Todo>(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    getKey: (item) => item.id,
  })
)
ts
// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)

// Schema inference
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    queryClient,
    schema: todoSchema, // Type inferred from schema
    getKey: (item) => item.id,
  })
)
ts
// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)

// With persistence handlers
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: fetchTodos,
    queryClient,
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      await api.createTodos(transaction.mutations.map(m => m.modified))
    },
    onUpdate: async ({ transaction }) => {
      await api.updateTodos(transaction.mutations)
    },
    onDelete: async ({ transaction }) => {
      await api.deleteTodos(transaction.mutations.map(m => m.key))
    }
  })
)
ts
// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)

// The select option extracts the items array from a response with metadata
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => fetch('/api/todos').then(r => r.json()),
    select: (data) => data.items, // Extract the array of items
    queryClient,
    schema: todoSchema,
    getKey: (item) => item.id,
  })
)
Edit on GitHub
Query DB Collection
RxDB DB Collection
Partners
Code Rabbit
Cloudflare
AG Grid
Netlify
Neon
WorkOS
Clerk
Convex
Electric
Sentry
Prisma
Strapi
Unkey
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.