Skip to content

feat(vue-query): Add mutationOptions - #10036

Closed
shincurry wants to merge 9 commits into
TanStack:mainfrom
shincurry:vue-mutation-options
Closed

feat(vue-query): Add mutationOptions#10036
shincurry wants to merge 9 commits into
TanStack:mainfrom
shincurry:vue-mutation-options

Conversation

@shincurry

@shincurryshincurry commented Jan 14, 2026

Copy link
Copy Markdown

🎯 Changes

  • New method mutationOptions
  • New type helpers: DeepUnwrapRefOrGetter, MaybeRefDeepOrGetter
  • New tests for mutationOptions (Generated by Claude Opus 4.5, reviewed by @shincurry)
  • New docs for mutationOptions (Copied from react-query)

✅ 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

    • Introduced a mutationOptions helper to standardize mutation configuration and improve TypeScript inference.
  • Documentation

    • Added a reference page with usage examples and options guidance for mutationOptions.
  • Tests

    • Added extensive type and runtime tests validating mutationOptions and its interaction with mutation-related hooks.
  • Chores

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

@changeset-bot

changeset-botBot commented Jan 14, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 4f516be

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

This PR includes changesets to release 2 packages
NameType
@tanstack/vue-queryMinor
@tanstack/vue-query-devtoolsMajor

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

@github-actionsgithub-actionsBot added documentation Improvements or additions to documentation package: vue-query labels Jan 14, 2026
@coderabbitai

coderabbitaiBot commented Jan 14, 2026

Copy link
Copy Markdown
Contributor

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

Adds getter-aware typing utilities and a new type-level helper mutationOptions, updates useMutation to accept getter/ref-wrapped options, exports mutationOptions, adds docs and a changeset, and introduces comprehensive TypeScript and minimal runtime tests.

Changes

Cohort / File(s)Summary
Type system extensions
packages/vue-query/src/types.ts
Add MaybeRefDeepOrGetter<T> and DeepUnwrapRefOrGetter<T> to support getter-returned maybe-ref-deep values and proper deep-unwrapping for typing.
Core API helper
packages/vue-query/src/mutationOptions.ts
Add mutationOptions with three overloads (required mutationKey, omitted mutationKey, and concrete form); implementation is an identity pass-through for typing.
API export & integration
packages/vue-query/src/index.ts, packages/vue-query/src/useMutation.ts
Export mutationOptions from the package index; update useMutation option type to MaybeRefDeepOrGetter<...> and adjust imports.
Type tests
packages/vue-query/src/__tests__/mutationOptions.test-d.ts
Add comprehensive TypeScript-only tests verifying inference, generics, contextual types, negative checks, and interactions with related hooks.
Runtime tests
packages/vue-query/src/__tests__/mutationOptions.test.ts
Add two runtime tests ensuring option objects are returned unchanged (with and without mutationKey).
Documentation
docs/framework/vue/reference/mutationOptions.md
Add reference doc describing mutationOptions usage and linking to useMutation options.
Changeset
.changeset/lucky-numbers-change.md
Add changeset recording a minor bump and the mutationOptions feature.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 I nibble types and stitch them tight,
Getters and refs tucked neat and right,
mutationOptions hops into view,
Tests and docs sing something new,
A tiny rabbit claps tonight! 🥕

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check nameStatusExplanationResolution
Docstring Coverage⚠️ WarningDocstring 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 nameStatusExplanation
Title check✅ PassedThe title clearly and concisely describes the main change: adding a mutationOptions feature to vue-query.
Description check✅ PassedThe description follows the template structure with all required sections completed: Changes section lists new features, Checklist items are marked appropriately, and Release Impact indicates a changeset was generated.

✏️ 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

Comment @coderabbitai help to get the list of available commands and usage tips.

@shincurry
shincurry marked this pull request as draft January 14, 2026 07:25
@shincurry
shincurry marked this pull request as ready for review January 14, 2026 08:43
@nx-cloud

nx-cloudBot commented Jan 26, 2026

Copy link
Copy Markdown

View your CI Pipeline Execution ↗ for commit 6abcbfb

