@tanstack/db 0.5.30 → 0.5.31

package/skills/db-core/live-queries/references/operators.md

@@ -0,0 +1,302 @@
+# Query Operators Reference
+
+All operators are imported from `@tanstack/db` (also re-exported by `@tanstack/react-db` and other framework packages).
+
+```ts
+import {
+  // Comparison
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  like,
+  ilike,
+  inArray,
+  isNull,
+  isUndefined,
+  // Logical
+  and,
+  or,
+  not,
+  // Aggregate
+  count,
+  sum,
+  avg,
+  min,
+  max,
+  // String
+  upper,
+  lower,
+  length,
+  concat,
+  // Math
+  add,
+  // Utility
+  coalesce,
+} from '@tanstack/db'
+```
+
+---
+
+## Comparison Operators
+
+### eq(left, right) -> BasicExpression\<boolean\>
+
+Equality comparison. Works with any type.
+
+```ts
+eq(user.id, 1)
+eq(user.name, 'Alice')
+```
+
+### not(eq(left, right)) — not-equal pattern
+
+There is no `ne` operator. Use `not(eq(...))` for not-equal:
+
+```ts
+not(eq(user.role, 'banned'))
+```
+
+### gt, gte, lt, lte (left, right) -> BasicExpression\<boolean\>
+
+Ordering comparisons. Work with numbers, strings, dates.
+
+```ts
+gt(user.age, 18) // greater than
+gte(user.salary, 50000) // greater than or equal
+lt(user.age, 65) // less than
+lte(user.rating, 5) // less than or equal
+gt(user.createdAt, new Date('2024-01-01'))
+```
+
+### like(left, right) -> BasicExpression\<boolean\>
+
+Case-sensitive string pattern matching. Use `%` as wildcard.
+
+```ts
+like(user.name, 'John%') // starts with John
+like(user.email, '%@corp.com') // ends with @corp.com
+```
+
+### ilike(left, right) -> BasicExpression\<boolean\>
+
+Case-insensitive string pattern matching.
+
+```ts
+ilike(user.email, '%@gmail.com')
+```
+
+### inArray(value, array) -> BasicExpression\<boolean\>
+
+Check if value is contained in an array.
+
+```ts
+inArray(user.id, [1, 2, 3])
+inArray(user.role, ['admin', 'moderator'])
+```
+
+### isNull(value) -> BasicExpression\<boolean\>
+
+Check if value is explicitly `null`.
+
+```ts
+isNull(user.bio)
+```
+
+### isUndefined(value) -> BasicExpression\<boolean\>
+
+Check if value is `undefined` (absent). Especially useful after left joins where unmatched rows produce `undefined`.
+
+```ts
+isUndefined(profile) // no matching profile in left join
+```
+
+---
+
+## Logical Operators
+
+### and(...conditions) -> BasicExpression\<boolean\>
+
+Combine two or more conditions with AND logic.
+
+```ts
+and(eq(user.active, true), gt(user.age, 18))
+and(eq(user.active, true), gt(user.age, 18), eq(user.role, 'user'))
+```
+
+### or(...conditions) -> BasicExpression\<boolean\>
+
+Combine two or more conditions with OR logic.
+
+```ts
+or(eq(user.role, 'admin'), eq(user.role, 'moderator'))
+```
+
+### not(condition) -> BasicExpression\<boolean\>
+
+Negate a condition.
+
+```ts
+not(eq(user.active, false))
+not(inArray(user.id, bannedIds))
+```
+
+---
+
+## Aggregate Functions
+
+Used inside `.select()` with `.groupBy()`, or without `groupBy` to aggregate the entire collection as one group.
+
+### count(value) -> Aggregate\<number\>
+
+Count non-null values in a group.
+
+```ts
+count(user.id)
+```
+
+### sum(value), avg(value) -> Aggregate\<number | null | undefined\>
+
+Sum or average of numeric values.
+
+```ts
+sum(order.amount)
+avg(user.salary)
+```
+
+### min(value), max(value) -> Aggregate\<T\>
+
+Minimum/maximum value (numbers, strings, dates).
+
+```ts
+min(order.amount)
+max(user.createdAt)
+```
+
+---
+
+## String Functions
+
+### upper(value), lower(value) -> BasicExpression\<string\>
+
+Convert string case.
+
+```ts
+upper(user.name) // 'ALICE'
+lower(user.email) // 'alice@example.com'
+```
+
+### length(value) -> BasicExpression\<number\>
+
+Get string or array length.
+
+```ts
+length(user.name) // string length
+length(user.tags) // array length
+```
+
+### concat(...values) -> BasicExpression\<string\>
+
+Concatenate any number of values into a string.
+
+```ts
+concat(user.firstName, ' ', user.lastName)
+```
+
+---
+
+## Math Functions
+
+### add(left, right) -> BasicExpression\<number\>
+
+Add two numeric values.
+
+```ts
+add(order.price, order.tax)
+add(user.salary, coalesce(user.bonus, 0))
+```
+
+---
+
+## Utility Functions
+
+### coalesce(...values) -> BasicExpression\<any\>
+
+Return the first non-null, non-undefined value.
+
+```ts
+coalesce(user.displayName, user.name, 'Unknown')
+coalesce(user.bonus, 0)
+```
+
+---
+
+## $selected Namespace
+
+When a query has a `.select()` clause, the `$selected` namespace becomes available in `.orderBy()` and `.having()` callbacks. It provides access to the computed/aggregated fields defined in `select`.
+
+```ts
+q.from({ order: ordersCollection })
+  .groupBy(({ order }) => order.customerId)
+  .select(({ order }) => ({
+    customerId: order.customerId,
+    totalSpent: sum(order.amount),
+    orderCount: count(order.id),
+  }))
+  .having(({ $selected }) => gt($selected.totalSpent, 1000))
+  .orderBy(({ $selected }) => $selected.totalSpent, 'desc')
+```
+
+`$selected` is only available when `.select()` (or `.fn.select()`) has been called on the query.
+
+---
+
+## Functional Variants (fn.select, fn.where, fn.having)
+
+Escape hatches for logic that cannot be expressed with declarative operators. These execute arbitrary JS on each row but **cannot be optimized** by the query compiler (no predicate push-down, no index use).
+
+### fn.select(callback)
+
+```ts
+q.from({ user: usersCollection }).fn.select((row) => ({
+  id: row.user.id,
+  domain: row.user.email.split('@')[1],
+  tier: row.user.salary > 100000 ? 'senior' : 'junior',
+}))
+```
+
+**Limitation**: `fn.select()` cannot be used with `groupBy()`. The compiler must statically analyze select to discover aggregate functions.
+
+### fn.where(callback)
+
+```ts
+q.from({ user: usersCollection }).fn.where(
+  (row) => row.user.active && row.user.email.endsWith('@company.com'),
+)
+```
+
+### fn.having(callback)
+
+Receives `$selected` when a `select()` clause exists.
+
+```ts
+q.from({ order: ordersCollection })
+  .groupBy(({ order }) => order.customerId)
+  .select(({ order }) => ({
+    customerId: order.customerId,
+    totalSpent: sum(order.amount),
+    orderCount: count(order.id),
+  }))
+  .fn.having(
+    ({ $selected }) => $selected.totalSpent > 1000 && $selected.orderCount >= 3,
+  )
+```
+
+### When to use functional variants
+
+- String manipulation not covered by `upper`/`lower`/`concat`/`like` (e.g., `split`, `slice`, regex)
+- Complex conditional logic (ternaries, multi-branch)
+- External function calls or lookups
+
+Prefer declarative operators whenever possible for incremental maintenance.

