@tanstack/db 0.5.30 → 0.5.31

package/skills/db-core/collection-setup/references/query-adapter.md

@@ -0,0 +1,183 @@
+# Query Adapter Reference
+
+## Install
+
+```bash
+pnpm add @tanstack/query-db-collection @tanstack/query-core @tanstack/db
+```
+
+## Required Config
+
+```typescript
+import { QueryClient } from '@tanstack/query-core'
+import { createCollection } from '@tanstack/db'
+import { queryCollectionOptions } from '@tanstack/query-db-collection'
+
+const queryClient = new QueryClient()
+const collection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => fetch('/api/todos').then((r) => r.json()),
+    queryClient,
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+- `queryKey` -- TanStack Query cache key
+- `queryFn` -- fetches data; must be provided (throws `QueryFnRequiredError` if missing)
+- `queryClient` -- `QueryClient` instance
+- `getKey` -- extracts unique key from each item
+
+## Optional Config (with defaults)
+
+| Option            | Default      | Description                                     |
+| ----------------- | ------------ | ----------------------------------------------- |
+| `id`              | (none)       | Unique collection identifier                    |
+| `schema`          | (none)       | StandardSchema validator                        |
+| `select`          | (none)       | Extracts array items when wrapped with metadata |
+| `enabled`         | `true`       | Whether query runs automatically                |
+| `refetchInterval` | `0`          | Polling interval in ms; 0 = disabled            |
+| `retry`           | (TQ default) | Retry config for failed queries                 |
+| `retryDelay`      | (TQ default) | Delay between retries                           |
+| `staleTime`       | (TQ default) | How long data is considered fresh               |
+| `meta`            | (none)       | Metadata passed to queryFn context              |
+| `startSync`       | `true`       | Start syncing immediately                       |
+| `syncMode`        | (none)       | Set `"on-demand"` for predicate push-down       |
+
+### Persistence Handlers
+
+```typescript
+onInsert: async ({ transaction }) => {
+  await api.createTodos(transaction.mutations.map((m) => m.modified))
+  // return nothing or { refetch: true } to trigger refetch
+  // return { refetch: false } to skip refetch
+},
+onUpdate: async ({ transaction }) => {
+  await api.updateTodos(transaction.mutations.map((m) => ({ id: m.key, changes: m.changes })))
+},
+onDelete: async ({ transaction }) => {
+  await api.deleteTodos(transaction.mutations.map((m) => m.key))
+},
+```
+
+## Utility Methods (`collection.utils`)
+
+- `refetch(opts?)` -- manual refetch; `opts.throwOnError` (default `false`); bypasses `enabled: false`
+- `writeInsert(data)` -- insert directly to synced store (bypasses optimistic system)
+- `writeUpdate(data)` -- update directly in synced store
+- `writeDelete(keys)` -- delete directly from synced store
+- `writeUpsert(data)` -- insert or update directly
+- `writeBatch(callback)` -- multiple write ops atomically
+
+Direct writes bypass optimistic updates, do NOT trigger refetches, and update TQ cache immediately.
+
+```typescript
+collection.utils.writeBatch(() => {
+  collection.utils.writeInsert({ id: '1', text: 'Buy milk' })
+  collection.utils.writeUpdate({ id: '2', completed: true })
+  collection.utils.writeDelete('3')
+})
+```
+
+## Predicate Push-Down (syncMode: "on-demand")
+
+Query predicates (where, orderBy, limit, offset) passed to `queryFn` via `ctx.meta.loadSubsetOptions`.
+
+```typescript
+import { parseLoadSubsetOptions } from '@tanstack/query-db-collection'
+
+queryFn: async (ctx) => {
+  const { filters, sorts, limit, offset } = parseLoadSubsetOptions(
+    ctx.meta?.loadSubsetOptions,
+  )
+  // filters: [{ field: ['category'], operator: 'eq', value: 'electronics' }]
+  // sorts: [{ field: ['price'], direction: 'asc', nulls: 'last' }]
+}
+```
+
+### Expression Helpers (from `@tanstack/db`)
+
+- `parseLoadSubsetOptions(opts)` -- returns `{ filters, sorts, limit, offset }`
+- `parseWhereExpression(expr, { handlers })` -- custom handlers per operator
+- `parseOrderByExpression(expr)` -- returns `[{ field, direction, nulls }]`
+- `extractSimpleComparisons(expr)` -- flat AND-ed comparisons only
+
+Supported operators: `eq`, `gt`, `gte`, `lt`, `lte`, `and`, `or`, `in`
+
+## Dynamic queryKey
+
+```typescript
+queryKey: (opts) => {
+  const parsed = parseLoadSubsetOptions(opts)
+  const key = ["products"]
+  parsed.filters.forEach((f) => key.push(`${f.field.join(".")}-${f.operator}-${f.value}`))
+  if (parsed.limit) key.push(`limit-${parsed.limit}`)
+  return key
+},
+```
+
+## Complete Example
+
+```typescript
+import { QueryClient } from '@tanstack/query-core'
+import { createCollection } from '@tanstack/react-db'
+import {
+  queryCollectionOptions,
+  parseLoadSubsetOptions,
+} from '@tanstack/query-db-collection'
+
+const queryClient = new QueryClient()
+
+const productsCollection = createCollection(
+  queryCollectionOptions({
+    id: 'products',
+    queryKey: ['products'],
+    queryClient,
+    getKey: (item) => item.id,
+    syncMode: 'on-demand',
+    queryFn: async (ctx) => {
+      const { filters, sorts, limit } = parseLoadSubsetOptions(
+        ctx.meta?.loadSubsetOptions,
+      )
+      const params = new URLSearchParams()
+      filters.forEach(({ field, operator, value }) => {
+        params.set(`${field.join('.')}_${operator}`, String(value))
+      })
+      if (sorts.length > 0) {
+        params.set(
+          'sort',
+          sorts.map((s) => `${s.field.join('.')}:${s.direction}`).join(','),
+        )
+      }
+      if (limit) params.set('limit', String(limit))
+      return fetch(`/api/products?${params}`).then((r) => r.json())
+    },
+    onInsert: async ({ transaction }) => {
+      const serverItems = await api.createProducts(
+        transaction.mutations.map((m) => m.modified),
+      )
+      productsCollection.utils.writeBatch(() => {
+        serverItems.forEach((item) =>
+          productsCollection.utils.writeInsert(item),
+        )
+      })
+      return { refetch: false }
+    },
+    onUpdate: async ({ transaction }) => {
+      await api.updateProducts(
+        transaction.mutations.map((m) => ({ id: m.key, changes: m.changes })),
+      )
+    },
+    onDelete: async ({ transaction }) => {
+      await api.deleteProducts(transaction.mutations.map((m) => m.key))
+    },
+  }),
+)
+```
+
+## Key Behaviors
+
+- `queryFn` result is treated as **complete state** -- missing items are deleted
+- Empty array from `queryFn` deletes all items
+- Direct writes update TQ cache but are overridden by subsequent `queryFn` results

package/skills/db-core/collection-setup/references/rxdb-adapter.md

@@ -0,0 +1,152 @@
+# RxDB Adapter Reference
+
+## Install
+
+```bash
+pnpm add @tanstack/rxdb-db-collection rxdb @tanstack/react-db
+```
+
+## Required Config
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { rxdbCollectionOptions } from '@tanstack/rxdb-db-collection'
+
+const todosCollection = createCollection(
+  rxdbCollectionOptions({
+    rxCollection: db.todos,
+  }),
+)
+```
+
+- `rxCollection` -- the underlying RxDB `RxCollection` instance
+
+## Optional Config (with defaults)
+
+| Option          | Default                 | Description                                                                                        |
+| --------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `id`            | (none)                  | Unique collection identifier                                                                       |
+| `schema`        | (none)                  | StandardSchema validator (RxDB has its own validation; this adds TanStack DB-side validation)      |
+| `startSync`     | `true`                  | Start ingesting RxDB data immediately                                                              |
+| `syncBatchSize` | `1000`                  | Max documents per batch during initial sync from RxDB; only affects initial load, not live updates |
+| `onInsert`      | (default: `bulkUpsert`) | Override default insert persistence                                                                |
+| `onUpdate`      | (default: `patch`)      | Override default update persistence                                                                |
+| `onDelete`      | (default: `bulkRemove`) | Override default delete persistence                                                                |
+
+## Key Behavior: String Keys
+
+RxDB primary keys are always strings. The `getKey` function is derived from the RxDB schema's `primaryKey` field automatically. All key values will be strings.
+
+## RxDB Setup (prerequisite)
+
+```typescript
+import { createRxDatabase } from 'rxdb/plugins/core'
+import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'
+
+const db = await createRxDatabase({
+  name: 'my-app',
+  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'],
+    },
+  },
+})
+```
+
+## Backend Sync (optional, RxDB-managed)
+
+Replication is configured directly on the RxDB collection, independent of TanStack DB. Changes from replication flow into the TanStack DB collection via RxDB's change stream automatically.
+
+```typescript
+import { replicateRxCollection } from 'rxdb/plugins/replication'
+
+const replicationState = replicateRxCollection({
+  collection: db.todos,
+  pull: { handler: myPullHandler },
+  push: { handler: myPushHandler },
+})
+```
+
+## Data Flow
+
+- Writes via `todosCollection.insert/update/delete` persist to RxDB
+- Direct RxDB writes (or replication changes) flow into the TanStack collection via change streams
+- Initial sync loads data in batches of `syncBatchSize`
+- Ongoing updates stream one by one via RxDB's change feed
+
+## Indexes
+
+RxDB schema indexes do not affect TanStack DB query performance (queries run in-memory). Indexes may still matter if you query RxDB directly, use filtered replication, or selectively load subsets.
+
+## Complete Example
+
+```typescript
+import { createRxDatabase } from 'rxdb/plugins/core'
+import { getRxStorageLocalstorage } from 'rxdb/plugins/storage-localstorage'
+import { createCollection } from '@tanstack/react-db'
+import { rxdbCollectionOptions } from '@tanstack/rxdb-db-collection'
+import { z } from 'zod'
+
+type Todo = { id: string; text: string; completed: boolean }
+
+const db = await createRxDatabase({
+  name: 'my-todos',
+  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'],
+    },
+  },
+})
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string().min(1),
+  completed: z.boolean(),
+})
+
+const todosCollection = createCollection(
+  rxdbCollectionOptions({
+    rxCollection: db.todos,
+    schema: todoSchema,
+    startSync: true,
+    syncBatchSize: 500,
+  }),
+)
+
+// Usage
+todosCollection.insert({
+  id: crypto.randomUUID(),
+  text: 'Buy milk',
+  completed: false,
+})
+todosCollection.update('some-id', (draft) => {
+  draft.completed = true
+})
+todosCollection.delete('some-id')
+```

