fix(query-core): fall back to query's own staleTime in isStatic() when no observers exist

[waterWang]

fix(query-core): fall back to query's own staleTime in isStatic() when no observers exist

Description

staleTime: 'static' stops being honoured as soon as a query has no observers, so refetchQueries({ type: 'all' }) and invalidateQueries({ refetchType: 'all' }) re-run the queryFn for queries that the docs promise will never refetch.

Query.isStatic() derives 'static' only from live observers. When there are no observers, it returns false, contradicting the documented behaviour:

set staleTime to 'static' to never trigger a refetch, even if the Query is invalidated manually

The neighbouring isDisabled() method already handles the no-observer case correctly with an explicit fallback. This fix mirrors that pattern.

Changes

• packages/query-core/src/query.ts: When isStatic() has no observers, fall back to the query's own staleTime option instead of returning false.

Fix details

// Before: returns false when no observers
return false

// After: mirrors isDisabled's no-observer fallback pattern
return resolveStaleTime((this.options as any).staleTime, this) === 'static'

The as any cast is needed because staleTime is declared on QueryObserverOptions and FetchQueryOptions, not on the base QueryOptions interface — but the value is always present at runtime since Query.setOptions stores the full merged options object.

Test results

The fix is verified against the issue author's test cases:

• A: prefetchQuery, never observed → calls=1
• C: fetchQuery, never observed → calls=1
• D: observer subscribed then unmounted → calls=1
• E: non-static query → calls=2 (still refetches, no over-blocking)
• F: staleTime: Infinity → calls=2 (still invalidatable, per the documented distinction)

Full packages/query-core suite: 554 passed.

Fixes #11190

Summary by CodeRabbit

• Bug Fixes
  • Queries without active observers now correctly recognize when their configured stale time is set to “static.”

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 95f417eb-18ce-4c93-a0a7-c48d39f8131b

📥 Commits

Reviewing files that changed from the base of the PR and between 3f9d11b and ddf201f.

📒 Files selected for processing (1)

• packages/query-core/src/query.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

Query.isStatic() now uses the query’s configured staleTime when no observers exist. Unobserved queries with staleTime: 'static' are therefore recognized as static.

Changes

Static stale-time handling

Layer / File(s)	Summary
Unobserved query static check packages/query-core/src/query.ts	isStatic() now resolves the query-level staleTime when the query has no observers and returns whether it is 'static'.

Estimated code review effort: 2 (Simple) | ~5 minutes

Merge Risk: ⚪ Minimal · up to ddf20

The change restores the documented static stale-time behavior for unobserved queries without introducing any actionable merge-blocking risk; it is merge-ready after normal checks and review.

Possibly related PRs

• TanStack/query#11157: Both changes address static stale-time behavior for unobserved queries during refetch decisions.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the query-core fix and the no-observer staleTime fallback.
Description check	✅ Passed	The description explains the bug, implementation, motivation, affected file, linked issue, and test results; template checklist sections are omitted.
Linked Issues check	✅ Passed	The change directly addresses issue #11190 by honoring static staleTime for unobserved queries while preserving refetching for non-static and Infinity queries.
Out of Scope Changes check	✅ Passed	The three-line change is limited to Query.isStatic() and directly supports the linked issue objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}