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.

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

+}
+
+/**
+ * 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 ca3361dCompare October 31, 2025 20:07

KyleAMathews force-pushed the claude/add-query-observer-utils-011CUfe3K9sLFToVas2AHHh5 branch from ca3361d to f8fd37fCompare 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

Comment threadpackages/db/src/types.ts
Comment threadpackages/query-db-collection/src/query.ts Outdated

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

KyleAMathewsand 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 mainNov 5, 2025
6 checks passed

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

github-actionsBot 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

Navigation Menu

Uh oh!

Add QueryObserver state utility methods to QueryCollectionUtils - #742

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

KyleAMathews commented Oct 31, 2025•
edited
Loading

Uh oh!

changeset-botBot commented Oct 31, 2025•
edited
Loading

Uh oh!

pkg-pr-newBot commented Oct 31, 2025•
edited
Loading

Uh oh!

github-actionsBot commented Oct 31, 2025•
edited
Loading

Uh oh!

github-actionsBot commented Oct 31, 2025•
edited
Loading

Uh oh!

samwillis left a comment

Uh oh!

Uh oh!

Uh oh!

samwillis left a comment

Uh oh!

samwillisNov 5, 2025•
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

github-actionsBot 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!

samwillisNov 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

KyleAMathews commented Oct 31, 2025•
edited
Loading

changeset-botBot commented Oct 31, 2025•
edited
Loading

pkg-pr-newBot commented Oct 31, 2025•
edited
Loading

github-actionsBot commented Oct 31, 2025•
edited
Loading

github-actionsBot commented Oct 31, 2025•
edited
Loading

samwillisNov 5, 2025•
edited
Loading