@tanstack/db 0.5.29 → 0.5.31

package/skills/db-core/collection-setup/references/local-adapters.md

@@ -0,0 +1,220 @@
+# Local Adapters Reference
+
+Both adapters are included in the core package.
+
+## Install
+
+```bash
+pnpm add @tanstack/react-db
+```
+
+---
+
+## localOnlyCollectionOptions
+
+In-memory only. No persistence. No cross-tab sync.
+
+### Required Config
+
+```typescript
+import {
+  createCollection,
+  localOnlyCollectionOptions,
+} from '@tanstack/react-db'
+
+const collection = createCollection(
+  localOnlyCollectionOptions({
+    id: 'ui-state',
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+- `id` -- unique collection identifier
+- `getKey` -- extracts unique key from each item
+
+### Optional Config
+
+| Option        | Default | Description                            |
+| ------------- | ------- | -------------------------------------- |
+| `schema`      | (none)  | StandardSchema validator               |
+| `initialData` | (none)  | Array of items to populate on creation |
+| `onInsert`    | (none)  | Handler before confirming inserts      |
+| `onUpdate`    | (none)  | Handler before confirming updates      |
+| `onDelete`    | (none)  | Handler before confirming deletes      |
+
+### Direct Mutations
+
+```typescript
+collection.insert({ id: 'theme', mode: 'dark' })
+collection.update('theme', (draft) => {
+  draft.mode = 'light'
+})
+collection.delete('theme')
+```
+
+### initialData
+
+```typescript
+localOnlyCollectionOptions({
+  id: 'ui-state',
+  getKey: (item) => item.id,
+  initialData: [
+    { id: 'sidebar', isOpen: false },
+    { id: 'theme', mode: 'light' },
+  ],
+})
+```
+
+### acceptMutations in Manual Transactions
+
+When using `createTransaction`, call `collection.utils.acceptMutations(transaction)` in `mutationFn`:
+
+```typescript
+import { createTransaction } from '@tanstack/react-db'
+
+const tx = createTransaction({
+  mutationFn: async ({ transaction }) => {
+    // Handle server mutations first, then:
+    localData.utils.acceptMutations(transaction)
+  },
+})
+tx.mutate(() => {
+  localData.insert({ id: 'draft-1', data: '...' })
+})
+await tx.commit()
+```
+
+---
+
+## localStorageCollectionOptions
+
+Persists to `localStorage`. Cross-tab sync via storage events. Survives reloads.
+
+### Required Config
+
+```typescript
+import {
+  createCollection,
+  localStorageCollectionOptions,
+} from '@tanstack/react-db'
+
+const collection = createCollection(
+  localStorageCollectionOptions({
+    id: 'user-preferences',
+    storageKey: 'app-user-prefs',
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+- `id` -- unique collection identifier
+- `storageKey` -- localStorage key for all collection data
+- `getKey` -- extracts unique key from each item
+
+### Optional Config
+
+| Option            | Default        | Description                                                          |
+| ----------------- | -------------- | -------------------------------------------------------------------- |
+| `schema`          | (none)         | StandardSchema validator                                             |
+| `storage`         | `localStorage` | Custom storage (`sessionStorage` or any localStorage-compatible API) |
+| `storageEventApi` | `window`       | Event API for cross-tab sync                                         |
+| `onInsert`        | (none)         | Handler on insert                                                    |
+| `onUpdate`        | (none)         | Handler on update                                                    |
+| `onDelete`        | (none)         | Handler on delete                                                    |
+
+### Using sessionStorage
+
+```typescript
+localStorageCollectionOptions({
+  id: 'session-data',
+  storageKey: 'session-key',
+  storage: sessionStorage,
+  getKey: (item) => item.id,
+})
+```
+
+### Custom Storage Backend
+
+Provide any object with `getItem`, `setItem`, `removeItem`:
+
+```typescript
+const encryptedStorage = {
+  getItem: (key) => {
+    const v = localStorage.getItem(key)
+    return v ? decrypt(v) : null
+  },
+  setItem: (key, value) => localStorage.setItem(key, encrypt(value)),
+  removeItem: (key) => localStorage.removeItem(key),
+}
+localStorageCollectionOptions({
+  id: 'secure',
+  storageKey: 'enc-key',
+  storage: encryptedStorage,
+  getKey: (i) => i.id,
+})
+```
+
+### acceptMutations
+
+Same as LocalOnly -- call `collection.utils.acceptMutations(transaction)` in manual transactions.
+
+---
+
+## Comparison
+
+| Feature         | LocalOnly        | LocalStorage |
+| --------------- | ---------------- | ------------ |
+| Persistence     | None (in-memory) | localStorage |
+| Cross-tab sync  | No               | Yes          |
+| Survives reload | No               | Yes          |
+| Performance     | Fastest          | Fast         |
+| Size limits     | Memory           | ~5-10MB      |
+
+## Complete Example
+
+```typescript
+import {
+  createCollection,
+  localOnlyCollectionOptions,
+  localStorageCollectionOptions,
+} from '@tanstack/react-db'
+import { z } from 'zod'
+
+// In-memory UI state
+const modalState = createCollection(
+  localOnlyCollectionOptions({
+    id: 'modal-state',
+    getKey: (item) => item.id,
+    initialData: [
+      { id: 'confirm-delete', isOpen: false },
+      { id: 'settings', isOpen: false },
+    ],
+  }),
+)
+
+// Persistent user prefs
+const userPrefs = createCollection(
+  localStorageCollectionOptions({
+    id: 'user-preferences',
+    storageKey: 'app-user-prefs',
+    getKey: (item) => item.id,
+    schema: z.object({
+      id: z.string(),
+      theme: z.enum(['light', 'dark', 'auto']),
+      language: z.string(),
+      notifications: z.boolean(),
+    }),
+  }),
+)
+
+modalState.update('settings', (draft) => {
+  draft.isOpen = true
+})
+userPrefs.insert({
+  id: 'current-user',
+  theme: 'dark',
+  language: 'en',
+  notifications: true,
+})
+```

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

@@ -0,0 +1,241 @@
+# PowerSync Adapter Reference
+
+## Install
+
+```bash
+pnpm add @tanstack/powersync-db-collection @powersync/web @journeyapps/wa-sqlite
+```
+
+## Required Config
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { powerSyncCollectionOptions } from '@tanstack/powersync-db-collection'
+import { Schema, Table, column, PowerSyncDatabase } from '@powersync/web'
+
+const APP_SCHEMA = new Schema({
+  documents: new Table({
+    name: column.text,
+    author: column.text,
+    created_at: column.text,
+    archived: column.integer,
+  }),
+})
+
+const db = new PowerSyncDatabase({
+  database: { dbFilename: 'app.sqlite' },
+  schema: APP_SCHEMA,
+})
+
+const documentsCollection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.documents,
+  }),
+)
+```
+
+- `database` -- `PowerSyncDatabase` instance
+- `table` -- PowerSync `Table` from schema (provides `getKey` and type inference)
+
+## Optional Config (with defaults)
+
+| Option                   | Default | Description                                                                           |
+| ------------------------ | ------- | ------------------------------------------------------------------------------------- |
+| `schema`                 | (none)  | StandardSchema for mutation validation                                                |
+| `deserializationSchema`  | (none)  | Transforms SQLite types to output types; required when input types differ from SQLite |
+| `onDeserializationError` | (none)  | Fatal error handler; **required** when using `schema` or `deserializationSchema`      |
+| `serializer`             | (none)  | Per-field functions to serialize output types back to SQLite                          |
+| `syncBatchSize`          | `1000`  | Batch size for initial sync                                                           |
+
+### SQLite Type Mapping
+
+| PowerSync Column | TypeScript Type  |
+| ---------------- | ---------------- |
+| `column.text`    | `string \| null` |
+| `column.integer` | `number \| null` |
+| `column.real`    | `number \| null` |
+
+All columns nullable by default. `id: string` is always included automatically.
+
+## Conversions (4 patterns)
+
+### 1. Type Inference Only (no schema)
+
+```typescript
+const collection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.documents,
+  }),
+)
+// Input/Output: { id: string, name: string | null, created_at: string | null, ... }
+```
+
+### 2. Schema Validation (same SQLite types)
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  name: z.string().min(3),
+  author: z.string(),
+  created_at: z.string(),
+  archived: z.number(),
+})
+const collection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.documents,
+    schema,
+    onDeserializationError: (error) => {
+      /* fatal */
+    },
+  }),
+)
+```
+
+### 3. Transform SQLite to Rich Output Types
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  created_at: z
+    .string()
+    .nullable()
+    .transform((val) => (val ? new Date(val) : null)),
+  archived: z
+    .number()
+    .nullable()
+    .transform((val) => (val != null ? val > 0 : null)),
+})
+const collection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.documents,
+    schema,
+    onDeserializationError: (error) => {
+      /* fatal */
+    },
+    serializer: { created_at: (value) => (value ? value.toISOString() : null) },
+  }),
+)
+// Input:  { created_at: string | null, ... }
+// Output: { created_at: Date | null, archived: boolean | null, ... }
+```
+
+### 4. Custom Input + Output with deserializationSchema
+
+```typescript
+const schema = z.object({
+  id: z.string(),
+  name: z.string(),
+  created_at: z.date(),
+  archived: z.boolean(),
+})
+const deserializationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  created_at: z.string().transform((val) => new Date(val)),
+  archived: z.number().transform((val) => val > 0),
+})
+const collection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.documents,
+    schema,
+    deserializationSchema,
+    onDeserializationError: (error) => {
+      /* fatal */
+    },
+  }),
+)
+// Input:  { created_at: Date, archived: boolean }
+// Output: { created_at: Date, archived: boolean }
+```
+
+## Metadata Tracking
+
+Enable on the table, then pass metadata with operations:
+
+```typescript
+const APP_SCHEMA = new Schema({
+  documents: new Table({ name: column.text }, { trackMetadata: true }),
+})
+
+await collection.insert(
+  { id: crypto.randomUUID(), name: 'Report' },
+  { metadata: { source: 'web-app', userId: 'user-123' } },
+).isPersisted.promise
+```
+
+Metadata appears as `entry.metadata` (stringified JSON) in PowerSync `CrudEntry`.
+
+## Advanced Transactions
+
+```typescript
+import { createTransaction } from '@tanstack/react-db'
+import { PowerSyncTransactor } from '@tanstack/powersync-db-collection'
+
+const tx = createTransaction({
+  autoCommit: false,
+  mutationFn: async ({ transaction }) => {
+    await new PowerSyncTransactor({ database: db }).applyTransaction(
+      transaction,
+    )
+  },
+})
+tx.mutate(() => {
+  documentsCollection.insert({
+    id: crypto.randomUUID(),
+    name: 'Doc 1',
+    created_at: new Date().toISOString(),
+  })
+})
+await tx.commit()
+await tx.isPersisted.promise
+```
+
+## Complete Example
+
+```typescript
+import { Schema, Table, column, PowerSyncDatabase } from '@powersync/web'
+import { createCollection } from '@tanstack/react-db'
+import { powerSyncCollectionOptions } from '@tanstack/powersync-db-collection'
+import { z } from 'zod'
+
+const APP_SCHEMA = new Schema({
+  tasks: new Table({
+    title: column.text,
+    due_date: column.text,
+    completed: column.integer,
+  }),
+})
+const db = new PowerSyncDatabase({
+  database: { dbFilename: 'app.sqlite' },
+  schema: APP_SCHEMA,
+})
+
+const taskSchema = z.object({
+  id: z.string(),
+  title: z.string().nullable(),
+  due_date: z
+    .string()
+    .nullable()
+    .transform((val) => (val ? new Date(val) : null)),
+  completed: z
+    .number()
+    .nullable()
+    .transform((val) => (val != null ? val > 0 : null)),
+})
+
+const tasksCollection = createCollection(
+  powerSyncCollectionOptions({
+    database: db,
+    table: APP_SCHEMA.props.tasks,
+    schema: taskSchema,
+    onDeserializationError: (error) => console.error('Fatal:', error),
+    syncBatchSize: 500,
+  }),
+)
+```

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