feat: add exact refetch targeting and improve utils.refetch() behavior

[lucasweng]

Resolves #537

Summary

• Implemented exact query key targeting to prevent unintended cascading refetches of related queries
• Changed utils.refetch() to bypass enabled: false for imperative control (matches TanStack Query hook behavior)
• Returns QueryObserverResult from utils.refetch() for better DX
• Removed refetchType option - not needed with exact targeting via observer

Key Changes

1. Exact targeting: Uses queryObserver.refetch() which targets only this collection (no cascade)
2. Bypasses enabled: false: Supports manual fetch patterns like button-triggered fetches and error recovery via clearError()
3. Better return type: Returns QueryObserverResult instead of void so users can inspect the result
4. Simplified API: Removed refetchType since exact targeting via observer makes it unnecessary

Test Plan

• Tests pass locally
• Package builds successfully
• Added tests for clearError() exact targeting
• Added tests for throwOnError behavior
• Added test for enabled: false bypass

[changeset-bot]

🦋 Changeset detected

Latest commit: 401e7c7

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

This PR includes changesets to release 2 packages

Name	Type
@tanstack/query-db-collection	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]

More templates

• todos
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 401e7c7

[KyleAMathews]

Hey @lucasweng! Sorry for not getting to this for so long! I/we somehow missed it.

Thanks for tackling this issue. I reviewed your PR and made some refinements based on a careful analysis of the requirements and TanStack Query's behavior. Here's what changed:

Changes Made

1. Changed utils.refetch() to use queryObserver.refetch() instead of queryClient.refetchQueries()

This was the key insight: we need different behavior for imperative refetch vs batch refetch operations.

• Why: According to https://tanstack.com/query/latest/docs/framework/react/guides/disabling-queries, the hook's refetch() method bypasses
  enabled: false to support manual fetch patterns
• Benefit: Fixes clearError() which calls refetch() internally - it now works even when enabled: false
• Benefit: Supports the common "manual fetch on button click" pattern with enabled: false

2. Removed refetchType option

After discussion, we realized refetchType doesn't add value with exact targeting:

• With exact: true, we're already targeting just this specific collection (no cascade)
• Users always want their collection data refetched, whether from explicit utils.refetch() calls or after mutations
• The refetchType filter made sense for preventing cascades in batch operations, but with exact targeting it's unnecessary

3. Changed return type to QueryObserverResult

• Returns the query result instead of void so users can inspect the result
• Better DX and more aligned with hook behavior

4. Added more comprehensive tests

• Test for clearError() using exact targeting
• Test for throwOnError propagation
• Test for enabled: false bypass behavior

The Core Issue

The original issue was about preventing cascade refetches. Your solution with exact: true solved that perfectly! The additional changes ensure
that imperative refetch() calls work as users expect (bypassing enabled: false like hooks do).

Let me know if you have any questions about these changes!