expand `useLiveQuery` callback to support conditional queries and additional return types by samwillis · Pull Request #535 · TanStack/db

samwillis · 2025-09-11T18:01:12Z

No description provided.

changeset-bot · 2025-09-11T18:01:16Z

🦋 Changeset detected

Latest commit: 13d9d0d

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@tanstack/react-db	Patch
@tanstack/db-example-react-todo	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2025-09-11T18:02:41Z

More templates

@tanstack/angular-db

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 13d9d0d

…itional return types

packages/react-db/src/useLiveQuery.ts

github-actions · 2025-09-11T18:05:51Z

Size Change: 0 B

Total Size: 68.4 kB

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/change-events.js`	1.13 kB
`./packages/db/dist/esm/collection-events.js`	672 B
`./packages/db/dist/esm/collection.js`	10.9 kB
`./packages/db/dist/esm/deferred.js`	230 B
`./packages/db/dist/esm/errors.js`	3.1 kB
`./packages/db/dist/esm/index.js`	1.55 kB
`./packages/db/dist/esm/indexes/auto-index.js`	745 B
`./packages/db/dist/esm/indexes/base-index.js`	605 B
`./packages/db/dist/esm/indexes/btree-index.js`	1.74 kB
`./packages/db/dist/esm/indexes/lazy-index.js`	1.25 kB
`./packages/db/dist/esm/local-only.js`	827 B
`./packages/db/dist/esm/local-storage.js`	2.02 kB
`./packages/db/dist/esm/optimistic-action.js`	294 B
`./packages/db/dist/esm/proxy.js`	3.87 kB
`./packages/db/dist/esm/query/builder/functions.js`	615 B
`./packages/db/dist/esm/query/builder/index.js`	3.93 kB
`./packages/db/dist/esm/query/builder/ref-proxy.js`	938 B
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.52 kB
`./packages/db/dist/esm/query/compiler/expressions.js`	631 B
`./packages/db/dist/esm/query/compiler/group-by.js`	2.08 kB
`./packages/db/dist/esm/query/compiler/index.js`	2.27 kB
`./packages/db/dist/esm/query/compiler/joins.js`	2.52 kB
`./packages/db/dist/esm/query/compiler/order-by.js`	1.23 kB
`./packages/db/dist/esm/query/compiler/select.js`	1.28 kB
`./packages/db/dist/esm/query/ir.js`	508 B
`./packages/db/dist/esm/query/live-query-collection.js`	333 B
`./packages/db/dist/esm/query/live/collection-config-builder.js`	2.59 kB
`./packages/db/dist/esm/query/live/collection-subscriber.js`	2.4 kB
`./packages/db/dist/esm/query/optimizer.js`	3.05 kB
`./packages/db/dist/esm/SortedMap.js`	1.24 kB
`./packages/db/dist/esm/transactions.js`	3.03 kB
`./packages/db/dist/esm/utils.js`	943 B
`./packages/db/dist/esm/utils/btree.js`	6.02 kB
`./packages/db/dist/esm/utils/comparison.js`	718 B
`./packages/db/dist/esm/utils/index-optimization.js`	1.62 kB

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

github-actions · 2025-09-11T18:07:11Z

Size Change: 0 B

Total Size: 1.18 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	152 B
`./packages/react-db/dist/esm/useLiveQuery.js`	1.02 kB

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

KyleAMathews

Generally looks great!

packages/react-db/src/useLiveQuery.ts

KyleAMathews · 2025-09-11T18:58:14Z

packages/react-db/src/useLiveQuery.ts

+        if (result === undefined || result === null) {
+          // Callback returned undefined/null - disabled query
+          collectionRef.current = null
+        } else if (result instanceof CollectionImpl) {


it'd be nice to have a isCollection

I've left isCollection and isQueryBuilder for a followup, there is some ambiguity on when each should be set as everything becomes a collection at the end.

KyleAMathews · 2025-09-11T18:58:25Z

packages/react-db/src/useLiveQuery.ts

+          // Callback returned a Collection instance - use it directly
+          result.startSyncImmediate()
+          collectionRef.current = result
+        } else if (result instanceof BaseQueryBuilder) {


and isQueryBuilder

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>

…695) 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>

samwillis requested review from KyleAMathews and kevin-dp September 11, 2025 18:01

expand useLiveQuery callback to support conditional queries and add…

24fccb5

…itional return types

samwillis force-pushed the samwillis/use-live-query-return-null branch from 8648213 to 24fccb5 Compare September 11, 2025 18:02

samwillis commented Sep 11, 2025

View reviewed changes

packages/react-db/src/useLiveQuery.ts Show resolved Hide resolved

samwillis requested a review from thruflo September 11, 2025 18:05

KyleAMathews approved these changes Sep 11, 2025

View reviewed changes

address review

13d9d0d

samwillis merged commit 65b078a into main Sep 18, 2025
6 checks passed

samwillis deleted the samwillis/use-live-query-return-null branch September 18, 2025 10:02

github-actions bot mentioned this pull request Sep 18, 2025

ci: Version Packages #569

Merged

KyleAMathews mentioned this pull request Oct 20, 2025

docs: document conditional queries and isUndefined/isNull functions #695

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

expand `useLiveQuery` callback to support conditional queries and additional return types#535

expand `useLiveQuery` callback to support conditional queries and additional return types#535
samwillis merged 2 commits intomainfrom
samwillis/use-live-query-return-null

samwillis commented Sep 11, 2025

Uh oh!

changeset-bot bot commented Sep 11, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Sep 11, 2025 •

edited

Loading

Uh oh!

Uh oh!

github-actions bot commented Sep 11, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Sep 11, 2025 •

edited

Loading

Uh oh!

KyleAMathews left a comment

Uh oh!

Uh oh!

Uh oh!

KyleAMathews Sep 11, 2025

Uh oh!

samwillis Sep 18, 2025

Uh oh!

KyleAMathews Sep 11, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

samwillis commented Sep 11, 2025

Uh oh!

changeset-bot bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

KyleAMathews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

KyleAMathews Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

samwillis Sep 18, 2025

Choose a reason for hiding this comment

Uh oh!

KyleAMathews Sep 11, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot bot commented Sep 11, 2025 •

edited

Loading

pkg-pr-new bot commented Sep 11, 2025 •

edited

Loading

github-actions bot commented Sep 11, 2025 •

edited

Loading

github-actions bot commented Sep 11, 2025 •

edited

Loading