TanStack DB

https://tanstack.com/db/latest
Admin
TanStack DB is a reactive client store that extends TanStack Query with collections, live queries,...
Tokens:194,820
Snippets:2,165
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Electric Proxy Example with TanStack Start

Source: https://tanstack.com/db/latest/docs/collections/electric-collection

Implement an Electric proxy server using TanStack Start to handle shape configuration, authentication, and authorization. This example demonstrates passing parameters from the Electric client to the proxy.

```typescript
import { createServerFileRoute } from "@tanstack/react-start/server"
import { ELECTRIC_PROTOCOL_QUERY_PARAMS } from "@electric-sql/client"

// Electric URL
const baseUrl = 'http://.../v1/shape'

const serve = async ({ request }: { request: Request }) => {
  // ...check user authorization  
  const url = new URL(request.url)
  const originUrl = new URL(baseUrl)

  // passthrough parameters from electric client
  url.searchParams.forEach((value, key) => {
    if (ELECTRIC_PROTOCOL_QUERY_PARAMS.includes(key)) {
      originUrl.searchParams.set(key, value)
    }
  })

  // set shape parameters 
  // full spec: https://github.com/electric-sql/electric/blob/main/website/electric-api.yaml
  originUrl.searchParams.set("table", "todos")
  // Where clause to filter rows in the table (optional).
  // originUrl.searchParams.set("where", "completed = true")
  
  // Select the columns to sync (optional)
  // originUrl.searchParams.set("columns", "id,text,completed")

  const response = await fetch(originUrl)
  const headers = new Headers(response.headers)
  headers.delete("content-encoding")
  headers.delete("content-length")

  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

export const ServerRoute = createServerFileRoute("/api/todos").methods({
  GET: serve,
})
```

--------------------------------

### Create local-only collections

Source: https://tanstack.com/db/latest/docs/reference/functions/localOnlyCollectionOptions

Examples demonstrating basic setup, initial data population, and mutation handling for local-only collections.

```ts
// Basic local-only collection
const collection = createCollection(
  localOnlyCollectionOptions({
    getKey: (item) => item.id,
  })
)
```

```ts
// Local-only collection with initial data
const collection = createCollection(
  localOnlyCollectionOptions({
    getKey: (item) => item.id,
    initialData: [
      { id: 1, name: 'Item 1' },
      { id: 2, name: 'Item 2' },
    ],
  })
)
```

```ts
// Local-only collection with mutation handlers
const collection = createCollection(
  localOnlyCollectionOptions({
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
      // Custom logic after insert
    },
  })
)
```

--------------------------------

### useLiveQuery Configuration Examples

Source: https://tanstack.com/db/latest/docs/framework/vue/reference/functions/useLiveQuery

Examples demonstrating basic configuration, reactive dependencies, and state handling.

```ts
// Basic config object usage
const { data, status } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})
```

```ts
// With reactive dependencies
const filter = ref('active')
const { data, isReady } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection })
                 .where(({ todos }) => eq(todos.status, filter.value))
}, [filter])
```

```ts
// Handle all states uniformly
const { data, isLoading, isReady, isError } = useLiveQuery({
  query: (q) => q.from({ items: itemCollection })
})

// In template:
// <div v-if="isLoading">Loading...</div>
// <div v-else-if="isError">Something went wrong</div>
// <div v-else-if="!isReady">Preparing...</div>
// <div v-else>{{ data.length }} items loaded</div>
```

--------------------------------

### useLiveQuery Collection Examples

Source: https://tanstack.com/db/latest/docs/framework/vue/reference/functions/useLiveQuery

Examples demonstrating subscription to pre-created collections, reactive references, and mutation handling.

```ts
// Using pre-created query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const { data, collection } = useLiveQuery(myLiveQuery)
```

```ts
// Reactive query collection reference
const selectedQuery = ref(todosQuery)
const { data, collection } = useLiveQuery(selectedQuery)

// Switch queries reactively
selectedQuery.value = archiveQuery
```

```ts
// Access query collection methods directly
const { data, collection, isReady } = useLiveQuery(existingQuery)

// Use underlying collection for mutations
const handleToggle = (id) => {
  collection.value.update(id, draft => { draft.completed = !draft.completed })
}
```

```ts
// Handle states consistently
const { data, isLoading, isError } = useLiveQuery(sharedQuery)

// In template:
// <div v-if="isLoading">Loading...</div>
// <div v-else-if="isError">Error loading data</div>
// <div v-else>
//   <Item v-for="item in data" :key="item.id" v-bind="item" />
// </div>
```

--------------------------------

### Implement ChangeListener examples

Source: https://tanstack.com/db/latest/docs/reference/type-aliases/ChangeListener

Examples demonstrating basic logging and conditional handling of different change types within a listener.

```ts
// Basic change listener
const listener: ChangeListener = (changes) => {
  changes.forEach(change => {
    console.log(`${change.type}: ${change.key}`, change.value)
  })
}

collection.subscribeChanges(listener)
```

```ts
// Handle different change types
const listener: ChangeListener<Todo> = (changes) => {
  for (const change of changes) {
    switch (change.type) {
      case 'insert':
        addToUI(change.value)
        break
      case 'update':
        updateInUI(change.key, change.value, change.previousValue)
        break
      case 'delete':
        removeFromUI(change.key)
        break
    }
  }
}
```

--------------------------------

### Install TanStack DB Svelte Adapter

Source: https://tanstack.com/db/latest/docs/framework/svelte/overview

Install the package via npm.

```sh
npm install @tanstack/svelte-db
```

--------------------------------

### Install ElectricSQL DB Collection Package

Source: https://tanstack.com/db/latest/docs/installation

Install the collection package for real-time synchronization with ElectricSQL.

