Skip to content

Conversation

@shincurry
Copy link

@shincurry shincurry commented Jan 14, 2026

🎯 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

    • Added a mutationOptions helper to configure mutations with or without a key and improved TypeScript inference.
  • Documentation

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

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

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

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

@changeset-bot
Copy link

changeset-bot bot commented Jan 14, 2026

🦋 Changeset detected

Latest commit: 2210327

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

@github-actions github-actions bot added documentation Improvements or additions to documentation package: vue-query labels Jan 14, 2026
@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 14, 2026

📝 Walkthrough

Walkthrough

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

Changes

Cohort / File(s) Summary
Type system extensions
packages/vue-query/src/types.ts
Added 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
New mutationOptions function with three overloads (with/without mutationKey and concrete form); implementation is a pass-through for typing purposes.
API export & integration
packages/vue-query/src/index.ts, packages/vue-query/src/useMutation.ts
Exported mutationOptions from the package index; useMutation option type updated to MaybeRefDeepOrGetter<...> and import adjusted.
Type tests
packages/vue-query/src/__tests__/mutationOptions.test-d.ts
New comprehensive TypeScript-only tests asserting inference, generics, contextual types, negative checks, and interactions with related hooks.
Runtime tests
packages/vue-query/src/__tests__/mutationOptions.test.ts
New runtime tests (two cases) verifying identity/return of option objects with and without mutationKey.
Documentation
docs/framework/vue/reference/mutationOptions.md
Added reference doc describing 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

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

Poem

🐰 I nibble types and stitch them tight,
Getters and refs tucked just right,
mutationOptions hops on stage,
Tests and docs turn a tidy page,
A little rabbit cheers tonight! 🥕

🚥 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 directly describes the main change: introducing a new mutationOptions feature to vue-query.
Description check ✅ Passed The description follows the template with all required sections completed: Changes section lists new functionality, Checklist items are marked, and Release Impact confirms changeset generation.

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

✨ Finishing touches
  • 📝 Generate docstrings

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
Copy link

nx-cloud bot commented Jan 26, 2026

View your CI Pipeline Execution ↗ for commit 2210327

Command Status Duration Result
nx affected --targets=test:sherif,test:knip,tes... ✅ Succeeded 1m 23s View ↗
nx run-many --target=build --exclude=examples/*... ✅ Succeeded <1s View ↗

☁️ Nx Cloud last updated this comment at 2026-01-27 10:13:32 UTC

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

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),
-    })
+    }))

@pkg-pr-new
Copy link

pkg-pr-new bot commented Jan 26, 2026

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/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: 2210327

@sentry
Copy link

sentry bot commented Jan 26, 2026

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 13 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     
Components Coverage Δ
@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-query 33.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
Copy link
Author

shincurry commented Jan 27, 2026

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

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

Labels

documentation Improvements or additions to documentation package: vue-query

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant