feat(vue-query): Add mutationOptions

[shincurry]

🎯 Changes

• New method mutationOptions
• New type helpers: DeepUnwrapRefOrGetter, MaybeRefDeepOrGetter
• New tests for mutationOptions
• New docs for mutationOptions

✅ 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

• New Features

  • Added a new mutationOptions helper to improve type inference and validation when configuring mutations, with support for optional and required mutation keys.

• Documentation

  • Added a reference page with usage examples and supported configuration options.

• Tests

  • Added extensive type and runtime tests covering mutationOptions and related mutation hooks.

• Chores

  • Exposed mutationOptions in the public API and refined related type utilities.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[changeset-bot]

🦋 Changeset detected

Latest commit: a04bdff

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	Minor
@tanstack/vue-query-devtools	Major

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

Adds a new type-level helper mutationOptions to @tanstack/vue-query, new type utilities to support option getters, updates useMutation typings to use the getter-aware types, adds public export and docs, and introduces comprehensive TypeScript and runtime tests validating typing and runtime interactions (useIsMutating, useMutationState).

Changes

Cohort / File(s)	Summary
Type system extensions packages/vue-query/src/types.ts	Added MaybeRefDeepOrGetter<T> and DeepUnwrapRefOrGetter<T> to support getters that return maybe-ref-deep values and to unwrap function-returned refs for typing.
Core implementation packages/vue-query/src/mutationOptions.ts	New mutationOptions function with three overloads to accept getter/ref-wrapped UseMutationOptions (with or without mutationKey) and return the same shape; runtime implementation is a pass-through.
API export & integration packages/vue-query/src/index.ts, packages/vue-query/src/useMutation.ts	Exported mutationOptions from the package index. Updated useMutation to use MaybeRefDeepOrGetter (replacing the prior union) for its UseMutationOptions type.
Type tests packages/vue-query/src/__tests__/mutationOptions.test-d.ts	New TypeScript-only tests asserting type inference, generics, context propagation, negative checks, and interactions with useMutation/useIsMutating/useMutationState.
Runtime tests packages/vue-query/src/__tests__/mutationOptions.test.ts	New runtime tests covering identity behavior, concurrent mutation counting, filtering by mutationKey, useMutationState emissions, scope disposal, and coordination with queryClient.isMutating.
Documentation docs/framework/vue/reference/mutationOptions.md	New reference doc explaining mutationOptions usage and linking to useMutation options.
Changeset .changeset/lucky-numbers-change.md	New changeset recording a minor bump and describing the mutationOptions feature.

Sequence Diagram(s)

(Skipped — changes are primarily type-level additions, API export, and tests; no new multi-component runtime control flow requiring visualization.)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• feat(vue-query): allow options getters in additional composables #9914 — Adds options-getter support and getter-aware types; closely related to the new MaybeRefDeepOrGetter/DeepUnwrapRefOrGetter changes.
• fix(types): onMutateResult is always defined in onSuccess callback #9677 — Changes mutation option typing and inference for onMutate/onSuccess; intersects with mutationOptions type behavior.
• feat(vue-query): support useQuery options getter #9866 — Introduces options getter support for vue-query hooks (query-related); similar getter-aware typing updates and patterns.

Poem

🐰 I nibble types and stitch them tight,
Getters and refs snug in sight,
mutationOptions hops into view,
Tests and docs say "how do you do?",
A tiny rabbit cheers for you! ✨

🚥 Pre-merge checks | ✅ 2 | ❌ 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 (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding a new mutationOptions feature to vue-query.
Description check	✅ Passed	The description follows the template, lists all major changes, and confirms checklist items and changeset generation.

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

---

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fe97419 and a04bdff.

📒 Files selected for processing (1)

• .changeset/lucky-numbers-change.md

🧰 Additional context used

🧠 Learnings (2)

📓 Common learnings

Learnt from: DogPawHat
Repo: TanStack/query PR: 9835
File: packages/query-core/src/__tests__/queryClient.test-d.tsx:242-256
Timestamp: 2025-11-02T22:52:33.071Z
Learning: In the TanStack Query codebase, the new `query` and `infiniteQuery` methods support the `select` option for data transformation, while the legacy `fetchQuery` and `fetchInfiniteQuery` methods do not support `select` and should reject it at the type level.

📚 Learning: 2025-11-02T22:52:33.071Z

Learnt from: DogPawHat
Repo: TanStack/query PR: 9835
File: packages/query-core/src/__tests__/queryClient.test-d.tsx:242-256
Timestamp: 2025-11-02T22:52:33.071Z
Learning: In the TanStack Query codebase, the new `query` and `infiniteQuery` methods support the `select` option for data transformation, while the legacy `fetchQuery` and `fetchInfiniteQuery` methods do not support `select` and should reject it at the type level.

Applied to files:

• .changeset/lucky-numbers-change.md

🔇 Additional comments (1)

.changeset/lucky-numbers-change.md (1)

1-5: LGTM! Changeset correctly documents the feature addition.

The changeset properly declares a minor version bump for adding the new mutationOptions functionality to @tanstack/vue-query. The format is correct and the version type is appropriate for this additive change.

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

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.}