package/skills/db-core/collection-setup/references/schema-patterns.md

@@ -0,0 +1,215 @@
+# Schema Patterns Reference
+
+## StandardSchema Integration
+
+TanStack DB accepts any [StandardSchema](https://standardschema.dev)-compatible library via the `schema` option.
+
+### Supported Libraries
+
+- [Zod](https://zod.dev), [Valibot](https://valibot.dev), [ArkType](https://arktype.io), [Effect Schema](https://effect.website/docs/schema/introduction/)
+
+## TInput vs TOutput
+
+- **TInput** -- type accepted by `insert()` and `update()`
+- **TOutput** -- type stored in collection and returned from queries
+
+When no transforms exist, TInput === TOutput.
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  created_at: z.string().transform((val) => new Date(val)),
+})
+// TInput:  { id: string, created_at: string }
+// TOutput: { id: string, created_at: Date }
+```
+
+## Union Pattern for Transforms (Required)
+
+When a schema transforms A to B, TInput **must** accept both A and B. During `update()`, the draft contains TOutput data.
+
+```typescript
+// WRONG -- update() fails because draft.created_at is Date but schema expects string
+z.string().transform((val) => new Date(val))
+
+// CORRECT
+z.union([z.string(), z.date()]).transform((val) =>
+  typeof val === 'string' ? new Date(val) : val,
+)
+// TInput: string | Date, TOutput: Date
+```
+
+## Defaults
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  text: z.string(),
+  completed: z.boolean().default(false),
+  priority: z.number().default(0),
+  tags: z.array(z.string()).default([]),
+  created_at: z.date().default(() => new Date()),
+})
+// insert({ id: "1", text: "Task" }) -- missing fields auto-filled
+```
+
+## Computed Fields
+
+```typescript
+const schema = z
+  .object({
+    id: z.string(),
+    first_name: z.string(),
+    last_name: z.string(),
+  })
+  .transform((data) => ({
+    ...data,
+    full_name: `${data.first_name} ${data.last_name}`,
+  }))
+```
+
+## Combining Defaults with Transforms
+
+```typescript
+const schema = z.object({
+  created_at: z
+    .string()
+    .default(() => new Date().toISOString())
+    .transform((val) => new Date(val)),
+})
+```
+
+## Validation Examples
+
+```typescript
+// Basic constraints
+z.string().min(3).max(100)
+z.string().email()
+z.number().int().positive()
+z.enum(['active', 'inactive'])
+z.array(z.string()).min(1)
+
+// Optional/nullable
+z.string().optional() // can be omitted
+z.string().nullable() // can be null
+
+// Cross-field
+z.object({ start: z.string(), end: z.string() }).refine(
+  (d) => new Date(d.end) > new Date(d.start),
+  'End must be after start',
+)
+
+// Custom
+z.string().refine((v) => /^[a-zA-Z0-9_]+$/.test(v), 'Alphanumeric only')
+```
+
+## SchemaValidationError
+
+```typescript
+import { SchemaValidationError } from '@tanstack/db'
+
+try {
+  collection.insert({ id: '1', email: 'bad', age: -5 })
+} catch (error) {
+  if (error instanceof SchemaValidationError) {
+    error.type // "insert" or "update"
+    error.message // "Validation failed with 2 issues"
+    error.issues // [{ path: ["email"], message: "Invalid email" }, ...]
+  }
+}
+```
+
+## Scope: Schema vs Sync — Two Separate Paths
+
+**Schemas validate client mutations only** (`insert()`, `update()`). Synced data from backends (Electric, PowerSync, etc.) bypasses the schema entirely.
+
+This means for types that need transformation (e.g., `timestamptz`):
+
+- **Sync path**: handled by the adapter's parser (e.g., Electric's `shapeOptions.parser`)
+- **Mutation path**: handled by the Zod schema
+
+You need BOTH configured for full type safety. See electric-adapter.md for the dual-path pattern.
+
+### Simpler date coercion (Zod-specific)
+
+With Zod, `z.coerce.date()` is simpler than the `z.union([z.string(), z.date()]).transform(...)` pattern:
+
+```typescript
+// Zod-specific: z.coerce.date() accepts string, number, or Date as input
+const schema = z.object({
+  created_at: z.coerce.date(),
+})
+// TInput: { created_at: string | number | Date }  (coerce accepts many types)
+// TOutput: { created_at: Date }
+```
+
+This satisfies the TInput-superset-of-TOutput requirement automatically. Other StandardSchema libraries have their own coercion patterns — consult library docs.
+
+### Important
+
+- Validation is synchronous, runs on every mutation
+- Keep transforms simple for performance
+
+## Where TOutput Appears
+
+- Data stored in collection and returned from queries
+- `PendingMutation.modified`
+- Mutation handler `transaction.mutations[].modified`
+
+## Performance
+
+Keep transforms simple -- validation runs synchronously on every mutation.
+
+## Complete Example
+
+```typescript
+import { z } from 'zod'
+import { createCollection, SchemaValidationError } from '@tanstack/react-db'
+import { queryCollectionOptions } from '@tanstack/query-db-collection'
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string().min(1, 'Text is required'),
+  completed: z.boolean().default(false),
+  priority: z.enum(['low', 'medium', 'high']).default('medium'),
+  created_at: z
+    .union([z.string(), z.date()])
+    .transform((val) => (typeof val === 'string' ? new Date(val) : val))
+    .default(() => new Date()),
+})
+
+const todosCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: async () => fetch('/api/todos').then((r) => r.json()),
+    queryClient,
+    getKey: (item) => item.id,
+    schema: todoSchema,
+    onInsert: async ({ transaction }) => {
+      const todo = transaction.mutations[0].modified
+      await api.todos.create({
+        ...todo,
+        created_at: todo.created_at.toISOString(),
+      })
+    },
+  }),
+)
+
+// Defaults and transforms applied
+todosCollection.insert({ id: '1', text: 'Buy groceries' })
+// => { id: "1", text: "Buy groceries", completed: false, priority: "medium", created_at: Date }
+
+// Update works -- draft contains TOutput, schema accepts via union
+todosCollection.update('1', (draft) => {
+  draft.completed = true
+})
+
+// Error handling
+try {
+  todosCollection.insert({ id: '2', text: '' })
+} catch (e) {
+  if (e instanceof SchemaValidationError) {
+    console.log(e.issues) // [{ path: ["text"], message: "Text is required" }]
+  }
+}
+```

package/skills/db-core/collection-setup/references/trailbase-adapter.md

@@ -0,0 +1,147 @@
+# TrailBase Adapter Reference
+
+## Install
+
+```bash
+pnpm add @tanstack/trailbase-db-collection @tanstack/react-db trailbase
+```
+
+## Required Config
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { trailBaseCollectionOptions } from '@tanstack/trailbase-db-collection'
+import { initClient } from 'trailbase'
+
+const trailBaseClient = initClient('https://your-trailbase-instance.com')
+
+const todosCollection = createCollection(
+  trailBaseCollectionOptions({
+    id: 'todos',
+    recordApi: trailBaseClient.records('todos'),
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+- `id` -- unique collection identifier
+- `recordApi` -- TrailBase Record API instance from `trailBaseClient.records(tableName)`
+- `getKey` -- extracts unique key from each item
+
+## Optional Config
+
+| Option      | Default | Description                                                                       |
+| ----------- | ------- | --------------------------------------------------------------------------------- |
+| `schema`    | (none)  | StandardSchema validator                                                          |
+| `parse`     | (none)  | Object mapping field names to functions that transform data coming FROM TrailBase |
+| `serialize` | (none)  | Object mapping field names to functions that transform data going TO TrailBase    |
+| `onInsert`  | (none)  | Handler called on insert                                                          |
+| `onUpdate`  | (none)  | Handler called on update                                                          |
+| `onDelete`  | (none)  | Handler called on delete                                                          |
+
+## Conversions (parse/serialize)
+
+TrailBase uses different data formats (e.g. Unix timestamps). Use `parse` and `serialize` for field-level transformations.
+
+```typescript
+type SelectTodo = {
+  id: string
+  text: string
+  created_at: number // Unix timestamp from TrailBase
+  completed: boolean
+}
+
+type Todo = {
+  id: string
+  text: string
+  created_at: Date // Rich JS type for app usage
+  completed: boolean
+}
+
+const collection = createCollection<SelectTodo, Todo>(
+  trailBaseCollectionOptions({
+    id: 'todos',
+    recordApi: trailBaseClient.records('todos'),
+    getKey: (item) => item.id,
+    parse: {
+      created_at: (ts) => new Date(ts * 1000),
+    },
+    serialize: {
+      created_at: (date) => Math.floor(date.valueOf() / 1000),
+    },
+  }),
+)
+```
+
+## Real-time Subscriptions
+
+Automatic when `enable_subscriptions` is enabled on the TrailBase server. No additional client config needed -- the collection subscribes to changes automatically.
+
+## Persistence Handlers
+
+```typescript
+onInsert: async ({ transaction }) => {
+  const newItem = transaction.mutations[0].modified
+},
+onUpdate: async ({ transaction }) => {
+  const { original, modified } = transaction.mutations[0]
+},
+onDelete: async ({ transaction }) => {
+  const deletedItem = transaction.mutations[0].original
+},
+```
+
+TrailBase handles persistence through the Record API automatically. Custom handlers are for additional logic only.
+
+## Complete Example
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { trailBaseCollectionOptions } from '@tanstack/trailbase-db-collection'
+import { initClient } from 'trailbase'
+import { z } from 'zod'
+
+const trailBaseClient = initClient('https://your-trailbase-instance.com')
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string(),
+  completed: z.boolean(),
+  created_at: z.date(),
+})
+
+type SelectTodo = {
+  id: string
+  text: string
+  completed: boolean
+  created_at: number
+}
+
+type Todo = z.infer<typeof todoSchema>
+
+const todosCollection = createCollection<SelectTodo, Todo>(
+  trailBaseCollectionOptions({
+    id: 'todos',
+    recordApi: trailBaseClient.records('todos'),
+    getKey: (item) => item.id,
+    schema: todoSchema,
+    parse: {
+      created_at: (ts) => new Date(ts * 1000),
+    },
+    serialize: {
+      created_at: (date) => Math.floor(date.valueOf() / 1000),
+    },
+    onInsert: async ({ transaction }) => {
+      console.log('Created:', transaction.mutations[0].modified)
+    },
+  }),
+)
+
+// Usage
+todosCollection.insert({
+  id: crypto.randomUUID(),
+  text: 'Review PR',
+  completed: false,
+  created_at: new Date(),
+})
+```