diff --git a/docs/eslint/eslint-plugin-query.md b/docs/eslint/eslint-plugin-query.md index 847ccab665..73750c65d7 100644 --- a/docs/eslint/eslint-plugin-query.md +++ b/docs/eslint/eslint-plugin-query.md @@ -99,3 +99,4 @@ Alternatively, add `@tanstack/query` to the plugins section, and configure the r - [@tanstack/query/no-unstable-deps](../no-unstable-deps.md) - [@tanstack/query/infinite-query-property-order](../infinite-query-property-order.md) - [@tanstack/query/no-void-query-fn](../no-void-query-fn.md) +- [@tanstack/query/mutation-property-order](../mutation-property-order.md) diff --git a/docs/eslint/mutation-property-order.md b/docs/eslint/mutation-property-order.md new file mode 100644 index 0000000000..ceb3f0b354 --- /dev/null +++ b/docs/eslint/mutation-property-order.md @@ -0,0 +1,73 @@ +--- +id: mutation-property-order +title: Ensure correct order of inference-sensitive properties in useMutation() +--- + +For the following functions, the property order of the passed in object matters due to type inference: + +- `useMutation()` + +The correct property order is as follows: + +- `onMutate` +- `onError` +- `onSettled` + +All other properties are insensitive to the order as they do not depend on type inference. + +## Rule Details + +Examples of **incorrect** code for this rule: + +```tsx +/* eslint "@tanstack/query/mutation-property-order": "warn" */ +import { useMutation } from '@tanstack/react-query' + +const mutation = useMutation({ + mutationFn: () => Promise.resolve('success'), + onSettled: () => { + results.push('onSettled-promise') + return Promise.resolve('also-ignored') // Promise (should be ignored) + }, + onMutate: async () => { + results.push('onMutate-async') + await sleep(1) + return { backup: 'async-data' } + }, + onError: async () => { + results.push('onError-async-start') + await sleep(1) + results.push('onError-async-end') + }, +}) +``` + +Examples of **correct** code for this rule: + +```tsx +/* eslint "@tanstack/query/mutation-property-order": "warn" */ +import { useInfiniteQuery } from '@tanstack/react-query' + +const mutation = useMutation({ + mutationFn: () => Promise.resolve('success'), + onMutate: async () => { + results.push('onMutate-async') + await sleep(1) + return { backup: 'async-data' } + }, + onError: async () => { + results.push('onError-async-start') + await sleep(1) + results.push('onError-async-end') + }, + onSettled: () => { + results.push('onSettled-promise') + return Promise.resolve('also-ignored') // Promise (should be ignored) + }, +}) +``` + +## Attributes + +- [x] ✅ Recommended +- [x] 🔧 Fixable