package/skills/db-core/mutations-optimistic/SKILL.md

@@ -0,0 +1,375 @@
+---
+name: db-core/mutations-optimistic
+description: >
+  collection.insert, collection.update (Immer-style draft proxy),
+  collection.delete. createOptimisticAction (onMutate + mutationFn).
+  createPacedMutations with debounceStrategy, throttleStrategy, queueStrategy.
+  createTransaction, getActiveTransaction, ambient transaction context.
+  Transaction lifecycle (pending/persisting/completed/failed). Mutation merging.
+  onInsert/onUpdate/onDelete handlers. PendingMutation type. Transaction.isPersisted.
+type: sub-skill
+library: db
+library_version: '0.5.30'
+sources:
+  - 'TanStack/db:docs/guides/mutations.md'
+  - 'TanStack/db:packages/db/src/transactions.ts'
+  - 'TanStack/db:packages/db/src/optimistic-action.ts'
+  - 'TanStack/db:packages/db/src/paced-mutations.ts'
+---
+
+# Mutations & Optimistic State
+
+> **Depends on:** `db-core/collection-setup` -- you need a configured collection
+> (with `getKey`, sync adapter, and optionally `onInsert`/`onUpdate`/`onDelete`
+> handlers) before you can mutate.
+
+TanStack DB mutations follow a unidirectional loop:
+**optimistic mutation -> handler persists to backend -> sync back -> confirmed state**.
+Optimistic state is applied in the current tick and dropped when the handler resolves.
+
+---
+
+## Setup -- Collection Write Operations
+
+### insert
+
+```ts
+// Single item
+todoCollection.insert({
+  id: crypto.randomUUID(),
+  text: 'Buy groceries',
+  completed: false,
+})
+
+// Multiple items
+todoCollection.insert([
+  { id: crypto.randomUUID(), text: 'Buy groceries', completed: false },
+  { id: crypto.randomUUID(), text: 'Walk dog', completed: false },
+])
+
+// With metadata / non-optimistic
+todoCollection.insert(item, { metadata: { source: 'import' } })
+todoCollection.insert(item, { optimistic: false })
+```
+
+### update (Immer-style draft proxy)
+
+```ts
+// Single item -- mutate the draft, do NOT reassign it
+todoCollection.update(todo.id, (draft) => {
+  draft.completed = true
+  draft.completedAt = new Date()
+})
+
+// Multiple items
+todoCollection.update([id1, id2], (drafts) => {
+  drafts.forEach((d) => {
+    d.completed = true
+  })
+})
+
+// With metadata
+todoCollection.update(
+  todo.id,
+  { metadata: { reason: 'user-edit' } },
+  (draft) => {
+    draft.text = 'Updated'
+  },
+)
+```
+
+### delete
+
+```ts
+todoCollection.delete(todo.id)
+todoCollection.delete([id1, id2])
+todoCollection.delete(todo.id, { metadata: { reason: 'completed' } })
+```
+
+All three return a `Transaction` object. Use `tx.isPersisted.promise` to await
+persistence or catch rollback errors.
+
+---
+
+## Core Patterns
+
+### 1. createOptimisticAction -- intent-based mutations
+
+Use when the optimistic change is a _guess_ at how the server will transform
+the data, or when you need to mutate multiple collections atomically.
+
+```ts
+import { createOptimisticAction } from '@tanstack/db'
+
+const likePost = createOptimisticAction<string>({
+  // MUST be synchronous -- applied in the current tick
+  onMutate: (postId) => {
+    postCollection.update(postId, (draft) => {
+      draft.likeCount += 1
+      draft.likedByMe = true
+    })
+  },
+  mutationFn: async (postId, { transaction }) => {
+    await api.posts.like(postId)
+    // IMPORTANT: wait for server state to sync back before returning
+    await postCollection.utils.refetch()
+  },
+})
+
+// Returns a Transaction
+const tx = likePost(postId)
+await tx.isPersisted.promise
+```
+
+Multi-collection example:
+
+```ts
+const createProject = createOptimisticAction<{ name: string; ownerId: string }>(
+  {
+    onMutate: ({ name, ownerId }) => {
+      projectCollection.insert({ id: crypto.randomUUID(), name, ownerId })
+      userCollection.update(ownerId, (d) => {
+        d.projectCount += 1
+      })
+    },
+    mutationFn: async ({ name, ownerId }) => {
+      await api.projects.create({ name, ownerId })
+      await Promise.all([
+        projectCollection.utils.refetch(),
+        userCollection.utils.refetch(),
+      ])
+    },
+  },
+)
+```
+
+### 2. createPacedMutations -- auto-save with debounce / throttle / queue
+
+```ts
+import { createPacedMutations, debounceStrategy } from '@tanstack/db'
+
+const autoSaveNote = createPacedMutations<string>({
+  onMutate: (text) => {
+    noteCollection.update(noteId, (draft) => {
+      draft.body = text
+    })
+  },
+  mutationFn: async ({ transaction }) => {
+    const mutation = transaction.mutations[0]
+    await api.notes.update(mutation.key, mutation.changes)
+    await noteCollection.utils.refetch()
+  },
+  strategy: debounceStrategy({ wait: 500 }),
+})
+
+// Each call resets the debounce timer; mutations merge into one transaction
+autoSaveNote('Hello')
+autoSaveNote('Hello, world') // only this version persists
+```
+
+Other strategies:
+
+```ts
+import { throttleStrategy, queueStrategy } from '@tanstack/db'
+
+// Evenly spaced (sliders, scroll)
+throttleStrategy({ wait: 200, leading: true, trailing: true })
+
+// Sequential FIFO -- every mutation persisted in order
+queueStrategy({ wait: 0, maxSize: 100 })
+```
+
+### 3. createTransaction -- manual batching
+
+```ts
+import { createTransaction } from '@tanstack/db'
+
+const tx = createTransaction({
+  autoCommit: false, // wait for explicit commit()
+  mutationFn: async ({ transaction }) => {
+    await api.batchUpdate(transaction.mutations)
+  },
+})
+
+tx.mutate(() => {
+  todoCollection.update(id1, (d) => {
+    d.status = 'reviewed'
+  })
+  todoCollection.update(id2, (d) => {
+    d.status = 'reviewed'
+  })
+})
+
+// User reviews... then commits or rolls back
+await tx.commit()
+// OR: tx.rollback()
+```
+
+Inside `tx.mutate(() => { ... })`, the transaction is pushed onto an ambient
+stack. Any `collection.insert/update/delete` call joins the ambient transaction
+automatically via `getActiveTransaction()`.
+
+### 4. Mutation handler with refetch (QueryCollection pattern)
+
+```ts
+const todoCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ['todos'],
+    queryFn: () => api.todos.getAll(),
+    getKey: (t) => t.id,
+    onInsert: async ({ transaction }) => {
+      await Promise.all(
+        transaction.mutations.map((m) => api.todos.create(m.modified)),
+      )
+      // IMPORTANT: handler must not resolve until server state is synced back
+      // QueryCollection auto-refetches after handler completes
+    },
+    onUpdate: async ({ transaction }) => {
+      await Promise.all(
+        transaction.mutations.map((m) =>
+          api.todos.update(m.original.id, m.changes),
+        ),
+      )
+    },
+    onDelete: async ({ transaction }) => {
+      await Promise.all(
+        transaction.mutations.map((m) => api.todos.delete(m.original.id)),
+      )
+    },
+  }),
+)
+```
+
+For ElectricCollection, return `{ txid }` instead of refetching:
+
+```ts
+onUpdate: async ({ transaction }) => {
+  const txids = await Promise.all(
+    transaction.mutations.map(async (m) => {
+      const res = await api.todos.update(m.original.id, m.changes)
+      return res.txid
+    }),
+  )
+  return { txid: txids }
+}
+```
+
+---
+
+## Common Mistakes
+
+### CRITICAL: Passing an object to update() instead of a draft callback
+
+```ts
+// WRONG -- silently fails or throws
+collection.update(id, { ...item, title: 'new' })
+
+// CORRECT -- mutate the draft proxy
+collection.update(id, (draft) => {
+  draft.title = 'new'
+})
+```
+
+### CRITICAL: Hallucinating mutation API signatures
+
+The most common AI-generated errors:
+
+- Inventing handler signatures (e.g. `onMutate` on a collection config)
+- Confusing `createOptimisticAction` with `createTransaction`
+- Wrong PendingMutation property names (`mutation.data` does not exist --
+  use `mutation.modified`, `mutation.changes`, `mutation.original`)
+- Missing the ambient transaction pattern
+
+Always reference the exact types in `references/transaction-api.md`.
+
+### CRITICAL: onMutate returning a Promise
+
+`onMutate` in `createOptimisticAction` **must be synchronous**. Optimistic state
+is applied in the current tick. Returning a Promise throws
+`OnMutateMustBeSynchronousError`.
+
+```ts
+// WRONG
+createOptimisticAction({
+  onMutate: async (text) => {
+    collection.insert({ id: await generateId(), text })
+  },
+  ...
+})
+
+// CORRECT
+createOptimisticAction({
+  onMutate: (text) => {
+    collection.insert({ id: crypto.randomUUID(), text })
+  },
+  ...
+})
+```
+
+### CRITICAL: Mutations without handler or ambient transaction
+
+Collection mutations require either:
+
+1. An `onInsert`/`onUpdate`/`onDelete` handler on the collection, OR
+2. An ambient transaction from `createTransaction`/`createOptimisticAction`
+
+Without either, throws `MissingInsertHandlerError` (or the Update/Delete variant).
+
+### HIGH: Calling .mutate() after transaction is no longer pending
+
+Transactions only accept new mutations while in `pending` state. Calling
+`mutate()` after `commit()` or `rollback()` throws
+`TransactionNotPendingMutateError`. Create a new transaction instead.
+
+### HIGH: Changing primary key via update
+
+The update proxy detects key changes and throws `KeyUpdateNotAllowedError`.
+Primary keys are immutable once set. If you need a different key, delete and
+re-insert.
+
+### HIGH: Inserting item with duplicate key
+
+If an item with the same key already exists (synced or optimistic), throws
+`DuplicateKeyError`. Always generate a unique key (e.g. `crypto.randomUUID()`)
+or check before inserting.
+
+### HIGH: Not awaiting refetch after mutation in query collection handler
+
+The optimistic state is held only until the handler resolves. If the handler
+returns before server state has synced back, optimistic state is dropped and
+users see a flash of missing data.
+
+```ts
+// WRONG -- optimistic state dropped before new server state arrives
+onInsert: async ({ transaction }) => {
+  await api.createTodo(transaction.mutations[0].modified)
+  // missing: await collection.utils.refetch()
+}
+
+// CORRECT
+onInsert: async ({ transaction }) => {
+  await api.createTodo(transaction.mutations[0].modified)
+  await collection.utils.refetch()
+}
+```
+
+---
+
+## Tension: Optimistic Speed vs. Data Consistency
+
+Instant optimistic updates create a window where client state diverges from
+server state. If the handler fails, the rollback removes the optimistic state --
+which can discard user work the user thought was saved. Consider:
+
+- Showing pending/saving indicators so users know state is unconfirmed
+- Using `{ optimistic: false }` for destructive operations
+- Designing idempotent server endpoints so retries are safe
+- Handling `tx.isPersisted.promise` rejection to surface errors to the user
+
+---
+
+## References
+
+- [Transaction API Reference](references/transaction-api.md) -- createTransaction config,
+  Transaction object, PendingMutation type, mutation merging rules, strategy types
+- [TanStack DB Mutations Guide](https://tanstack.com/db/latest/docs/guides/mutations)