docs: document conditional queries and isUndefined/isNull functions#695
Merged
KyleAMathews merged 1 commit intomainfrom Oct 20, 2025
Merged
Conversation
Add comprehensive documentation for three undocumented live query features: 1. Conditional queries via undefined/null return - Document how to disable queries by returning undefined/null from useLiveQuery - Explain the disabled state (status: 'disabled', isEnabled: false) - Show practical "wait until inputs exist" pattern 2. Alternative useLiveQuery callback return types - Document returning pre-created Collections - Document returning LiveQueryCollectionConfig objects - Show use cases for each approach 3. isUndefined and isNull query functions - Add to Expression Functions Reference - Explain semantic difference between undefined vs null - Show examples with joins and optional properties These features were added in PR #535 and DB 0.2.0 but were not previously documented in the Live Queries guide. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
|
More templates
@tanstack/angular-db
@tanstack/db
@tanstack/db-ivm
@tanstack/electric-db-collection
@tanstack/query-db-collection
@tanstack/react-db
@tanstack/rxdb-db-collection
@tanstack/solid-db
@tanstack/svelte-db
@tanstack/trailbase-db-collection
@tanstack/vue-db
commit: |
Contributor
|
Size Change: 0 B Total Size: 83.7 kB ℹ️ View Unchanged
|
Contributor
|
Size Change: 0 B Total Size: 2.89 kB ℹ️ View Unchanged
|
KyleAMathews
deleted the
claude/review-live-query-docs-011CUJzuyDjEMw9pii46chzK
branch
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
3 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.
Summary
This PR adds comprehensive documentation for three previously undocumented live query features that were added in PR #535 and DB 0.2.0.
What's Documented
How to disable queries by returning undefined or null from useLiveQuery
Complete state description when disabled (status: 'disabled', isEnabled: false)
Practical "wait until inputs exist" pattern example
Example:
const { data, isEnabled } = useLiveQuery((q) => {
if (!userId) return undefined
return q.from({ todos: todosCollection })
}, [userId])
2. Alternative useLiveQuery callback return types
Returning pre-created Collections
Returning LiveQueryCollectionConfig objects
Use cases for each approach (debugging IDs, custom gcTime, etc.)
Example:
const { data } = useLiveQuery((q) => {
return {
query: q.from({ items: itemsCollection }),
id: 'items-view',
gcTime: 10000
}
})
3. isUndefined and isNull query functions
Added to Expression Functions Reference section
Explains semantic difference between undefined vs null
Shows examples with joins and optional properties
Example:
// Find users without a matching profile (left join resulted in undefined)
const usersWithoutProfiles = createLiveQueryCollection((q) =>
q.from({ user: usersCollection })
.leftJoin({ profile: profilesCollection }, ...)
.where(({ profile }) => isUndefined(profile))
)
Changes Made
Added "Conditional Queries" section after framework integration docs
Added "Alternative Callback Return Types" section with three subsections
Added isUndefined and isNull to "Expression Functions Reference"
All examples include TypeScript code with proper syntax highlighting
Intern Credit
These features were identified by an intern who did excellent research work cataloging undocumented features. The only minor correction needed was that when disabled, isIdle is false (not true).
Files Changed
docs/guides/live-queries.md - Added 131 lines of documentation