```sh
npm install @tanstack/electric-db-collection
```

--------------------------------

### Implement onUpdate handler examples

Source: https://tanstack.com/db/latest/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig

Examples showing how to handle updates using transaction IDs or custom matching utilities.

```ts
// Basic Electric update handler with txid (recommended)
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes
  })
  return { txid: result.txid }
}
```

```ts
// Use awaitMatch utility for custom matching
onUpdate: async ({ transaction, collection }) => {
  const { original, changes } = transaction.mutations[0]
  await api.todos.update({ where: { id: original.id }, data: changes })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'update' &&
                 message.value.id === original.id
  )
}
```

--------------------------------

### Install Query Collection dependencies

Source: https://tanstack.com/db/latest/docs/collections/query-collection

Install the required packages for using query collections.

```bash
npm install @tanstack/query-db-collection @tanstack/query-core @tanstack/db
```

--------------------------------

### Install TanStack DB React Adapter

Source: https://tanstack.com/db/latest/docs/framework/react/overview

Install the package via npm.

```sh
npm install @tanstack/react-db
```

--------------------------------

### Install PowerSync DB Collection Package for Web

Source: https://tanstack.com/db/latest/docs/installation

Install the PowerSync collection package and necessary web SDKs for offline-first sync.

```sh
npm install @tanstack/powersync-db-collection @powersync/web @journeyapps/wa-sqlite
```

--------------------------------

### Applying Transactions with PowerSyncTransactor

Source: https://tanstack.com/db/latest/docs/reference/powersync-db-collection/classes/PowerSyncTransactor

This example demonstrates how to create a transaction and apply mutations to a PowerSync collection using PowerSyncTransactor. It shows the setup for a collection and a transaction that commits mutations.

```typescript
const collection = createCollection(
  powerSyncCollectionOptions<Document>({
    database: db,
    table: APP_SCHEMA.props.documents,
  })
)

const addTx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await new PowerSyncTransactor({ database: db }).applyTransaction(transaction)
  },
})

addTx.mutate(() => {
  for (let i = 0; i < 5; i++) {
    collection.insert({ id: randomUUID(), name: `tx-${i}` })
  }
})

await addTx.commit()
await addTx.isPersisted.promise
```

--------------------------------

### Install TanStack DB Vue Adapter

Source: https://tanstack.com/db/latest/docs/framework/vue/overview

Command to install the package via npm.

```sh
npm install @tanstack/vue-db
```

--------------------------------

### caseWhen Usage Examples

Source: https://tanstack.com/db/latest/docs/reference/functions/caseWhen

Examples demonstrating simple scalar conditions, multiple branches, and projection objects.

```ts
caseWhen(gt(user.age, 18), `adult`, `minor`)
```

```ts
caseWhen(
  gt(user.age, 65),
  `senior`,
  gt(user.age, 18),
  `adult`,
  `minor`,
)
```

```ts
caseWhen(gt(user.age, 18), {
  ...user,
  posts: q
    .from({ post: postsCollection })
    .where(({ post }) => eq(post.userId, user.id)),
})
```

--------------------------------

### Install Core Vanilla JS DB Package

Source: https://tanstack.com/db/latest/docs/installation

Install the core TanStack DB package for use without a framework.

```sh
npm install @tanstack/db
```

--------------------------------

### Basic useLiveQuery configuration

Source: https://tanstack.com/db/latest/docs/framework/solid/reference/functions/useLiveQuery

Example of initializing a live query with a basic configuration object.

```ts
// Basic config object usage
const todosQuery = useLiveQuery(() => ({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
}))
```

--------------------------------

### Install TrailBase Collection package

Source: https://tanstack.com/db/latest/docs/collections/trailbase-collection

Install the required dependencies to enable TrailBase integration.

```bash
npm install @tanstack/trailbase-db-collection @tanstack/react-db trailbase
```

--------------------------------

### Defer sync start

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Internal method to defer the start of synchronization.

```ts
_deferSyncStart(): boolean;
```

--------------------------------

### Install Electric Collection Dependencies

Source: https://tanstack.com/db/latest/docs/collections/electric-collection

Install the necessary packages for using Electric collections with TanStack DB and React.

```bash
npm install @tanstack/electric-db-collection @tanstack/react-db
```

--------------------------------

### Using pre-created query collection

Source: https://tanstack.com/db/latest/docs/framework/svelte/reference/functions/useLiveQuery

Example of subscribing to a static query collection.

```ts
// Using pre-created query collection
const myLiveQuery = createLiveQueryCollection((q) =>
  q.from({ todos: todosCollection }).where(({ todos }) => eq(todos.active, true))
)
const queryResult = useLiveQuery(myLiveQuery)
```

--------------------------------

### Install TanStack DB Angular Adapter

Source: https://tanstack.com/db/latest/docs/framework/angular/overview

Install the TanStack DB Angular Adapter using npm.

```sh
npm install @tanstack/angular-db
```

--------------------------------

### Creating a PowerSync Collection with Schema Validation

Source: https://tanstack.com/db/latest/docs/reference/powersync-db-collection/functions/powerSyncCollectionOptions

This example demonstrates how to create a PowerSync collection using `powerSyncCollectionOptions`. It defines the SQLite schema, an advanced Zod validation schema for input and output types, and a deserialization schema to convert SQLite integer values to booleans. This setup allows for flexible data handling and type safety.

```typescript
import { z } from "zod"

// The PowerSync SQLite schema
const APP_SCHEMA = new Schema({
  documents: new Table({
    name: column.text,
    // Booleans are represented as integers in SQLite
    is_active: column.integer
  }),
})

// Advanced Zod validations.
// We accept boolean values as input for operations and expose Booleans in query results
const schema = z.object({
  id: z.string(),
  isActive: z.boolean(), // TInput and TOutput are boolean
})

// The deserializationSchema converts the SQLite synced INTEGER (0/1) values to booleans.
const deserializationSchema = z.object({
  id: z.string(),
  isActive: z.number().nullable().transform((val) => val == null ? true : val > 0),
})

const collection = createCollection(
  powerSyncCollectionOptions({
    database: db,
    table: APP_SCHEMA.props.documents,
    schema,
    deserializationSchema,
  })
)
```

--------------------------------

### Creating a PowerSync Collection Example

Source: https://tanstack.com/db/latest/docs/reference/powersync-db-collection/type-aliases/PowerSyncCollectionConfig

Demonstrates how to set up a PowerSyncDatabase and create a collection using the powerSyncCollectionOptions helper function.

```typescript
const APP_SCHEMA = new Schema({
  documents: new Table({
    name: column.text,
  }),
})

const db = new PowerSyncDatabase({
  database: {
    dbFilename: "test.sqlite",
  },
  schema: APP_SCHEMA,
})

const collection = createCollection(
  powerSyncCollectionOptions({
    database: db,
    table: APP_SCHEMA.props.documents
  })
)
```

--------------------------------

### Mutation Lifecycle Example

Source: https://tanstack.com/db/latest/docs/guides/mutations

Demonstrates the immediate application of optimistic state followed by backend persistence.

```tsx
// Step 1: Optimistic state applied immediately
todoCollection.update(todo.id, (draft) => {
  draft.completed = true
})
// UI updates instantly with optimistic state

// Step 2-3: onUpdate handler persists to backend
// Step 4: Handler waits for sync back
// Step 5: Optimistic state replaced by server state
```

--------------------------------

### Basic Configuration Usage

Source: https://tanstack.com/db/latest/docs/framework/react/reference/functions/useLiveQuery

Example of initializing a live query with a basic configuration object and garbage collection time.

```ts
// Basic config object usage
const { data, status } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})
```

--------------------------------

### Install Query Collection Package

Source: https://tanstack.com/db/latest/docs/installation

Install the collection package for integrating TanStack DB with TanStack Query for data fetching.

```sh
npm install @tanstack/query-db-collection
```

--------------------------------

### Install TrailBase DB Collection Package

Source: https://tanstack.com/db/latest/docs/installation

Install the collection package for syncing data with TrailBase backends.

```sh
npm install @tanstack/trailbase-db-collection
```

--------------------------------

### Basic useLiveQuery usage

Source: https://tanstack.com/db/latest/docs/framework/solid/reference/functions/useLiveQuery

Examples of basic queries, dependency-based re-execution, and join patterns.

```ts
// Basic query with object syntax
const todosQuery = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)
```

```ts
// With dependencies that trigger re-execution
const todosQuery = useLiveQuery(
  (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority())),
)
```

```ts
// Join pattern
const personIssues = useLiveQuery((q) =>
  q.from({ issues: issueCollection })
   .join({ persons: personCollection }, ({ issues, persons }) =>
     eq(issues.userId, persons.id)
   )
   .select(({ issues, persons }) => ({
     id: issues.id,
     title: issues.title,
     userName: persons.name
   }))
)
```

--------------------------------

### Resume sync start

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Internal method to resume synchronization.

```ts
_resumeSyncStart(): void;
```

--------------------------------

### Configure startSync behavior

Source: https://tanstack.com/db/latest/docs/reference/interfaces/LocalStorageCollectionConfig

Determines if syncing starts immediately upon creation. Defaults to false.

```ts
optional startSync: boolean;
```

```ts
false
```

--------------------------------

### useLiveQuery Examples

Source: https://tanstack.com/db/latest/docs/framework/react/reference/functions/useLiveQuery

Various patterns for implementing live queries, including filtering, joining, and handling states.

```ts
// Prefer config object syntax
const { data, isLoading } = useLiveQuery({
  query: (q) =>
    q.from({ todos: todosCollection })
     .where(({ todos }) => eq(todos.completed, false))
     .select(({ todos }) => ({ id: todos.id, text: todos.text }))
})
```

```ts
// Single result query
const { data } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => eq(todos.id, 1))
         .findOne()
})
```

```ts
// Structured captured values are included in derived query identity
const { data, state } = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection })
         .where(({ todos }) => gt(todos.priority, minPriority)),
})
```

```ts
// Return undefined or null to disable a query
const { data, isEnabled } = useLiveQuery({
  query: (q) => {
    if (!userId) return undefined
    return q.from({ todos: todosCollection })
            .where(({ todos }) => eq(todos.userId, userId))
  },
})
```

```ts
// Join pattern
const { data } = useLiveQuery({
  query: (q) =>
    q.from({ issues: issueCollection })
     .join({ persons: personCollection }, ({ issues, persons }) =>
       eq(issues.userId, persons.id)
     )
     .select(({ issues, persons }) => ({
       id: issues.id,
       title: issues.title,
       userName: persons.name
     }))
})
```

```ts
// Handle loading and error states
const { data, isLoading, isError, status } = useLiveQuery({
  query: (q) => q.from({ todos: todoCollection })
})

if (isLoading) return <div>Loading...</div>
if (isError) return <div>Error: {status}</div>

return (
  <ul>
    {data.map(todo => <li key={todo.id}>{todo.text}</li>)}
  </ul>
)
```

--------------------------------

### Install React Native UUID polyfill

Source: https://tanstack.com/db/latest/docs/overview

Install the required package to provide crypto.randomUUID() functionality.

```bash
npm install react-native-random-uuid
```

--------------------------------

### Install TanStack DB dependencies

Source: https://tanstack.com/db/latest/docs/quick-start

Install the core packages required to use TanStack DB with React and TanStack Query.

```bash
npm install @tanstack/react-db @tanstack/query-db-collection @tanstack/query-core
```

--------------------------------

### Install RxDB Collection Packages

Source: https://tanstack.com/db/latest/docs/collections/rxdb-collection

Install the necessary packages for RxDB collection integration with TanStack DB and your chosen framework.

```bash
npm install @tanstack/rxdb-db-collection rxdb @tanstack/react-db
```

--------------------------------

### localStorage Collection Examples

Source: https://tanstack.com/db/latest/docs/reference/functions/localStorageCollectionOptions

Various configurations for initializing a localStorage collection, including custom storage and mutation handlers.

```ts
// Basic localStorage collection
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
  })
)
```

```ts
// localStorage collection with custom storage
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    storage: window.sessionStorage, // Use sessionStorage instead
    getKey: (item) => item.id,
  })
)
```

```ts
// localStorage collection with mutation handlers
const collection = createCollection(
  localStorageCollectionOptions({
    storageKey: 'todos',
    getKey: (item) => item.id,
    onInsert: async ({ transaction }) => {
      console.log('Item inserted:', transaction.mutations[0].modified)
    },
  })
)
```

--------------------------------

### SQL Join Optionality Examples

Source: https://tanstack.com/db/latest/docs/reference/type-aliases/ApplyJoinOptionalityToMergedSchema

Examples illustrating how different SQL join types affect the optionality of tables in a merged schema.

```sql
FROM users LEFT JOIN orders  -- orders becomes optional
FROM users RIGHT JOIN orders -- users becomes optional
FROM users FULL JOIN orders  -- both become optional
FROM users INNER JOIN orders -- both remain required
```

--------------------------------

### Basic Query Usage

Source: https://tanstack.com/db/latest/docs/framework/vue/reference/functions/useLiveQuery

A simple example of using the object syntax to fetch data.

```ts
const { data, isLoading } = useLiveQuery((q) =>
  q.from({ todos: todosCollection })
   .where(({ todos }) => eq(todos.completed, false))
   .select(({ todos }) => ({ id: todos.id, text: todos.text }))
)
```

--------------------------------

### Retrieve keys from start

Source: https://tanstack.com/db/latest/docs/reference/interfaces/IndexInterface

Fetches a specified number of keys from the beginning of the index, optionally filtered by a predicate.

```ts
takeFromStart: (n, filterFn?) => TKey[];
```

--------------------------------

### Install PowerSync DB Collection Package for React Native

Source: https://tanstack.com/db/latest/docs/installation

Install the PowerSync collection package and necessary React Native SDKs for offline-first sync.

```sh
npm install @tanstack/powersync-db-collection @powersync/react-native @powersync/op-sqlite @op-engineering/op-sqlite
```

--------------------------------

### Take method

Source: https://tanstack.com/db/latest/docs/reference/interfaces/IndexInterface

Retrieves a specified number of keys starting from a given key, optionally filtered.

```ts
take: (n, from, filterFn?) => TKey[];
```

--------------------------------

### Capture stack trace example

Source: https://tanstack.com/db/latest/docs/reference/classes/InvalidJoinConditionSourceMismatchError

Demonstrates how to use Error.captureStackTrace to generate a stack trace for an object.

```js
const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`
```

--------------------------------

### Implement onDelete handlers

Source: https://tanstack.com/db/latest/docs/reference/interfaces/CollectionConfig

Examples of implementing onDelete for basic deletion, batch processing, user confirmation, and optimistic rollback.

```ts
// Basic delete handler
onDelete: async ({ transaction, collection }) => {
  const deletedKey = transaction.mutations[0].key
  await api.deleteTodo(deletedKey)
}
```

```ts
// Delete handler with multiple items
onDelete: async ({ transaction, collection }) => {
  const keysToDelete = transaction.mutations.map(m => m.key)
  await api.deleteTodos(keysToDelete)
}
```

```ts
// 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)
}
```

```ts
// 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
  }
}
```

--------------------------------

### Implement onInsert handlers

Source: https://tanstack.com/db/latest/docs/reference/interfaces/CollectionConfig

Examples of implementing onInsert for basic insertion, batch processing, error handling, and metadata usage.

```ts
// Basic insert handler
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.createTodo(newItem)
}
```

```ts
// Insert handler with multiple items
onInsert: async ({ transaction, collection }) => {
  const items = transaction.mutations.map(m => m.modified)
  await api.createTodos(items)
}
```

```ts
// Insert handler with error handling
onInsert: async ({ transaction, collection }) => {
  try {
    const newItem = transaction.mutations[0].modified
    const result = await api.createTodo(newItem)
    return result
  } catch (error) {
    console.error('Insert failed:', error)
    throw error // This will cause the transaction to fail
  }
}
```

```ts
// Insert handler with metadata
onInsert: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.createTodo(mutation.modified, {
    source: mutation.metadata?.source,
    timestamp: mutation.createdAt
  })
}
```

--------------------------------

### preload

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Preloads the collection data by starting sync if not already started.

```APIDOC
## preload()

### Description
Preload the collection data by starting sync if not already started. Multiple concurrent calls will share the same promise.

### Returns
- **Promise<void>** - A promise that resolves when the collection is preloaded.
```

--------------------------------

### get(key)

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Get the current value for a key (virtual derived state).

```APIDOC
## get(key)

### Description
Get the current value for a key (virtual derived state).

### Parameters
- **key** (TKey) - Required - The key to retrieve.

### Returns
- **WithVirtualProps<TOutput, TKey> | undefined** - The value associated with the key or undefined.
```

--------------------------------

### Comparison of useLiveQuery and useLiveSuspenseQuery Patterns

Source: https://tanstack.com/db/latest/docs/guides/live-queries

Examples demonstrating how to handle states in components versus using Suspense, and the recommended pattern for router loaders.

```tsx
// useLiveQuery - handle states in component
function UserList() {
  const { data, status, isLoading } = useLiveQuery({
    query: (q) => q.from({ user: usersCollection }),
  })

  if (isLoading) return <div>Loading...</div>
  if (status === 'error') return <div>Error loading users</div>

  return <ul>{data?.map(user => <li key={user.id}>{user.name}</li>)}</ul>
}

// useLiveSuspenseQuery - handle states with Suspense/ErrorBoundary
function UserList() {
  const { data } = useLiveSuspenseQuery({
    query: (q) => q.from({ user: usersCollection }),
  })

  return <ul>{data.map(user => <li key={user.id}>{user.name}</li>)}</ul>
}

// useLiveQuery with router loader - recommended pattern
// In your route configuration:
const route = {
  path: '/users',
  loader: async () => {
    // Preload the collection in the loader
    await usersCollection.preload()
    return null
  },
  component: UserList,
}

// In your component:
function UserList() {
  // Collection is already loaded, so data is immediately available
  const { data } = useLiveQuery({
    query: (q) => q.from({ user: usersCollection }),
  })

  return <ul>{data?.map(user => <li key={user.id}>{user.name}</li>)}</ul>
}
```

--------------------------------

### Queued Mutations Example

Source: https://tanstack.com/db/latest/docs/reference/functions/createPacedMutations

Illustrates using createPacedMutations with a queue strategy to process mutations sequentially, ensuring order of operations.

```APIDOC
## Example: Queued Mutations

```ts
// Queue strategy for sequential processing
const addTodo = createPacedMutations<{ text: string }>({
  onMutate: ({ text }) => {
    collection.insert({ id: uuid(), text, completed: false })
  },
  mutationFn: async ({ transaction }) => {
    await api.save(transaction.mutations)
  },
  strategy: queueStrategy({
    wait: 200,
    addItemsTo: 'back',
    getItemsFrom: 'front'
  })
})
```
```

--------------------------------

### Implement onUpdate handlers

Source: https://tanstack.com/db/latest/docs/reference/interfaces/CollectionConfig

Examples of implementing onUpdate for basic updates, partial updates, batch processing, and optimistic rollback.

```ts
// Basic update handler
onUpdate: async ({ transaction, collection }) => {
  const updatedItem = transaction.mutations[0].modified
  await api.updateTodo(updatedItem.id, updatedItem)
}
```

```ts
// Update handler with partial updates
onUpdate: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  const changes = mutation.changes // Only the changed fields
  await api.updateTodo(mutation.original.id, changes)
}
```

```ts
// 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)
}
```

```ts
// 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
  }
}
```

--------------------------------

### Initialize method

Source: https://tanstack.com/db/latest/docs/reference/classes/BaseIndex

Initializes the index with optional configuration.

```ts
abstract protected initialize(options?): void;
```

--------------------------------

### Initialize DbProvider

Source: https://tanstack.com/db/latest/docs/framework/react/overview

Create a DbClient instance and wrap the application with the DbProvider.

```tsx
import { DbClient, DbProvider } from '@tanstack/react-db'

const dbClient = new DbClient()

root.render(
  <DbProvider client={dbClient}>
    <App />
  </DbProvider>
)
```

--------------------------------

### Functional select example

Source: https://tanstack.com/db/latest/docs/reference/classes/BaseQueryBuilder

Example of using the functional select method to transform row data.

```ts
q.fn.select((row) => ({
  name: row.user.name.toUpperCase(),
  age: row.user.age + 1,
}))
```

--------------------------------

### Install Vue DB Package

Source: https://tanstack.com/db/latest/docs/installation

Install the Vue-specific package for TanStack DB. Compatible with Vue v3.3.0+.

```sh
npm install @tanstack/vue-db
```

--------------------------------

### Configure Query Collection with initialData

Source: https://tanstack.com/db/latest/docs/collections/query-initial-placeholder-data-design

Example of using initialData within queryCollectionOptions to provide server-side data.

```ts
queryCollectionOptions({
  queryKey: ["todos"],
  queryFn: fetchTodos,
  initialData: { items: serverTodos, nextCursor: null },
  select: (response) => response.items,
  // ...
})
```

--------------------------------

### Use useLiveInfiniteQuery

Source: https://tanstack.com/db/latest/docs/framework/svelte/overview

Implement paginated data with live updates using useLiveInfiniteQuery.

```svelte
<script>
  import { useLiveInfiniteQuery } from '@tanstack/svelte-db'
  import { eq } from '@tanstack/db'

  let category = $state('news')
  const query = useLiveInfiniteQuery(
    (q) =>
      q
        .from({ posts: postsCollection })
        .where(({ posts }) => eq(posts.category, category))
        .orderBy(({ posts }) => posts.createdAt, 'desc'),
    { pageSize: 20 },
    [() => category],
  )
</script>

{#each query.data as post (post.id)}
  <article>{post.title}</article>
{/each}

{#if query.hasNextPage}
  <button
    disabled={query.isFetchingNextPage}
    onclick={() => query.fetchNextPage()}
  >
    Load more
  </button>
{/if}
```

--------------------------------

### Create RxDatabase and RxCollection

Source: https://tanstack.com/db/latest/docs/collections/rxdb-collection

Set up an RxDB database and define a collection with a schema. This example uses the localStorage storage engine and includes optional JSON schema validation and dev mode plugins.

```typescript
import { createRxDatabase, addRxPlugin } from 'rxdb/plugins/core'

/**
 * Here we use the localStorage based storage for RxDB.
 * RxDB has a wide range of storages based on Dexie.js, IndexedDB, SQLite, and more.
 */
import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'

// add json-schema validation (optional)
import { wrappedValidateAjvStorage } from 'rxdb/plugins/validate-ajv';

// Enable dev mode (optional, recommended during development)
import { RxDBDevModePlugin } from 'rxdb/plugins/dev-mode'
addRxPlugin(RxDBDevModePlugin)

type Todo = { id: string; text: string; completed: boolean }

const db = await createRxDatabase({
  name: 'my-todos',
  storage: wrappedValidateAjvStorage({
    storage: getRxStorageLocalstorage()
  })
})

await db.addCollections({
  todos: {
    schema: {
      title: 'todos',
      version: 0,
      type: 'object',
      primaryKey: 'id',
      properties: {
        id: { type: 'string', maxLength: 100 },
        text: { type: 'string' },
        completed: { type: 'boolean' },
      },
      required: ['id', 'text', 'completed'],
    },
  },
})
```

--------------------------------

### Configure Query Collection Options

Source: https://tanstack.com/db/latest/docs/collections/query-collection

Demonstrates initializing a collection with standard TanStack Query observer options passed through the queryCollectionOptions helper.

```ts
const todosCollection = createCollection(
  queryCollectionOptions({
    queryKey: ["todos"],
    queryFn: fetchTodos,
    queryClient,
    getKey: (todo) => todo.id,
    refetchOnWindowFocus: true,
    refetchOnReconnect: true,
    refetchOnMount: "always",
    networkMode: "online",
  })
)
```

--------------------------------

### Initialize DbClient

Source: https://tanstack.com/db/latest/docs/reference/classes/DbClient

Instantiate a new DbClient instance with optional configuration.

```ts
new DbClient(options): DbClient;
```

--------------------------------

### takeFromStart(n, filterFn?)

Source: https://tanstack.com/db/latest/docs/reference/classes/ReverseIndex

Retrieves a specified number of keys from the beginning of the index.

```APIDOC
## takeFromStart(n, filterFn?)

### Description
Retrieves a specified number of keys from the beginning of the index, optionally filtered by a function.

### Parameters
- **n** (number) - Required - Number of items to take.
- **filterFn** ((key) => boolean) - Optional - Function to filter keys.

### Returns
- **TKey[]** - An array of retrieved keys.
```

--------------------------------

### Create a live query collection with convenience function

Source: https://tanstack.com/db/latest/docs/guides/live-queries

Use the shortcut function for simpler live query collection definitions.

```ts
import { createLiveQueryCollection, eq } from '@tanstack/db'

const activeUsers = createLiveQueryCollection((q) =>
  q
    .from({ user: usersCollection })
    .where(({ user }) => eq(user.active, true))
    .select(({ user }) => ({
      id: user.id,
      name: user.name,
    }))
)
```

--------------------------------

### isLimitSubset() Examples

Source: https://tanstack.com/db/latest/docs/reference/functions/isLimitSubset

Examples demonstrating how `isLimitSubset` works with different limit values. It returns true if the subset is satisfied by the superset, and false otherwise. Undefined supersets are treated as unlimited.

```typescript
isLimitSubset(10, 20) // true (requesting 10 items when 20 are available)
```

```typescript
isLimitSubset(20, 10) // false (requesting 20 items when only 10 are available)
```

```typescript
isLimitSubset(10, undefined) // true (requesting 10 items when unlimited are available)
```

--------------------------------

### Build method

Source: https://tanstack.com/db/latest/docs/reference/classes/BaseIndex

Populates the index with a collection of entries.

```ts
abstract build(entries): void;
```

--------------------------------

### Implement multi-step workflows

Source: https://tanstack.com/db/latest/docs/guides/mutations

Illustrates using a manual transaction to batch updates across multiple user interaction steps.

```ts
const reviewTx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await api.batchUpdate(transaction.mutations)
  },
})

// Step 1: User makes initial changes
reviewTx.mutate(() => {
  todoCollection.update(id1, (draft) => {
    draft.status = "reviewed"
  })
  todoCollection.update(id2, (draft) => {
    draft.status = "reviewed"
  })
})

// Step 2: Show preview to user...

// Step 3: User confirms or makes additional changes
reviewTx.mutate(() => {
  todoCollection.update(id3, (draft) => {
    draft.status = "reviewed"
  })
})

// Step 4: User commits all changes at once
await reviewTx.commit()
// OR user cancels
// reviewTx.rollback()
```

--------------------------------

### deserializationSchema Example

Source: https://tanstack.com/db/latest/docs/reference/powersync-db-collection/type-aliases/ConfigWithArbitraryCollectionTypes

Provides an example of how to define the deserializationSchema for transforming and validating incoming data from SQLite types to application-specific output types. This is useful for handling richer types like Dates or objects.

```typescript
deserializationSchema: z.object({
  createdAt: z.preprocess((val) => new Date(val as string), z.date()),
  meta: z.preprocess((val) => JSON.parse(val as string), z.object({ ... })),
})
```

--------------------------------

### Custom SQLite Column Serialization Example

Source: https://tanstack.com/db/latest/docs/reference/powersync-db-collection/type-aliases/SerializerConfig

Provides an example of how to use the `serializer` property to customize the serialization of specific columns for SQLite storage. This allows for custom handling of data types like dates and objects.

```typescript
serializer: {
  createdAt: (date) => date.getTime(), // Store as timestamp
  meta: (meta) => JSON.stringify(meta), // Custom object serialization
}
```

--------------------------------

### entries()

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Get all entries (virtual derived state).

```APIDOC
## entries()

### Description
Get all entries (virtual derived state).

