docs(query-db-collection): clarify select row extraction#1654
Merged
Conversation
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR clarifies ChangesSelect Semantics Clarification
Estimated code review effort: 2 (Simple) | ~10 minutes Related issues: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
More templates
@tanstack/angular-db
@tanstack/browser-db-sqlite-persistence
@tanstack/capacitor-db-sqlite-persistence
@tanstack/cloudflare-durable-objects-db-sqlite-persistence
@tanstack/db
@tanstack/db-ivm
@tanstack/db-sqlite-persistence-core
@tanstack/electric-db-collection
@tanstack/electron-db-sqlite-persistence
@tanstack/expo-db-sqlite-persistence
@tanstack/node-db-sqlite-persistence
@tanstack/offline-transactions
@tanstack/powersync-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/react-native-db-sqlite-persistence
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/tauri-db-sqlite-persistence
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: 0 B Total Size: 125 kB ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 4.26 kB ℹ️ View Unchanged
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/query-db-collection/tests/query.test.ts`:
- Around line 901-935: The test in query.test.ts reuses the same wrappedResponse
object for both the query result and the final cache assertion, so it can miss
in-place cache mutation. Update the “materializes selected rows while preserving
wrapped Query cache response” test to create a separate expected snapshot before
calling queryFn, then assert queryClient.getQueryData(queryKey) against that
independent snapshot. Keep the focus on the wrappedResponse/select/queryClient
path so the test verifies the cached envelope is truly preserved.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 86834c2e-2fdf-44ad-94cd-df02f0435940
📒 Files selected for processing (4)
.changeset/clarify-query-select-semantics.mddocs/collections/query-collection.mdpackages/query-db-collection/src/query.tspackages/query-db-collection/tests/query.test.ts
kevin-dp
approved these changes
Jul 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clarifies
@tanstack/query-db-collectionselectas row extraction for TanStack DB materialization, while preserving the wrapped TanStack Query cache response. This gives users a clearer model for APIs that return envelopes like{ items, nextCursor }without introducing a new projection API.Root Cause
Issue #345 asked for wrapped API responses to work with query collections. The implementation already supports this, but the docs still described
selecttersely and could be read as equivalent to TanStack Query's observer-levelselect. That left the adapter boundary unclear: Query owns the response cache shape, while TanStack DB materializes rows extracted from that response.Approach
selectas a query-db-collection row extraction hook.response.itemswhilequeryClient.getQueryData(queryKey)still returns the full response envelope.data,items, andresults.QueryCollectionConfig.selectto match the public docs.Key Invariants
selectreturns the row array TanStack DB materializes.Non-goals
select.rows.read/rows.writeprojection API.Trade-offs
The docs call direct-write patching "best effort" rather than narrowing the existing fallback behavior. This preserves compatibility for current simple wrapper use cases while making it clear that derived projections cannot generally be reverse-patched without a future explicit read/write projection API.
Verification
Files changed
docs/collections/query-collection.md— clarifiesselectsemantics, wrapped response behavior, and best-effort direct-write cache patching.packages/query-db-collection/src/query.ts— updates theselectAPI comment.packages/query-db-collection/tests/query.test.ts— adds wrapped response row extraction/cache preservation coverage..changeset/clarify-query-select-semantics.md— records a patch changeset for@tanstack/query-db-collection.Closes #345
Related #1643
Summary by CodeRabbit
selectsemantics for wrapped API responses, explaining how row extraction works while preserving the full original response shape in cache.selectcorrectly materializes rows fromitemswhen thequeryFnreturns an envelope, while confirming the cache retainsmetaand the full wrapped response.