fix(vue-query): fix queryOptions return type to expose all properties

[veeceey]

Summary

• Fix the queryOptions return type in vue-query to expose all query option properties (queryFn, staleTime, select, etc.) for direct access, not just queryKey and initialData
• Use Exclude<T, Ref | ComputedRef> to remove Ref/ComputedRef branches from the MaybeRef union in the return type, since queryOptions always returns a plain object
• Update useQueries type inference (GetUseQueryOptionsForUseQueries and GetUseQueryResult) to handle the new plain return type via DataTag-based matching
• Add type test verifying direct property access on queryOptions result

Fixes #7892

Details

The root cause was that UndefinedInitialQueryOptions and DefinedInitialQueryOptions are defined as MaybeRef<Inner> & { initialData }, where MaybeRef<T> = T | Ref<T> | ComputedRef<T>. When TypeScript resolves property access on this union type, it only shows properties common to all union members. Since Ref<T> only has .value and ComputedRef<T> only has .value/.effect, the common properties were limited to queryKey (from the & { queryKey } intersection) and initialData.

The fix uses Exclude<T, Ref<any> | ComputedRef<any>> (aliased as PlainQueryOptions<T>) in the queryOptions return type to strip the Ref and ComputedRef branches from the union. This is safe because queryOptions always accepts and returns plain objects, never Vue refs.

Test plan

• All existing queryOptions type tests pass (17 tests)
• New type test added: verifies options.queryFn and options.queryKey are accessible
• All useQueries type tests pass (8 tests)
• All useQuery type tests pass (18 tests)
• All runtime tests pass across Vue 2, 2.7, and 3
• TypeScript compatibility tests pass across TS 5.0 through 5.7

Summary by CodeRabbit

• Bug Fixes
  • Fixed the return type of queryOptions() to properly expose all query option properties (such as queryFn and staleTime) for direct access via dot notation, improving type inference and developer experience.

[changeset-bot]

🦋 Changeset detected

Latest commit: 551270e

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

This PR includes changesets to release 2 packages

Name	Type
@tanstack/vue-query	Patch
@tanstack/vue-query-devtools	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

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR fixes a TypeScript type issue in @tanstack/vue-query where the queryOptions() function's return type didn't expose query option properties like queryFn and staleTime. A new PlainQueryOptions type excludes Vue's Ref and ComputedRef branches to expose all query option properties for dot-notation access.

Changes

Cohort / File(s)	Summary
Type Definition Fix packages/vue-query/src/queryOptions.ts	Introduces PlainQueryOptions<T> type that excludes Ref and ComputedRef from union types, updating both DefinedInitialQueryOptions and UndefinedInitialQueryOptions overloads to expose all query properties.
Enhanced Type Inference packages/vue-query/src/useQueries.ts	Adds DataTag import and extends GetUseQueryOptionsForUseQueries and GetUseQueryResult type utilities to correctly handle plain query option objects with queryKey, applying consistent type unwrapping via DeepUnwrapRef.
Type Tests and Changelog packages/vue-query/src/__tests__/queryOptions.test-d.ts, .changeset/fix-vue-query-options-type.md	Adds type test assertions verifying queryFn and queryKey accessibility on returned options object, plus patch release changelog entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• TanStack/query#9914 — Modifies types and handling around Vue Query's query/options surface including updates to packages/vue-query/src/useQueries.ts and related option types

Suggested labels

package: vue-query

Suggested reviewers

• DamianOsipiuk

Poem

🐰 A query's secrets now revealed,
No more typing mysteries sealed!
PlainQueryOptions set them free—
queryFn and friends in harmony,
Vue-Query types now crystal clear,
TypeScript errors disappear! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely describes the main change: fixing the queryOptions return type to expose all properties, which directly addresses issue #7892.
Description check	✅ Passed	The PR description is comprehensive, including summary, technical details, root cause analysis, and test plan. All required checklist items are addressed (contributing guide followed and tests run locally).
Linked Issues check	✅ Passed	The changes fully address issue #7892 by fixing the queryOptions return type to expose all query option properties (queryFn, staleTime, etc.) through the PlainQueryOptions type and updating useQueries type inference accordingly.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to fixing the queryOptions return type issue: new PlainQueryOptions type, updated function signatures, type inference updates in useQueries, and corresponding type tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

No actionable comments were generated in the recent review. 🎉

---

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 and usage tips.}