@tanstack/db 0.5.30 → 0.5.31

package/skills/db-core/mutations-optimistic/references/transaction-api.md

@@ -0,0 +1,207 @@
+# Transaction API Reference
+
+## createTransaction
+
+```ts
+import { createTransaction } from "@tanstack/db"
+
+const tx = createTransaction<T>({
+  id?: string,                        // defaults to crypto.randomUUID()
+  autoCommit?: boolean,               // default true -- commit after mutate()
+  mutationFn: MutationFn<T>,          // (params: { transaction }) => Promise<any>
+  metadata?: Record<string, unknown>, // custom data attached to the transaction
+})
+```
+
+## Transaction Object
+
+```ts
+interface Transaction<T> {
+  id: string
+  state: 'pending' | 'persisting' | 'completed' | 'failed'
+  mutations: Array<PendingMutation<T>>
+  autoCommit: boolean
+  createdAt: Date
+  sequenceNumber: number
+  metadata: Record<string, unknown>
+  error?: { message: string; error: Error }
+
+  // Deferred promise -- resolves when mutationFn completes, rejects on failure
+  isPersisted: {
+    promise: Promise<Transaction<T>>
+    resolve: (value: Transaction<T>) => void
+    reject: (reason?: any) => void
+  }
+
+  // Execute collection operations inside the ambient transaction context
+  mutate(callback: () => void): Transaction<T>
+
+  // Commit -- calls mutationFn, transitions to persisting -> completed|failed
+  commit(): Promise<Transaction<T>>
+
+  // Rollback -- transitions to failed, also rolls back conflicting transactions
+  rollback(config?: { isSecondaryRollback?: boolean }): Transaction<T>
+}
+```
+
+**Lifecycle:** `pending` -> `persisting` -> `completed` | `failed`
+
+- `mutate()` only allowed in `pending` state (throws `TransactionNotPendingMutateError`)
+- `commit()` only allowed in `pending` state (throws `TransactionNotPendingCommitError`)
+- `rollback()` allowed in `pending` or `persisting` (throws `TransactionAlreadyCompletedRollbackError` if completed)
+- Failed `mutationFn` automatically triggers `rollback()`
+- Rollback cascades to other pending transactions sharing the same item keys
+
+## PendingMutation Type
+
+```ts
+interface PendingMutation<T, TOperation = 'insert' | 'update' | 'delete'> {
+  mutationId: string // unique id for this mutation
+  original: TOperation extends 'insert' ? {} : T // state before mutation
+  modified: T // state after mutation
+  changes: Partial<T> // only the changed fields
+  key: any // collection-local key
+  globalKey: string // globally unique key (collectionId + key)
+  type: TOperation // "insert" | "update" | "delete"
+  metadata: unknown // user-provided metadata
+  syncMetadata: Record<string, unknown> // adapter-specific metadata
+  optimistic: boolean // whether applied optimistically (default true)
+  createdAt: Date
+  updatedAt: Date
+  collection: Collection // reference to the source collection
+}
+```
+
+## Mutation Merging Rules
+
+When multiple mutations target the same item (same `globalKey`) within a
+transaction, they merge:
+
+| Existing | Incoming | Result    | Notes                              |
+| -------- | -------- | --------- | ---------------------------------- |
+| insert   | update   | insert    | Merge changes, keep empty original |
+| insert   | delete   | _removed_ | Both mutations cancel out          |
+| update   | update   | update    | Union changes, keep first original |
+| update   | delete   | delete    | Delete dominates                   |
+| delete   | delete   | delete    | Replace with latest                |
+| insert   | insert   | insert    | Replace with latest                |
+
+`(delete, update)` and `(delete, insert)` cannot occur -- the collection
+prevents operations on deleted items within the same transaction.
+
+## getActiveTransaction / Ambient Transaction Context
+
+```ts
+import { getActiveTransaction } from '@tanstack/db'
+
+const tx = getActiveTransaction() // Transaction | undefined
+```
+
+Inside `tx.mutate(() => { ... })`, the transaction is pushed onto an internal
+stack. Any `collection.insert/update/delete` call automatically joins the
+topmost ambient transaction. This is how `createOptimisticAction` and
+`createPacedMutations` wire collection operations into their transactions.
+
+## createOptimisticAction
+
+```ts
+import { createOptimisticAction } from "@tanstack/db"
+
+const action = createOptimisticAction<TVariables>({
+  // Synchronous -- apply optimistic state immediately (MUST NOT return a Promise)
+  onMutate: (variables: TVariables) => void,
+
+  // Async -- persist to backend, wait for sync back
+  mutationFn: (variables: TVariables, params: { transaction }) => Promise<any>,
+
+  // Optional: same as createTransaction config
+  id?: string,
+  autoCommit?: boolean,    // always true (commit happens after mutate)
+  metadata?: Record<string, unknown>,
+})
+
+// Returns a function: (variables: TVariables) => Transaction
+const tx = action(variables)
+await tx.isPersisted.promise
+```
+
+## createPacedMutations
+
+```ts
+import { createPacedMutations } from "@tanstack/db"
+
+const mutate = createPacedMutations<TVariables>({
+  onMutate: (variables: TVariables) => void,   // synchronous optimistic update
+  mutationFn: MutationFn,                       // persists merged transaction
+  strategy: Strategy,                            // timing control
+  metadata?: Record<string, unknown>,
+})
+
+// Returns a function: (variables: TVariables) => Transaction
+const tx = mutate(variables)
+```
+
+Rapid calls merge into the active transaction (via `applyMutations`) until the
+strategy fires the commit. A new transaction is created for subsequent calls.
+
+## Strategy Types
+
+### debounceStrategy
+
+```ts
+import { debounceStrategy } from "@tanstack/db"
+
+debounceStrategy({
+  wait: number,           // ms to wait after last call before committing
+  leading?: boolean,      // execute on the leading edge (default false)
+  trailing?: boolean,     // execute on the trailing edge (default true)
+})
+```
+
+### throttleStrategy
+
+```ts
+import { throttleStrategy } from "@tanstack/db"
+
+throttleStrategy({
+  wait: number,           // minimum ms between commits
+  leading?: boolean,      // execute on the leading edge
+  trailing?: boolean,     // execute on the trailing edge
+})
+```
+
+### queueStrategy
+
+```ts
+import { queueStrategy } from "@tanstack/db"
+
+queueStrategy({
+  wait?: number,                      // ms between processing items (default 0)
+  maxSize?: number,                   // drop items if queue exceeds this
+  addItemsTo?: "front" | "back",     // default "back" (FIFO)
+  getItemsFrom?: "front" | "back",   // default "front" (FIFO)
+})
+```
+
+Queue creates a **separate transaction per call** (unlike debounce/throttle
+which merge). Each transaction commits and awaits `isPersisted` before the next
+starts. Failed transactions do not block subsequent ones.
+
+## Transaction.isPersisted.promise
+
+```ts
+const tx = collection.insert({ id: '1', text: 'Hello' })
+
+try {
+  await tx.isPersisted.promise // resolves with the Transaction on success
+  console.log(tx.state) // "completed"
+} catch (error) {
+  console.log(tx.state) // "failed"
+  // optimistic state has been rolled back
+}
+```
+
+The promise is a `Deferred` -- it is created at transaction construction time
+and settled when `commit()` completes or `rollback()` is called. For
+`autoCommit: true` transactions, the promise settles shortly after `mutate()`
+returns (the commit runs asynchronously).

package/skills/meta-framework/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: meta-framework
+description: >
+  Integrating TanStack DB with meta-frameworks (TanStack Start, Next.js,
+  Remix, Nuxt, SvelteKit). Client-side only: SSR is NOT supported — routes
+  must disable SSR. Preloading collections in route loaders with
+  collection.preload(). Pattern: ssr: false + await collection.preload() in
+  loader. Multiple collection preloading with Promise.all. Framework-specific
+  loader APIs.
+type: composition
+library: db
+library_version: '0.5.30'
+requires:
+  - db-core
+  - db-core/collection-setup
+sources:
+  - 'TanStack/db:examples/react/todo/src/routes/electric.tsx'
+  - 'TanStack/db:examples/react/todo/src/routes/query.tsx'
+  - 'TanStack/db:examples/react/todo/src/start.tsx'
+---
+
+This skill builds on db-core. Read it first for collection setup and query builder.
+
+# TanStack DB — Meta-Framework Integration
+
+## Setup
+
+TanStack DB collections are **client-side only**. SSR is not implemented. Routes using TanStack DB **must disable SSR**. The setup pattern is:
+
+1. Set `ssr: false` on the route
+2. Call `collection.preload()` in the route loader
+3. Use `useLiveQuery` in the component
+
+## TanStack Start
+
+### Global SSR disable
+
+```ts
+// start.tsx
+import { createStart } from '@tanstack/react-start'
+
+export const startInstance = createStart(() => {
+  return {
+    defaultSsr: false,
+  }
+})
+```
+
+### Per-route SSR disable + preload
+
+```tsx
+import { createFileRoute } from '@tanstack/react-router'
+import { useLiveQuery } from '@tanstack/react-db'
+
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  loader: async () => {
+    await todoCollection.preload()
+    return null
+  },
+  component: TodoPage,
+})
+
+function TodoPage() {
+  const { data: todos } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Multiple collection preloading
+
+```tsx
+export const Route = createFileRoute('/electric')({
+  ssr: false,
+  loader: async () => {
+    await Promise.all([todoCollection.preload(), configCollection.preload()])
+    return null
+  },
+  component: ElectricPage,
+})
+```
+
+## Next.js (App Router)
+
+### Client component with preloading
+
+```tsx
+// app/todos/page.tsx
+'use client'
+
+import { useEffect, useState } from 'react'
+import { useLiveQuery } from '@tanstack/react-db'
+
+export default function TodoPage() {
+  const { data: todos, isLoading } = useLiveQuery((q) =>
+    q.from({ todo: todoCollection }),
+  )
+
+  if (isLoading) return <div>Loading...</div>
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Next.js App Router components using TanStack DB must be client components (`'use client'`). There is no server-side preloading — collections sync on mount.
+
+### With route-level preloading (experimental)
+
+```tsx
+// app/todos/page.tsx
+'use client'
+
+import { useEffect } from 'react'
+import { useLiveQuery } from '@tanstack/react-db'
+
+// Trigger preload immediately when module is loaded
+const preloadPromise = todoCollection.preload()
+
+export default function TodoPage() {
+  const { data: todos } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Remix
+
+### Client loader pattern
+
+```tsx
+// app/routes/todos.tsx
+import { useLiveQuery } from '@tanstack/react-db'
+import type { ClientLoaderFunctionArgs } from '@remix-run/react'
+
+export const clientLoader = async ({ request }: ClientLoaderFunctionArgs) => {
+  await todoCollection.preload()
+  return null
+}
+
+// Prevent server loader from running
+export const loader = () => null
+
+export default function TodoPage() {
+  const { data: todos } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+  return (
+    <ul>
+      {todos.map((t) => (
+        <li key={t.id}>{t.text}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+## Nuxt
+
+### Client-only component
+
+```vue
+<!-- pages/todos.vue -->
+<script setup lang="ts">
+import { useLiveQuery } from '@tanstack/vue-db'
+
+const { data: todos, isLoading } = useLiveQuery((q) =>
+  q.from({ todo: todoCollection }),
+)
+</script>
+
+<template>
+  <ClientOnly>
+    <div v-if="isLoading">Loading...</div>
+    <ul v-else>
+      <li v-for="todo in todos" :key="todo.id">{{ todo.text }}</li>
+    </ul>
+  </ClientOnly>
+</template>
+```
+
+Wrap TanStack DB components in `<ClientOnly>` to prevent SSR.
+
+## SvelteKit
+
+### Client-side only page
+
+```svelte
+<!-- src/routes/todos/+page.svelte -->
+<script lang="ts">
+  import { browser } from '$app/environment'
+  import { useLiveQuery } from '@tanstack/svelte-db'
+
+  const todosQuery = browser
+    ? useLiveQuery((q) => q.from({ todo: todoCollection }))
+    : null
+</script>
+
+{#if todosQuery}
+  {#each todosQuery.data as todo (todo.id)}
+    <li>{todo.text}</li>
+  {/each}
+{/if}
+```
+
+Or disable SSR for the route:
+
+```ts
+// src/routes/todos/+page.ts
+export const ssr = false
+```
+
+## Core Patterns
+
+### What preload() does
+
+`collection.preload()` starts the sync process and returns a promise that resolves when the collection reaches "ready" status. This means:
+
+1. The sync function connects to the backend
+2. Initial data is fetched and written to the collection
+3. `markReady()` is called by the adapter
+4. The promise resolves
+
+Subsequent calls to `preload()` on an already-ready collection return immediately.
+
+### Collection module pattern
+
+Define collections in a shared module, import in both loaders and components:
+
+```ts
+// lib/collections.ts
+import { createCollection, queryCollectionOptions } from '@tanstack/react-db'
+
+export const todoCollection = createCollection(
+  queryCollectionOptions({ ... })
+)
+```
+
+```tsx
+// routes/todos.tsx — loader uses the same collection instance
+import { todoCollection } from '../lib/collections'
+
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  loader: async () => {
+    await todoCollection.preload()
+    return null
+  },
+  component: () => {
+    const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+    // ...
+  },
+})
+```
+
+## Server-Side Integration
+
+This skill covers the **client-side** read path only (preloading, live queries). For server-side concerns:
+
+- **Electric proxy route** (forwarding shape requests to Electric) — see the [Electric adapter reference](../db-core/collection-setup/references/electric-adapter.md)
+- **Mutation endpoints** (`createServerFn` in TanStack Start, API routes in Next.js/Remix) — implement using your framework's server function pattern. See the Electric adapter reference for the txid handshake that mutations must return.
+
+## Common Mistakes
+
+### CRITICAL Enabling SSR with TanStack DB
+
+Wrong:
+
+```tsx
+export const Route = createFileRoute('/todos')({
+  loader: async () => {
+    await todoCollection.preload()
+    return null
+  },
+})
+```
+
+Correct:
+
+```tsx
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  loader: async () => {
+    await todoCollection.preload()
+    return null
+  },
+})
+```
+
+TanStack DB collections are client-side only. Without `ssr: false`, the route loader runs on the server where collections cannot sync, causing hangs or errors.
+
+Source: examples/react/todo/src/start.tsx
+
+### HIGH Forgetting to preload in route loader
+
+Wrong:
+
+```tsx
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  component: TodoPage,
+})
+```
+
+Correct:
+
+```tsx
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  loader: async () => {
+    await todoCollection.preload()
+    return null
+  },
+  component: TodoPage,
+})
+```
+
+Without preloading, the collection starts syncing only when the component mounts, causing a loading flash. Preloading in the route loader starts sync during navigation, making data available immediately when the component renders.
+
+### MEDIUM Creating separate collection instances
+
+Wrong:
+
+```tsx
+// routes/todos.tsx
+const todoCollection = createCollection(queryCollectionOptions({ ... }))
+
+export const Route = createFileRoute('/todos')({
+  ssr: false,
+  loader: async () => { await todoCollection.preload() },
+  component: () => {
+    const { data } = useLiveQuery((q) => q.from({ todo: todoCollection }))
+  },
+})
+```
+
+Correct:
+
+```ts
+// lib/collections.ts — single shared instance
+export const todoCollection = createCollection(queryCollectionOptions({ ... }))
+```
+
+Collections are singletons. Creating multiple instances for the same data causes duplicate syncs, wasted bandwidth, and inconsistent state between components.
+
+See also: react-db/SKILL.md, vue-db/SKILL.md, svelte-db/SKILL.md, solid-db/SKILL.md, angular-db/SKILL.md — for framework-specific hook usage.
+
+See also: db-core/collection-setup/SKILL.md — for collection creation and adapter selection.