### Returns
- **IterableIterator<[TKey, WithVirtualProps<TOutput, TKey>]>** - An iterator of collection entries.
```

--------------------------------

### Get status

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the current status of the collection.

```ts
get status(): CollectionStatus;
```

--------------------------------

### Get toArray

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the current state of the collection as an Array.

```ts
get toArray(): WithVirtualProps<TOutput, TKey>[];
```

--------------------------------

### Get size

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the cached current size of the collection.

```ts
get size(): number;
```

--------------------------------

### Implement Simple REST API with Predicate Push-Down

Source: https://tanstack.com/db/latest/docs/collections/query-collection

Example of configuring a collection with on-demand sync mode and using helpers to translate AST filters into REST query parameters.

```typescript
import { createCollection } from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'
import { parseLoadSubsetOptions } from '@tanstack/db'
import { QueryClient } from '@tanstack/query-core'

const queryClient = new QueryClient()

const productsCollection = createCollection(
  queryCollectionOptions({
    id: 'products',
    queryKey: ['products'],
    queryClient,
    getKey: (item) => item.id,
    syncMode: 'on-demand', // Enable predicate push-down

    queryFn: async (ctx) => {
      const { limit, offset, where, orderBy } = ctx.meta.loadSubsetOptions

      // Parse the expressions into simple format
      const parsed = parseLoadSubsetOptions({ where, orderBy, limit })

      // Build query parameters from parsed filters
      const params = new URLSearchParams()

      // Add filters
      parsed.filters.forEach(({ field, operator, value }) => {
        const fieldName = field.join('.')
        if (operator === 'eq') {
          params.set(fieldName, String(value))
        } else if (operator === 'lt') {
          params.set(`${fieldName}_lt`, String(value))
        } else if (operator === 'gt') {
          params.set(`${fieldName}_gt`, String(value))
        }
      })

      // Add sorting
      if (parsed.sorts.length > 0) {
        const sortParam = parsed.sorts
          .map(s => `${s.field.join('.')}:${s.direction}`)
          .join(',')
        params.set('sort', sortParam)
      }

      // Add limit
      if (parsed.limit) {
        params.set('limit', String(parsed.limit))
      }

      // Add offset for pagination
      if (offset) {
        params.set('offset', String(offset))
      }

      const response = await fetch(`/api/products?${params}`)
      return response.json()
    },
  })
)

// Usage with live queries
import { createLiveQueryCollection } from '@tanstack/react-db'
import { eq, lt, and } from '@tanstack/db'

const affordableElectronics = createLiveQueryCollection({
  query: (q) =>
    q.from({ product: productsCollection })
     .where(({ product }) => and(
       eq(product.category, 'electronics'),
       lt(product.price, 100)
     ))
     .orderBy(({ product }) => product.price, 'asc')
     .limit(10)
     .select(({ product }) => product)
})

// This triggers a queryFn call with:
// GET /api/products?category=electronics&price_lt=100&sort=price:asc&limit=10
// When paginating, offset is included: &offset=20
```

--------------------------------

### Get compareOptions

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the collation configuration for string comparisons.

```ts
get compareOptions(): StringCollationConfig;
```

--------------------------------

### Get stats method

Source: https://tanstack.com/db/latest/docs/reference/classes/BaseIndex

Retrieves statistics about the current index.

```ts
getStats(): IndexStats;
```

--------------------------------

### useLiveQuery<TContext>(config, deps?)

Source: https://tanstack.com/db/latest/docs/framework/svelte/reference/functions/useLiveQuery

Creates a live query using a configuration object, returning a reactive object containing query data, state, and status information.

```APIDOC
## useLiveQuery<TContext>(config, deps?)

### Description
Creates a live query using a configuration object. This function returns a reactive object that tracks query data, loading state, error status, and readiness.

### Parameters
- **config** (UseLiveQueryConfig<TContext>) - Required - Configuration object containing the query definition and options.
- **deps** (() => unknown[]) - Optional - An array of reactive dependencies that trigger query re-execution when changed.

### Returns
- **UseLiveQueryReturn** - A reactive object containing query data, state, and status information.

### Example
```ts
const todosQuery = useLiveQuery({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
})
```
```

--------------------------------

### Get subscriberCount

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the total number of active subscribers to the collection.

```ts
get subscriberCount(): number;
```

--------------------------------

### createCollection<T, TKey, TUtils>(options)

Source: https://tanstack.com/db/latest/docs/reference/functions/createCollection

Initializes a new Collection instance. It accepts configuration options including schema, key extraction logic, and optional synchronization or operation hooks.

```APIDOC
## createCollection<T, TKey, TUtils>(options)

### Description
Creates a new Collection instance with the given configuration. This function is the primary entry point for defining data collections in TanStack DB.

### Parameters
- **options** (CollectionConfig<T, TKey, never, TUtils> & object & NonSingleResult) - Required - Configuration object containing schema, key extraction logic, and optional sync/operation handlers.

### Returns
- **Collection<T, TKey, TUtils, never, T> & NonSingleResult** - A new Collection instance with utilities exposed at the top level and under .utils.

### Usage Example
```ts
const todos = createCollection({
  id: "todos",
  getKey: (todo) => todo.id,
  schema,
  sync: { sync: () => {} }
})

// Insert an item
const tx = todos.insert({ id: "1", text: "Buy milk", completed: false })
await tx.isPersisted.promise
```
```

--------------------------------

### Get isLoadingSubset

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Checks if the collection is currently in the process of loading more data.

```ts
get isLoadingSubset(): boolean;
```

--------------------------------

### Get indexes

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the resolved indexes used for query optimization.

```ts
get indexes(): Map<number, BaseIndex<TKey>>;
```

--------------------------------

### Initialize TanStack DB and define a collection

Source: https://tanstack.com/db/latest/docs/quick-start

Sets up the DbClient and defines a collection descriptor using queryCollectionOptions to handle data fetching and updates.

```tsx
import {
  DbClient,
  DbProvider,
  collectionOptions,
  eq,
  useDbClient,
  useLiveQuery,
} from '@tanstack/react-db'
import { QueryClient } from '@tanstack/query-core'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

const queryClient = new QueryClient()
const dbClient = new DbClient({ queryClient })

// Define a stable collection descriptor that loads data using TanStack Query
const todoCollection = collectionOptions('todos', (client) =>
  queryCollectionOptions({
    id: 'todos',
    queryKey: ['todos'],
    queryClient: client.requireDependency<QueryClient>('queryClient'),
    queryFn: async () => {
      const response = await fetch('/api/todos')
      return response.json()
    },
    getKey: (item) => item.id,
    onUpdate: async ({ transaction }) => {
      const { original, modified } = transaction.mutations[0]
      await fetch(`/api/todos/${original.id}`, {
        method: 'PUT',
        body: JSON.stringify(modified),
      })
    },
  })
)

function useTodoCollection() {
  return useDbClient().collection(todoCollection)
}

function Todos() {
  const todosCollection = useTodoCollection()

  // Live query that updates automatically when data changes
  const { data: todos } = useLiveQuery({
    query: (q) =>
      q.from({ todo: todoCollection })
       .where(({ todo }) => eq(todo.completed, false))
       .orderBy(({ todo }) => todo.createdAt, 'desc'),
  })

  const toggleTodo = (todo) => {
    // Instantly applies optimistic state, then syncs to server
    todosCollection.update(todo.id, (draft) => {
      draft.completed = !draft.completed
    })
  }

  return (
    <ul>
      {todos.map((todo) => (
        <li key={todo.id} onClick={() => toggleTodo(todo)}>
          {todo.text}
        </li>
      ))}
    </ul>
  )
}

function App() {
  return (
    <DbProvider client={dbClient}>
      <Todos />
    </DbProvider>
  )
}
```

--------------------------------

### Get _layoutRevision

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Retrieves the monotonic revision of explicit layout-only publications.

```ts
get _layoutRevision(): number;
```

--------------------------------

### Get a dependency

Source: https://tanstack.com/db/latest/docs/reference/classes/DbClient

Retrieves a dependency by its key, returning undefined if not found.

```ts
getDependency<T>(key): T | undefined;
```

--------------------------------

### Retrieve run count

Source: https://tanstack.com/db/latest/docs/reference/type-aliases/LiveQueryCollectionUtils

Method to get the current execution count of the query.

```ts
getRunCount: () => number;
```

--------------------------------

### Initialize and use DeduplicatedLoadSubset

Source: https://tanstack.com/db/latest/docs/reference/classes/DeduplicatedLoadSubset

Demonstrates creating an instance of DeduplicatedLoadSubset, performing subset loads, and resetting the internal state.

```ts
const dedupe = new DeduplicatedLoadSubset({ loadSubset: myLoadSubset, onDeduplicate: (opts) => console.log(`Call was deduplicated:`, opts) })

// First call - fetches data
await dedupe.loadSubset({ where: gt(ref('age'), val(10)) })

// Second call - subset of first, returns true immediately
await dedupe.loadSubset({ where: gt(ref('age'), val(20)) })

// Clear state to start fresh
dedupe.reset()
```

--------------------------------

### size Accessor

Source: https://tanstack.com/db/latest/docs/reference/classes/SortedMap

Gets the number of key-value pairs currently stored in the SortedMap.

```APIDOC
## size Accessor

### Description
Gets the number of key-value pairs in the map.

### Returns
`number` - The number of entries in the map.
```

--------------------------------

### useLiveQuery(config, deps?)

Source: https://tanstack.com/db/latest/docs/framework/vue/reference/functions/useLiveQuery

Creates a live query using a configuration object. This method allows defining the query logic and optional reactive dependencies that trigger re-execution.

```APIDOC
## function useLiveQuery<TContext>(config, deps?)

### Description
Creates a live query using a configuration object. The query automatically updates when reactive dependencies change.

### Parameters
- **config** (LiveQueryCollectionConfig<TContext>) - Required - Configuration object containing the query definition and options.
- **deps** (unknown[]) - Optional - Array of reactive dependencies that trigger query re-execution when changed.

### Returns
- **UseLiveQueryReturn<TContext>** - A reactive object containing query data, state (isLoading, isReady, isError), and status information.
```

--------------------------------

### useLiveQuery<TContext>(config)

Source: https://tanstack.com/db/latest/docs/framework/solid/reference/functions/useLiveQuery

Creates a live query using a configuration object. Returns an accessor that provides data and status properties.

```APIDOC
## useLiveQuery<TContext>(config)

### Description
Creates a live query using a configuration object. The returned accessor provides data with Suspense support and includes state and status information as properties.

### Parameters
- **config** (Accessor<LiveQueryCollectionConfig<TContext, RootQueryResult<TContext>>>) - Required - Configuration object containing the query and options.

### Returns
- **Accessor** - An accessor that returns the query data and exposes state properties like `isLoading`, `isError`, and `isReady`.

### Example
```ts
const todosQuery = useLiveQuery(() => ({
  query: (q) => q.from({ todos: todosCollection }),
  gcTime: 60000
}))
```
```

--------------------------------

### toArrayWhenReady

Source: https://tanstack.com/db/latest/docs/reference/classes/CollectionImpl

Gets the current state of the collection as an Array, resolving only when data is available.

```APIDOC
## toArrayWhenReady()

### Description
Gets the current state of the collection as an Array, but only resolves when data is available. Waits for the first sync commit to complete before resolving.

### Returns
- **Promise<WithVirtualProps<TOutput, TKey>[]>** - Promise that resolves to an Array containing all items in the collection.
```
Tokens:
Raw