docs(db): clarify caseWhen, coalesce, manual transactions, and multi-endpoint behavior by KyleAMathews · Pull Request #1544 · TanStack/db

KyleAMathews · 2026-05-21T20:26:07Z

Summary

Addresses documentation feedback by clarifying several areas where users were confused or the docs were incomplete:

Document the new caseWhen operator with examples and usage guidance
Clarify that coalesce handles both null and undefined (not just null)
Explain that manual transaction mutations bypass collection-level onInsert/onUpdate/onDelete handlers, with a draft-style workflow example
Warn about multi-endpoint Query Collection pitfalls when the same collection receives data from different REST endpoints

Approach

These changes address real confusion points reported via feedback. Each addition follows the existing doc patterns: prose explanation followed by code examples showing WRONG vs CORRECT usage where applicable.

Key decisions:

Added a new "Utility Functions" heading in the live queries guide to properly categorize coalesce and caseWhen (previously both were under "Mathematical Functions")
Fixed the SKILL.md frontmatter to categorize coalesce/caseWhen as utility functions rather than string functions — important since LLMs read frontmatter for relevance
Removed the stale line-number anchor from operators.md source link to prevent future rot
Fixed caseWhen alphabetical ordering in the reference index

Non-goals:

Did not restructure existing documentation sections beyond the minimal heading addition
Did not add the untracked docs/reference/functions/caseWhen.md file (separate concern)

Files changed

File	Change
`docs/collections/query-collection.md`	Multi-endpoint pitfall warning + three recommended patterns
`docs/guides/live-queries.md`	`coalesce` examples, `caseWhen` docs, new "Utility Functions" heading
`docs/guides/mutations.md`	Manual transaction handler bypass explanation + draft workflow example
`docs/reference/index.md`	Added `caseWhen` in correct alphabetical position
`docs/reference/variables/operators.md`	Added `caseWhen` to operators list, removed stale line anchor
`packages/db/skills/db-core/live-queries/SKILL.md`	Updated frontmatter categorization, added conditional expression helpers section
`packages/db/skills/db-core/mutations-optimistic/SKILL.md`	Added note about manual transactions bypassing collection handlers

Verification

These are documentation-only changes with no runtime impact.

# Verify docs build
pnpm docs:build

🤖 Generated with Claude Code

Summary by CodeRabbit

Documentation
- Clarified Query Collection full-state requirement and safe multi-endpoint/subset-loading patterns
- Expanded coalesce behavior and added comprehensive caseWhen docs with examples and usage across query clauses
- Clarified manual transactions: how captured mutations interact with collection handlers, optimistic flows, commit/rollback examples
- Updated reference and utility-function docs, plus ordering/organization improvements

…endpoint behavior Address documentation feedback: add caseWhen operator docs, clarify coalesce handles null/undefined, document manual transaction handler bypass semantics, and warn about multi-endpoint Query Collection pitfalls. Fix categorization of utility functions and reference index ordering. Co-Authored-By: Claude Opus 4.6 <[email protected]>

Co-Authored-By: Claude Opus 4.6 <[email protected]>

coderabbitai · 2026-05-21T20:29:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bcc3aac1-7d2a-41f5-9374-3cefff7a6615

📥 Commits

Reviewing files that changed from the base of the PR and between 38906d9 and 5cb0574.

📒 Files selected for processing (1)

docs/collections/query-collection.md

✅ Files skipped from review due to trivial changes (1)

docs/collections/query-collection.md

📝 Walkthrough

Walkthrough

This PR updates documentation across user guides, API references, and skill files to clarify TanStack DB behavior: introducing caseWhen as a conditional utility alongside coalesce, explaining that manual transactions do not invoke collection handlers, and documenting Query Collection full-state-sync requirements with multi-endpoint guidance.

Changes

Documentation Clarifications

Layer / File(s)	Summary
caseWhen utility documentation and operator registry `docs/guides/live-queries.md`, `docs/reference/index.md`, `docs/reference/variables/operators.md`	`caseWhen` is documented as a SQL-like conditional utility in the live-queries guide with examples showing fallback logic for null/undefined/empty-string cases. It is added to the API reference index and the operators list, making it discoverable in the public API documentation.
Expression utilities skill guidance `packages/db/skills/db-core/live-queries/SKILL.md`	The skill file is updated to mention `caseWhen` alongside `coalesce` as supported conditional utilities, includes a new subsection on building conditional expressions, and provides WRONG/CORRECT examples demonstrating when to use `coalesce()` and `caseWhen()` instead of arbitrary JavaScript functions.
Manual transaction handler behavior clarification `docs/guides/mutations.md`, `packages/db/skills/db-core/mutations-optimistic/SKILL.md`	Documentation clarifies that collection `onInsert`/`onUpdate`/`onDelete` handlers are not invoked when mutations are captured by manual transactions. A draft-workflow example is added showing `createTransaction({ autoCommit: false })`, `mutate()` for optimistic edits, and deferred `commit()` or `rollback()`.
Query Collection full-state-sync guidance `docs/collections/query-collection.md`	New subsection under "Full State Sync" clarifies that the `queryFn` result must represent complete server state for the collection scope, warns against mixing endpoints of different scopes, and recommends alternatives such as `syncMode: 'on-demand'`, separate Query Collections per scope, or direct writes via `writeUpsert`/`writeBatch`.
Release metadata `.changeset/docs-feedback-clarifications.md`	Changeset entry declares a `patch` release for `@tanstack/db` documenting the clarifications added across utility functions, manual transactions, and Query Collection guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

TanStack/db#1538: Related update to manual transaction and tx.mutate() behavior documentation clarifying handler invocation scope.
TanStack/db#1536: Related to caseWhen implementation/compilation semantics referenced by these docs.

Suggested reviewers

samwillis
kevin-dp

Poem

🐰 I hopped through docs to make things clear,

Where caseWhen checks and coalesce appear,
Manual tx drafts now behave as planned,
Query Collections know their single-scope stand,
Patch notes penned with a rabbit's bright cheer.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and specifically summarizes the main changes: clarifying documentation for caseWhen, coalesce, manual transactions, and multi-endpoint behavior.
Description check	✅ Passed	The description is comprehensive and well-structured, covering changes, approach, key decisions, files changed, and verification steps, but does not follow the provided template structure with the checklist sections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs-feedback-clarifications

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

pkg-pr-new · 2026-05-21T20:36:57Z

More templates

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@1544

@tanstack/browser-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1544

@tanstack/capacitor-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1544

@tanstack/cloudflare-durable-objects-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1544

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@1544

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@1544

@tanstack/db-sqlite-persistence-core

npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1544

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@1544

@tanstack/electron-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1544

@tanstack/expo-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1544

@tanstack/node-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1544

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1544

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1544

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@1544

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@1544

@tanstack/react-native-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1544

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1544

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@1544

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@1544

@tanstack/tauri-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1544

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1544

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@1544

commit: 5cb0574

github-actions · 2026-05-21T20:37:35Z

Size Change: 0 B

Total Size: 122 kB

ℹ️ View Unchanged

