@tanstack/db 0.5.30 → 0.5.31

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

@@ -0,0 +1,238 @@
+# Electric Adapter Reference
+
+## Install
+
+```bash
+pnpm add @tanstack/electric-db-collection @tanstack/react-db
+```
+
+## Required Config
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { electricCollectionOptions } from '@tanstack/electric-db-collection'
+
+const collection = createCollection(
+  electricCollectionOptions({
+    shapeOptions: { url: '/api/todos' },
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+- `shapeOptions` -- ElectricSQL ShapeStream config; `url` is the proxy URL to Electric
+- `getKey` -- extracts unique key from each item
+
+## Optional Config
+
+| Option                | Default | Description                                         |
+| --------------------- | ------- | --------------------------------------------------- |
+| `id`                  | (none)  | Unique collection identifier                        |
+| `schema`              | (none)  | StandardSchema validator                            |
+| `shapeOptions.params` | (none)  | Additional shape params (e.g. `{ table: 'todos' }`) |
+| `onInsert`            | (none)  | Persistence handler; should return `{ txid }`       |
+| `onUpdate`            | (none)  | Persistence handler; should return `{ txid }`       |
+| `onDelete`            | (none)  | Persistence handler; should return `{ txid }`       |
+
+## Three Sync Strategies
+
+### 1. Txid Return (Recommended)
+
+Handler returns `{ txid }`. Client waits for that txid in the Electric stream.
+
+```typescript
+onInsert: async ({ transaction }) => {
+  const response = await api.todos.create(transaction.mutations[0].modified)
+  return { txid: response.txid }
+},
+```
+
+### 2. awaitMatch (Custom Match)
+
+Use when txids are unavailable. Import `isChangeMessage` to match on message content.
+
+```typescript
+import { isChangeMessage } from "@tanstack/electric-db-collection"
+
+onInsert: async ({ transaction, collection }) => {
+  const newItem = transaction.mutations[0].modified
+  await api.todos.create(newItem)
+  await collection.utils.awaitMatch(
+    (message) =>
+      isChangeMessage(message) &&
+      message.headers.operation === "insert" &&
+      message.value.text === newItem.text,
+    5000 // timeout ms, defaults to 3000
+  )
+},
+```
+
+### 3. Simple Timeout (Prototyping)
+
+```typescript
+onInsert: async ({ transaction }) => {
+  await api.todos.create(transaction.mutations[0].modified)
+  await new Promise((resolve) => setTimeout(resolve, 2000))
+},
+```
+
+## Utility Methods (`collection.utils`)
+
+- `awaitTxId(txid, timeout?)` -- wait for txid in Electric stream; default timeout 30s
+- `awaitMatch(matchFn, timeout?)` -- wait for message matching predicate; default timeout 3000ms
+
+### Helper Exports
+
+```typescript
+import {
+  isChangeMessage,
+  isControlMessage,
+} from '@tanstack/electric-db-collection'
+// isChangeMessage(msg) -- true for insert/update/delete
+// isControlMessage(msg) -- true for up-to-date/must-refetch
+```
+
+## generateTxId Backend Pattern
+
+The txid **must** be queried inside the same Postgres transaction as the mutation.
+
+```typescript
+async function generateTxId(tx: any): Promise<number> {
+  const result = await tx`SELECT pg_current_xact_id()::xid::text as txid`
+  const txid = result[0]?.txid
+  if (txid === undefined) throw new Error('Failed to get transaction ID')
+  return parseInt(txid, 10)
+}
+
+async function createTodo(data) {
+  let txid!: number
+  const result = await sql.begin(async (tx) => {
+    txid = await generateTxId(tx) // INSIDE the transaction
+    const [todo] = await tx`INSERT INTO todos ${tx(data)} RETURNING *`
+    return todo
+  })
+  return { todo: result, txid }
+}
+```
+
+Querying txid outside the transaction produces a mismatched txid -- `awaitTxId` stalls indefinitely.
+
+## Schema vs Parser: Two Separate Paths
+
+When using Electric with a schema, data enters the collection via **two independent paths**:
+
+1. **Sync path** — Electric's `ShapeStream` applies the `parser` from `shapeOptions`. The schema is NOT applied to synced data.
+2. **Mutation path** — `insert()` and `update()` run through the collection schema. The parser is not involved.
+
+For types that need transformation (e.g., `timestamptz`), you need BOTH configured:
+
+```typescript
+const todosCollection = createCollection(
+  electricCollectionOptions({
+    schema: z.object({
+      id: z.string(),
+      text: z.string(),
+      completed: z.boolean(), // Electric auto-parses bools
+      created_at: z.coerce.date(), // mutation path: coerce string → Date
+    }),
+    shapeOptions: {
+      url: '/api/todos',
+      parser: {
+        timestamptz: (value: string) => new Date(value), // sync path: parse incoming strings
+      },
+    },
+    getKey: (item) => item.id,
+  }),
+)
+```
+
+### Postgres → Electric type handling
+
+| PG type        | Electric auto-parses? | Schema needed?    | Parser needed?                                      |
+| -------------- | --------------------- | ----------------- | --------------------------------------------------- |
+| `text`, `uuid` | Yes (string)          | `z.string()`      | No                                                  |
+| `int4`, `int8` | Yes (number)          | `z.number()`      | No                                                  |
+| `bool`         | Yes (boolean)         | `z.boolean()`     | No                                                  |
+| `timestamptz`  | No (stays string)     | `z.coerce.date()` | Yes — `parser: { timestamptz: (v) => new Date(v) }` |
+| `jsonb`        | Yes (parsed object)   | As needed         | No                                                  |
+
+Note: `z.coerce.date()` is Zod-specific. Other StandardSchema libraries have their own coercion patterns.
+
+## Proxy Route
+
+Electric collections connect to a proxy URL (`shapeOptions.url`), not directly to Electric. Your app server must forward shape requests to Electric, passing through the Electric protocol query params.
+
+The proxy route must:
+
+1. Accept GET requests at the URL you specify in `shapeOptions.url`
+2. Forward all query parameters (these are Electric protocol params like `offset`, `handle`, `live`, etc.)
+3. Proxy the response (SSE stream) back to the client
+4. Optionally add authentication headers or filter params
+
+Implementation depends on your framework — use `createServerFn` in TanStack Start, API routes in Next.js, `loader` in Remix, etc. See the `@electric-sql/client` skills for proxy route examples:
+
+```bash
+npx @electric-sql/client intent list
+```
+
+## Electric Client Skills
+
+For deeper Electric-specific guidance (ShapeStream config, shape filtering, etc.), load the Electric client's built-in skills:
+
+```bash
+npx @electric-sql/client intent list
+```
+
+## Debug Logging
+
+```javascript
+localStorage.debug = 'ts/db:electric'
+```
+
+## Complete Example
+
+Always use a schema — types are inferred automatically, avoiding generic placement confusion.
+
+```typescript
+import { createCollection } from '@tanstack/react-db'
+import { electricCollectionOptions } from '@tanstack/electric-db-collection'
+import { z } from 'zod'
+
+const todoSchema = z.object({
+  id: z.string(),
+  text: z.string().min(1),
+  completed: z.boolean(),
+  created_at: z.coerce.date(),
+})
+
+const todosCollection = createCollection(
+  electricCollectionOptions({
+    id: 'todos',
+    schema: todoSchema,
+    getKey: (item) => item.id,
+    shapeOptions: {
+      url: '/api/todos',
+      params: { table: 'todos' },
+      parser: {
+        timestamptz: (value: string) => new Date(value), // sync path
+      },
+    },
+    onInsert: async ({ transaction }) => {
+      const response = await api.todos.create(transaction.mutations[0].modified)
+      return { txid: response.txid }
+    },
+    onUpdate: async ({ transaction }) => {
+      const { original, changes } = transaction.mutations[0]
+      const response = await api.todos.update({
+        where: { id: original.id },
+        data: changes,
+      })
+      return { txid: response.txid }
+    },
+    onDelete: async ({ transaction }) => {
+      const response = await api.todos.delete(transaction.mutations[0].key)
+      return { txid: response.txid }
+    },
+  }),
+)
+```

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,
+  }),
+)
+```