Add QueryObserver state utility methods to QueryCollectionUtils by KyleAMathews · Pull Request #742 · TanStack/db

KyleAMathews · 2025-10-31T19:56:12Z

Adds new utility methods to QueryCollectionUtils to expose TanStack Query's QueryObserver state, addressing user request for visibility into sync status:

New utils exposed:

isFetching() - Check if query is currently fetching (initial or background)
isRefetching() - Check if query is refetching in background
isLoading() - Check if query is loading for first time
dataUpdatedAt() - Get timestamp of last successful data update
fetchStatus() - Get current fetch status ('fetching' | 'paused' | 'idle')

This allows users to:

Show loading indicators during background refetches
Implement "Last updated X minutes ago" UI patterns
Understand sync behavior beyond just error states

Converted error state utilities from methods to getters:

lastError() → lastError
isError() → isError
errorCount() → errorCount

Resolves user request from Discord where status is always 'ready' after initial load, making it impossible to know if background refetches are happening.

changeset-bot · 2025-10-31T19:56:16Z

🦋 Changeset detected

Latest commit: 50c5d1a

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

This PR includes changesets to release 16 packages

Name	Type
@tanstack/query-db-collection	Minor
@tanstack/db	Patch
@tanstack/db-example-react-todo	Patch
@tanstack/db-example-solid-todo	Patch
@tanstack/angular-db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/offline-transactions	Patch
@tanstack/powersync-db-collection	Patch
@tanstack/react-db	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
todos	Patch
@tanstack/db-example-paced-mutations-demo	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-10-31T19:57:47Z

More templates

@tanstack/angular-db

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 3b4a50b

github-actions · 2025-10-31T20:00:38Z

Size Change: 0 B

Total Size: 79.1 kB

ℹ️ View Unchanged

Filename	Size
`./packages/db/dist/esm/collection/change-events.js`	1.34 kB
`./packages/db/dist/esm/collection/changes.js`	977 B
`./packages/db/dist/esm/collection/events.js`	388 B
`./packages/db/dist/esm/collection/index.js`	3.12 kB
`./packages/db/dist/esm/collection/indexes.js`	1.1 kB
`./packages/db/dist/esm/collection/lifecycle.js`	1.67 kB
`./packages/db/dist/esm/collection/mutations.js`	2.26 kB
`./packages/db/dist/esm/collection/state.js`	3.43 kB
`./packages/db/dist/esm/collection/subscription.js`	2.42 kB
`./packages/db/dist/esm/collection/sync.js`	2.02 kB
`./packages/db/dist/esm/deferred.js`	207 B
`./packages/db/dist/esm/errors.js`	3.9 kB
`./packages/db/dist/esm/event-emitter.js`	748 B
`./packages/db/dist/esm/index.js`	2.36 kB
`./packages/db/dist/esm/indexes/auto-index.js`	731 B
`./packages/db/dist/esm/indexes/base-index.js`	766 B
`./packages/db/dist/esm/indexes/btree-index.js`	1.87 kB
`./packages/db/dist/esm/indexes/lazy-index.js`	1.1 kB
`./packages/db/dist/esm/indexes/reverse-index.js`	513 B
`./packages/db/dist/esm/local-only.js`	837 B
`./packages/db/dist/esm/local-storage.js`	2.04 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.22 kB
`./packages/db/dist/esm/query/builder/functions.js`	606 B
`./packages/db/dist/esm/query/builder/index.js`	3.85 kB
`./packages/db/dist/esm/query/builder/ref-proxy.js`	917 B
`./packages/db/dist/esm/query/compiler/evaluators.js`	1.26 kB
`./packages/db/dist/esm/query/compiler/expressions.js`	674 B
`./packages/db/dist/esm/query/compiler/group-by.js`	1.78 kB
`./packages/db/dist/esm/query/compiler/index.js`	1.95 kB
`./packages/db/dist/esm/query/compiler/joins.js`	2 kB
`./packages/db/dist/esm/query/compiler/order-by.js`	1.17 kB
`./packages/db/dist/esm/query/compiler/select.js`	1.07 kB
`./packages/db/dist/esm/query/ir.js`	673 B
`./packages/db/dist/esm/query/live-query-collection.js`	360 B
`./packages/db/dist/esm/query/live/collection-config-builder.js`	5 kB
`./packages/db/dist/esm/query/live/collection-registry.js`	214 B
`./packages/db/dist/esm/query/live/collection-subscriber.js`	1.77 kB
`./packages/db/dist/esm/query/optimizer.js`	2.6 kB
`./packages/db/dist/esm/scheduler.js`	1.21 kB
`./packages/db/dist/esm/SortedMap.js`	1.18 kB
`./packages/db/dist/esm/strategies/debounceStrategy.js`	237 B
`./packages/db/dist/esm/strategies/queueStrategy.js`	418 B
`./packages/db/dist/esm/strategies/throttleStrategy.js`	236 B
`./packages/db/dist/esm/transactions.js`	2.9 kB
`./packages/db/dist/esm/utils.js`	881 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`	660 B
`./packages/db/dist/esm/utils/index-optimization.js`	1.49 kB
`./packages/db/dist/esm/utils/type-guards.js`	157 B

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

github-actions · 2025-10-31T20:01:14Z

Size Change: 0 B

Total Size: 3.34 kB

ℹ️ View Unchanged

Filename	Size
`./packages/react-db/dist/esm/index.js`	225 B
`./packages/react-db/dist/esm/useLiveInfiniteQuery.js`	1.17 kB
`./packages/react-db/dist/esm/useLiveQuery.js`	1.11 kB
`./packages/react-db/dist/esm/useLiveSuspenseQuery.js`	431 B
`./packages/react-db/dist/esm/usePacedMutations.js`	401 B

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

…tters Adds new utilities to expose TanStack Query's QueryObserver state: - isFetching: Check if query is currently fetching - isRefetching: Check if query is refetching in background - isLoading: Check if query is loading for first time - dataUpdatedAt: Timestamp of last successful data update - fetchStatus: Current fetch status ('fetching' | 'paused' | 'idle') BREAKING CHANGE: Error state utilities are now getters instead of methods: - collection.utils.lastError() → collection.utils.lastError - collection.utils.isError() → collection.utils.isError - collection.utils.errorCount() → collection.utils.errorCount

samwillis

Looking very good, much prefer this to the previous and the widening of the types for the utils.

Just a comment above on the class being a closure.

packages/db/src/types.ts

packages/query-db-collection/src/query.ts

Addresses PR feedback from samwillis: refactor QueryCollectionUtilsImpl class to be extracted outside the function scope with required state passed through the constructor instead of relying on closure patterns. This improves code architecture by making dependencies explicit and avoiding nested class definitions within functions. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Re-generate documentation after QueryCollectionUtilsImpl refactoring. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Regenerated all documentation files after running full build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

samwillis

Looks good.

Aside: it will create some merge conflicts with the query driven sync PR #763, hopefully not too painful, but to keep in mind.

samwillis · 2025-11-05T16:44:44Z

packages/query-db-collection/src/query.ts

+}
+
+/**
+ * Implementation class for QueryCollectionUtils that maintains proper closure


that maintains proper closure

its not a colure any more...

Update QueryCollectionUtilsImpl class comment to accurately reflect that it now uses explicit dependency injection instead of closure. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

KyleAMathews mentioned this pull request Oct 31, 2025

feat(query-db-collection): expose query state from QueryObserver #712

Closed

4 tasks

KyleAMathews force-pushed the claude/add-query-observer-utils-011CUfe3K9sLFToVas2AHHh5 branch from 2f89188 to ca3361d Compare October 31, 2025 20:07

KyleAMathews force-pushed the claude/add-query-observer-utils-011CUfe3K9sLFToVas2AHHh5 branch from ca3361d to f8fd37f Compare October 31, 2025 20:10

KyleAMathews added this to TanStack DB 1.0.0 release Nov 4, 2025

KyleAMathews moved this to Ready for review in TanStack DB 1.0.0 release Nov 4, 2025

samwillis requested changes Nov 5, 2025

View reviewed changes

packages/db/src/types.ts Show resolved Hide resolved

packages/query-db-collection/src/query.ts Outdated Show resolved Hide resolved

KyleAMathews requested a review from samwillis November 5, 2025 15:44

KyleAMathews and others added 4 commits November 5, 2025 08:45

Merge origin/main into claude/add-query-observer-utils

75aeb32

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

chore: Update generated docs

06f4c19

Re-generate documentation after QueryCollectionUtilsImpl refactoring. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

chore: Re-generate documentation after build

09be8e2

Regenerated all documentation files after running full build. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

Merge origin/main into claude/add-query-observer-utils

3b4a50b

🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>

samwillis approved these changes Nov 5, 2025

View reviewed changes

KyleAMathews merged commit 1367756 into main Nov 5, 2025
6 checks passed

KyleAMathews deleted the claude/add-query-observer-utils-011CUfe3K9sLFToVas2AHHh5 branch November 5, 2025 17:27

github-actions bot mentioned this pull request Nov 5, 2025

ci: Version Packages #767

Merged

KyleAMathews moved this from Ready for review to Done in TanStack DB 1.0.0 release Nov 13, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add QueryObserver state utility methods to QueryCollectionUtils#742

Add QueryObserver state utility methods to QueryCollectionUtils#742
KyleAMathews merged 7 commits intomainfrom
claude/add-query-observer-utils-011CUfe3K9sLFToVas2AHHh5

KyleAMathews commented Oct 31, 2025 •

edited

Loading

Uh oh!

changeset-bot bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

github-actions bot commented Oct 31, 2025 •

edited

Loading

Uh oh!

samwillis left a comment

Uh oh!

Uh oh!

Uh oh!

samwillis left a comment

Uh oh!

samwillis Nov 5, 2025 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

KyleAMathews commented Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Oct 31, 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 Oct 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

samwillis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

samwillis left a comment

Choose a reason for hiding this comment

Uh oh!

samwillis Nov 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

KyleAMathews commented Oct 31, 2025 •

edited

Loading

changeset-bot bot commented Oct 31, 2025 •

edited

Loading

pkg-pr-new bot commented Oct 31, 2025 •

edited

Loading

github-actions bot commented Oct 31, 2025 •

edited

Loading

github-actions bot commented Oct 31, 2025 •

edited

Loading

samwillis Nov 5, 2025 •

edited

Loading