Filename	Size
`packages/db/dist/esm/collection/change-events.js`	1.39 kB
`packages/db/dist/esm/collection/changes.js`	1.38 kB
`packages/db/dist/esm/collection/cleanup-queue.js`	810 B
`packages/db/dist/esm/collection/events.js`	434 B
`packages/db/dist/esm/collection/index.js`	3.61 kB
`packages/db/dist/esm/collection/indexes.js`	1.99 kB
`packages/db/dist/esm/collection/lifecycle.js`	1.69 kB
`packages/db/dist/esm/collection/mutations.js`	2.47 kB
`packages/db/dist/esm/collection/state.js`	5.26 kB
`packages/db/dist/esm/collection/subscription.js`	3.74 kB
`packages/db/dist/esm/collection/sync.js`	2.88 kB
`packages/db/dist/esm/collection/transaction-metadata.js`	144 B
`packages/db/dist/esm/deferred.js`	207 B
`packages/db/dist/esm/errors.js`	5.01 kB
`packages/db/dist/esm/event-emitter.js`	748 B
`packages/db/dist/esm/index.js`	3.01 kB
`packages/db/dist/esm/indexes/auto-index.js`	829 B
`packages/db/dist/esm/indexes/base-index.js`	729 B
`packages/db/dist/esm/indexes/basic-index.js`	2.05 kB
`packages/db/dist/esm/indexes/btree-index.js`	2.17 kB
`packages/db/dist/esm/indexes/index-registry.js`	820 B
`packages/db/dist/esm/indexes/reverse-index.js`	538 B
`packages/db/dist/esm/local-only.js`	890 B
`packages/db/dist/esm/local-storage.js`	2.1 kB
`packages/db/dist/esm/optimistic-action.js`	359 B
`packages/db/dist/esm/paced-mutations.js`	496 B
`packages/db/dist/esm/proxy.js`	3.75 kB
`packages/db/dist/esm/query/builder/functions.js`	1.37 kB
`packages/db/dist/esm/query/builder/index.js`	5.79 kB
`packages/db/dist/esm/query/builder/ref-proxy.js`	1.23 kB
`packages/db/dist/esm/query/compiler/evaluators.js`	1.83 kB
`packages/db/dist/esm/query/compiler/expressions.js`	430 B
`packages/db/dist/esm/query/compiler/group-by.js`	3.56 kB
`packages/db/dist/esm/query/compiler/index.js`	6.67 kB
`packages/db/dist/esm/query/compiler/joins.js`	2.5 kB
`packages/db/dist/esm/query/compiler/lazy-targets.js`	918 B
`packages/db/dist/esm/query/compiler/order-by.js`	1.74 kB
`packages/db/dist/esm/query/compiler/select.js`	1.4 kB
`packages/db/dist/esm/query/effect.js`	4.77 kB
`packages/db/dist/esm/query/expression-helpers.js`	1.43 kB
`packages/db/dist/esm/query/ir.js`	1.25 kB
`packages/db/dist/esm/query/live-query-collection.js`	360 B
`packages/db/dist/esm/query/live/collection-config-builder.js`	8.34 kB
`packages/db/dist/esm/query/live/collection-registry.js`	264 B
`packages/db/dist/esm/query/live/collection-subscriber.js`	1.93 kB
`packages/db/dist/esm/query/live/internal.js`	145 B
`packages/db/dist/esm/query/live/utils.js`	1.81 kB
`packages/db/dist/esm/query/optimizer.js`	2.92 kB
`packages/db/dist/esm/query/predicate-utils.js`	2.97 kB
`packages/db/dist/esm/query/query-once.js`	359 B
`packages/db/dist/esm/query/subset-dedupe.js`	960 B
`packages/db/dist/esm/scheduler.js`	1.3 kB
`packages/db/dist/esm/SortedMap.js`	1.3 kB
`packages/db/dist/esm/strategies/debounceStrategy.js`	247 B
`packages/db/dist/esm/strategies/queueStrategy.js`	428 B
`packages/db/dist/esm/strategies/throttleStrategy.js`	246 B
`packages/db/dist/esm/transactions.js`	3.02 kB
`packages/db/dist/esm/utils.js`	927 B
`packages/db/dist/esm/utils/array-utils.js`	273 B
`packages/db/dist/esm/utils/browser-polyfills.js`	304 B
`packages/db/dist/esm/utils/btree.js`	5.61 kB
`packages/db/dist/esm/utils/comparison.js`	1.05 kB
`packages/db/dist/esm/utils/cursor.js`	457 B
`packages/db/dist/esm/utils/index-optimization.js`	1.54 kB
`packages/db/dist/esm/utils/type-guards.js`	157 B
`packages/db/dist/esm/virtual-props.js`	360 B

_{compressed-size-action::db-package-size}

github-actions · 2026-05-21T20:38:12Z

Size Change: 0 B

Total Size: 4.24 kB

ℹ️ View Unchanged

Filename	Size
`packages/react-db/dist/esm/index.js`	249 B
`packages/react-db/dist/esm/useLiveInfiniteQuery.js`	1.32 kB
`packages/react-db/dist/esm/useLiveQuery.js`	1.34 kB
`packages/react-db/dist/esm/useLiveQueryEffect.js`	355 B
`packages/react-db/dist/esm/useLiveSuspenseQuery.js`	567 B
`packages/react-db/dist/esm/usePacedMutations.js`	401 B

_{compressed-size-action::react-db-package-size}

Co-Authored-By: Claude Opus 4.6 <[email protected]>

KyleAMathews and others added 2 commits May 21, 2026 14:24

chore: add changeset for docs clarifications

38906d9

Co-Authored-By: Claude Opus 4.6 <[email protected]>

docs(db): mention unionAll as option for multi-endpoint collections

5cb0574

Co-Authored-By: Claude Opus 4.6 <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(db): clarify caseWhen, coalesce, manual transactions, and multi-endpoint behavior#1544

docs(db): clarify caseWhen, coalesce, manual transactions, and multi-endpoint behavior#1544
KyleAMathews wants to merge 3 commits into
mainfrom
docs-feedback-clarifications

KyleAMathews commented May 21, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented May 21, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

pkg-pr-new Bot commented May 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 21, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

KyleAMathews commented May 21, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Approach

Files changed

Verification

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested reviewers

Poem

Uh oh!

pkg-pr-new Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

KyleAMathews commented May 21, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented May 21, 2026 •

edited

Loading

pkg-pr-new Bot commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading