Query mutation options in core

[benjavicente]

🎯 Changes

Adds queryOptions and mutationOptions to the core library.

This was requested at #10735 and #9258 discussions. Having those function in core is useful for defining shared query options for a framework agnostic layer, or for server side usage.

Most of the frameworks accept the shared interface from core without changes. The exception is Vue, that require a small change in the interface since MaybeRefOrGetterwasn't compatible. I added runtime test for Vue to demonstrate that it works with the core query options, with the same shape of () => coreOptions as Solid/Angular/Lit/Svelte.

About docs: There is a lot of outdated docs, so I excluded the doc generation in the PR. I didn't add docs mentioning that core has this new functions.

Pending questions:

• Is CoreQueryOptions and CoreMutationOptions ok names for the interface the new queryOptions and mutationOptions requires? The core library already has QueryOptions and MutationOptions. The new CoreQueryOptions and CoreMutationOptions are the equivalent of QueryOptions and MutationOptions exported by each individual adapter. The new types can't replace the base options alredy defined in core.
• Should CoreQueryOptions and CoreMutationOptions be excluded from the re-export from core? How? Each adapter exports queryOptions and mutationOptions, so a consumer can't import the implementation defined in core if the consumer hasn't installed @tanstack/query-core directly, but they can consume CoreQueryOptions and CoreMutationOptions.
• I'm not happy on how the useQuery interface of Vue had to be extended, there is probably something that can be done there to simplify the types.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

Release Notes

• New Features
  • Added framework-agnostic queryOptions and mutationOptions helpers for enhanced type inference and reusable query/mutation configurations across all supported frameworks.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2931dc9a-616e-44e1-a35c-56275db0d300

📥 Commits

Reviewing files that changed from the base of the PR and between 4f11927 and ff39c7b.

📒 Files selected for processing (22)

• .changeset/quiet-cooks-sparkle.md
• packages/angular-query-experimental/src/__tests__/mutation-options.test-d.ts
• packages/angular-query-experimental/src/__tests__/query-options.test-d.ts
• packages/lit-query/src/tests/type-inference.test.ts
• packages/preact-query/src/__tests__/mutationOptions.test-d.tsx
• packages/preact-query/src/__tests__/queryOptions.test-d.tsx
• packages/query-core/src/__tests__/mutationOptions.test-d.tsx
• packages/query-core/src/__tests__/queryOptions.test-d.tsx
• packages/query-core/src/index.ts
• packages/query-core/src/mutationOptions.ts
• packages/query-core/src/queryOptions.ts
• packages/react-query/src/__tests__/mutationOptions.test-d.tsx
• packages/react-query/src/__tests__/queryOptions.test-d.tsx
• packages/solid-query/src/__tests__/mutationOptions.test-d.tsx
• packages/solid-query/src/__tests__/queryOptions.test-d.tsx
• packages/svelte-query/tests/createQuery/createQuery.test-d.ts
• packages/svelte-query/tests/mutationOptions/mutationOptions.test-d.ts
• packages/vue-query/src/__tests__/mutationOptions.test-d.ts
• packages/vue-query/src/__tests__/queryOptions.test-d.ts
• packages/vue-query/src/__tests__/useQuery.test.ts
• packages/vue-query/src/useBaseQuery.ts
• packages/vue-query/src/useQuery.ts

---

📝 Walkthrough

Walkthrough

Adds framework-agnostic queryOptions and mutationOptions helper functions and their corresponding CoreQueryOptions/CoreMutationOptions types to @tanstack/query-core. Exports them from the package's public API, updates Vue Query's useBaseQuery/useQuery to accept options factories returning these core types, and validates cross-framework type inference in all adapter packages.

Changes

Framework-agnostic queryOptions and mutationOptions

Layer / File(s)	Summary
Core queryOptions and mutationOptions implementation packages/query-core/src/queryOptions.ts, packages/query-core/src/mutationOptions.ts, packages/query-core/src/index.ts, .changeset/quiet-cooks-sparkle.md	Introduces queryOptions.ts with three typed overloads (DefinedInitialDataOptions, UndefinedInitialDataOptions, UnusedSkipTokenOptions) merged into CoreQueryOptions, and mutationOptions.ts with CoreMutationOptions (omitting _defaulted) and three mutationKey-aware overloads. Both are no-op passthroughs at runtime. Re-exports all four public symbols from index.ts.
Core type-inference tests packages/query-core/src/__tests__/queryOptions.test-d.tsx, packages/query-core/src/__tests__/mutationOptions.test-d.tsx	New Vitest type-test suites covering DataTag propagation on queryKey, getQueryData/setQueryData type enforcement, initialData variants, skipToken behavior, mutationKey optionality, and _defaulted exclusion.
Vue Query integration packages/vue-query/src/useBaseQuery.ts, packages/vue-query/src/useQuery.ts	useBaseQuery parameter type is broadened to MaybeRefOrGetter<UseQueryOptionsGeneric> | (() => CoreQueryOptions) and internal options resolution is simplified to a conditional expression. useQuery overloads are rewritten to require an options factory () => CoreQueryOptions or () => DefinedCoreQueryOptions.
Vue Query tests packages/vue-query/src/__tests__/queryOptions.test-d.ts, packages/vue-query/src/__tests__/mutationOptions.test-d.ts, packages/vue-query/src/__tests__/useQuery.test.ts	Type tests assert that useQuery infers data from a coreQueryOptions getter, that direct (non-getter) core options are rejected, and that queryKey[dataTagSymbol] carries the result type. A runtime test validates reactive ref updates through coreQueryOptions.
Framework adapter type tests packages/react-query/src/__tests__/..., packages/angular-query-experimental/src/__tests__/..., packages/solid-query/src/__tests__/..., packages/preact-query/src/__tests__/..., packages/svelte-query/tests/..., packages/lit-query/src/tests/...	Adds coreMutationOptions/coreQueryOptions import aliases and new type-inference test cases across all adapters, each verifying that passing core option objects into the framework-specific hooks infers correct data, variables, and mutate types.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• TanStack/query#9914: Modifies useBaseQuery/useQuery in Vue Query to accept options as getter functions (options: () => ...), which directly overlaps with the Vue integration changes in this PR.

Suggested labels

package: query-core, package: react-query, package: preact-query, package: vue-query

Suggested reviewers

• TkDodo

🐇 A hop and a skip, the options now core,
queryOptions and mutationOptions — framework-free, what's more!
Each adapter gets tagged keys, typed to the brim,
No _defaulted sneaking in on a whim.
The bunny types safely, all inferences true,
🎉 One helper to share them — for me and for you!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Query mutation options in core' accurately describes the main change—adding queryOptions and mutationOptions helpers to the core library.
Description check	✅ Passed	The description thoroughly covers the changes, motivation, implementation details, testing, and open questions. All required sections are addressed with sufficient detail.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

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

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