CommandStatusDurationResult
nx affected --targets=test:sherif,test:knip,tes...✅ Succeeded1m 26sView ↗
nx run-many --target=build --exclude=examples/*...✅ Succeeded<1sView ↗

☁️ Nx Cloud last updated this comment at 2026-03-01 17:02:22 UTC

@coderabbitaicoderabbitaiBot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@packages/vue-query/src/__tests__/mutationOptions.test.ts`:
- Around line 1-11: The test imports onScopeDispose from vue-demi but never
mocks it, so casting it to MockedFunction and calling mockImplementation will
throw; add a vi.mock for 'vue-demi' that provides onScopeDispose as a
jest/vitest mock function (e.g., onScopeDispose: vi.fn()) and ensure the mock is
registered before the test uses the imported onScopeDispose (place the vi.mock
call at the top of the test file or adjust imports so the mock is applied prior
to importing onScopeDispose) so the test can call mockImplementation on
onScopeDispose safely.
🧹 Nitpick comments (2)
packages/vue-query/src/__tests__/mutationOptions.test.ts (2)

262-263: Test descriptions are misleading.

These tests verify mutation state data (e.g., mutationStateArray[0]?.data), not "the number of fetching mutations." Consider updating the descriptions to accurately reflect what's being tested, e.g., "should return mutation states when used with useMutationState."


379-407: Test doesn't exercise mutationOptions functionality.

This test uses useMutation directly without calling mutationOptions. It appears to test the disposal behavior of useMutation/useIsMutating, which may be better suited in useMutation.test.ts or useMutationState.test.ts.

If the intent is to test mutationOptions integration with disposal, consider using mutationOptions in the test setup:

- const mutation = useMutation({+ const mutation = useMutation(mutationOptions({
mutationFn: (params: string) => sleep(0).then(() => params),
- })+ }))

Comment threadpackages/vue-query/src/__tests__/mutationOptions.test.ts Outdated
@pkg-pr-new

pkg-pr-newBot commented Jan 26, 2026

Copy link
Copy Markdown
More templates

@tanstack/angular-query-experimental

npm i https://pkg.pr.new/@tanstack/angular-query-experimental@10036

@tanstack/eslint-plugin-query

npm i https://pkg.pr.new/@tanstack/eslint-plugin-query@10036

@tanstack/preact-query

npm i https://pkg.pr.new/@tanstack/preact-query@10036

@tanstack/query-async-storage-persister

npm i https://pkg.pr.new/@tanstack/query-async-storage-persister@10036

@tanstack/query-broadcast-client-experimental

npm i https://pkg.pr.new/@tanstack/query-broadcast-client-experimental@10036

@tanstack/query-core

npm i https://pkg.pr.new/@tanstack/query-core@10036

@tanstack/query-devtools

npm i https://pkg.pr.new/@tanstack/query-devtools@10036

@tanstack/query-persist-client-core

npm i https://pkg.pr.new/@tanstack/query-persist-client-core@10036

@tanstack/query-sync-storage-persister

npm i https://pkg.pr.new/@tanstack/query-sync-storage-persister@10036

@tanstack/react-query

npm i https://pkg.pr.new/@tanstack/react-query@10036

@tanstack/react-query-devtools

npm i https://pkg.pr.new/@tanstack/react-query-devtools@10036

@tanstack/react-query-next-experimental

npm i https://pkg.pr.new/@tanstack/react-query-next-experimental@10036

@tanstack/react-query-persist-client

npm i https://pkg.pr.new/@tanstack/react-query-persist-client@10036

@tanstack/solid-query

npm i https://pkg.pr.new/@tanstack/solid-query@10036

@tanstack/solid-query-devtools

npm i https://pkg.pr.new/@tanstack/solid-query-devtools@10036

@tanstack/solid-query-persist-client

npm i https://pkg.pr.new/@tanstack/solid-query-persist-client@10036

@tanstack/svelte-query

npm i https://pkg.pr.new/@tanstack/svelte-query@10036

@tanstack/svelte-query-devtools

npm i https://pkg.pr.new/@tanstack/svelte-query-devtools@10036

@tanstack/svelte-query-persist-client

npm i https://pkg.pr.new/@tanstack/svelte-query-persist-client@10036

@tanstack/vue-query

npm i https://pkg.pr.new/@tanstack/vue-query@10036

@tanstack/vue-query-devtools

npm i https://pkg.pr.new/@tanstack/vue-query-devtools@10036

commit: fc3a74b

@sentry

sentryBot commented Jan 26, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 2.73973% with 71 lines in your changes missing coverage. Please review.
✅ Project coverage is 33.42%. Comparing base (bf7f47e) to head (2210327).
⚠️ Report is 54 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@ Coverage Diff @@## main #10036 +/- ##
===========================================
- Coverage 45.84% 33.42% -12.43% 
===========================================
Files 200 28 -172 Lines 8526 1071 -7455 Branches 1972 177 -1795 ===========================================
- Hits 3909 358 -3551 + Misses 4157 657 -3500 + Partials 460 56 -404 
ComponentsCoverage Δ
@tanstack/angular-query-experimental∅ <ø> (∅)
@tanstack/eslint-plugin-query∅ <ø> (∅)
@tanstack/query-async-storage-persister∅ <ø> (∅)
@tanstack/query-broadcast-client-experimental∅ <ø> (∅)
@tanstack/query-codemods∅ <ø> (∅)
@tanstack/query-core∅ <ø> (∅)
@tanstack/query-devtools∅ <ø> (∅)
@tanstack/query-persist-client-core∅ <ø> (∅)
@tanstack/query-sync-storage-persister∅ <ø> (∅)
@tanstack/query-test-utils∅ <ø> (∅)
@tanstack/react-query∅ <ø> (∅)
@tanstack/react-query-devtools∅ <ø> (∅)
@tanstack/react-query-next-experimental∅ <ø> (∅)
@tanstack/react-query-persist-client∅ <ø> (∅)
@tanstack/solid-query∅ <ø> (∅)
@tanstack/solid-query-devtools∅ <ø> (∅)
@tanstack/solid-query-persist-client∅ <ø> (∅)
@tanstack/svelte-query∅ <ø> (∅)
@tanstack/svelte-query-devtools∅ <ø> (∅)
@tanstack/svelte-query-persist-client∅ <ø> (∅)
@tanstack/vue-query33.42% <2.73%> (-38.50%)⬇️
@tanstack/vue-query-devtools∅ <ø> (∅)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@shincurry

shincurry commented Jan 27, 2026

Copy link
Copy Markdown
Author

Why doesn't test coverage exclude the test files themselves? 🤔

coverage: {enabled: true,provider: 'istanbul',include: ['src/**/*']},

https://app.codecov.io/gh/TanStack/query/pull/10036/blob/packages/vue-query/src/__tests__/mutationOptions.test-d.ts

Comment threaddocs/framework/vue/reference/mutationOptions.md
mutationFn: () => sleep(10).then(() => 5),
} as const

expect(mutationOptions(object)).toStrictEqual(object)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
expect(mutationOptions(object)).toStrictEqual(object)
expect(mutationOptions(object)).toBe(object)

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe mutationOptions is merely a type-check helper function; therefore, tests should guarantee the referential identity of object instances and ensure that the internal data remains unchanged.

Perhaps we should use both toBe and toStrictEqual.

mutationFn: () => sleep(10).then(() => 5),
} as const

expect(mutationOptions(object)).toStrictEqual(object)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
expect(mutationOptions(object)).toStrictEqual(object)
expect(mutationOptions(object)).toBe(object)

@TkDodo

Copy link
Copy Markdown
Collaborator

@DamianOsipiuk could you have a look here please 🙏

@shincurry
shincurryforce-pushed the vue-mutation-options branch from 4f516be to da4f339CompareMarch 27, 2026 05:20
@DamianOsipiuk

Copy link
Copy Markdown
Contributor

@shincurry

Copy link
Copy Markdown
Author

6

Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentationImprovements or additions to documentationpackage: vue-query

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

@shincurry@TkDodo@DamianOsipiuk