feat(eslint-plugin): add mutation-property-order rule and tests

packages/eslint-plugin-query/src/__tests__/mutation-property-order.rule.test.ts

@@ -0,0 +1,218 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import combinate from 'combinate'
+
+import {
+  checkedProperties,
+  mutationFunctions,
+} from '../rules/mutation-property-order/constants'
+import {
+  name,
+  rule,
+} from '../rules/mutation-property-order/mutation-property-order.rule'
+import {
+  generateInterleavedCombinations,
+  generatePartialCombinations,
+  generatePermutations,
+  normalizeIndent,
+} from './test-utils'
+import type { MutationFunctions } from '../rules/mutation-property-order/constants'
+
+const ruleTester = new RuleTester()
+
+type CheckedProperties = (typeof checkedProperties)[number]
+const orderIndependentProps = [
+  'gcTime',
+  '...objectExpressionSpread',
+  '...callExpressionSpread',
+  '...memberCallExpressionSpread',
+] as const
+type OrderIndependentProps = (typeof orderIndependentProps)[number]
+
+interface TestCase {
+  mutationFunction: MutationFunctions
+  properties: Array<CheckedProperties | OrderIndependentProps>
+}
+
+const validTestMatrix = combinate({
+  mutationFunction: [...mutationFunctions],
+  properties: generatePartialCombinations(checkedProperties, 2),
+})
+
+export function generateInvalidPermutations(
+  arr: ReadonlyArray<CheckedProperties>,
+): Array<{
+  invalid: Array<CheckedProperties>
+  valid: Array<CheckedProperties>
+}> {
+  const combinations = generatePartialCombinations(arr, 2)
+  const allPermutations: Array<{
+    invalid: Array<CheckedProperties>
+    valid: Array<CheckedProperties>
+  }> = []
+
+  for (const combination of combinations) {
+    const permutations = generatePermutations(combination)
+    // skip the first permutation as it matches the original combination
+    const invalidPermutations = permutations.slice(1)
+
+    if (combination.includes('onError') && combination.includes('onSettled')) {
+      if (combination.indexOf('onError') < combination.indexOf('onSettled')) {
+        // since we ignore the relative order of 'onError' and 'onSettled', we skip this combination (but keep the other one where `onSettled` is before `onError`)
+
+        continue
+      }
+    }
+
+    allPermutations.push(
+      ...invalidPermutations
+        .map((p) => {
+          // ignore the relative order of 'onError' and 'onSettled'
+          const correctedValid = [...combination].sort((a, b) => {
+            if (
+              (a === 'onSettled' && b === 'onError') ||
+              (a === 'onError' && b === 'onSettled')
+            ) {
+              return p.indexOf(a) - p.indexOf(b)
+            }
+            return checkedProperties.indexOf(a) - checkedProperties.indexOf(b)
+          })
+          return { invalid: p, valid: correctedValid }
+        })
+        .filter(
+          ({ invalid }) =>
+            // if `onError` and `onSettled` are next to each other and `onMutate` is not present, we skip this invalid permutation
+            Math.abs(
+              invalid.indexOf('onSettled') - invalid.indexOf('onError'),
+            ) !== 1,
+        ),
+    )
+  }
+
+  return allPermutations
+}
+
+const invalidPermutations = generateInvalidPermutations(checkedProperties)
+
+type Interleaved = CheckedProperties | OrderIndependentProps
+const interleavedInvalidPermutations: Array<{
+  invalid: Array<Interleaved>
+  valid: Array<Interleaved>
+}> = []
+for (const invalidPermutation of invalidPermutations) {
+  const invalid = generateInterleavedCombinations(
+    invalidPermutation.invalid,
+    orderIndependentProps,
+  )
+  const valid = generateInterleavedCombinations(
+    invalidPermutation.valid,
+    orderIndependentProps,
+  )
+
+  for (let i = 0; i < invalid.length; i++) {
+    interleavedInvalidPermutations.push({
+      invalid: invalid[i]!,
+      valid: valid[i]!,
+    })
+  }
+}
+
+const invalidTestMatrix = combinate({
+  mutationFunction: [...mutationFunctions],
+  properties: interleavedInvalidPermutations,
+})
+
+const callExpressionSpread = normalizeIndent`
+        ...mutationOptions({
+            onSuccess: () => {},
+            retry: 3,
+        })`
+
+function getCode({ mutationFunction: mutationFunction, properties }: TestCase) {
+  function getPropertyCode(
+    property: CheckedProperties | OrderIndependentProps,
+  ) {
+    switch (property) {
+      case '...objectExpressionSpread':
+        return `...objectExpressionSpread`
+      case '...callExpressionSpread':
+        return callExpressionSpread
+      case '...memberCallExpressionSpread':
+        return '...myOptions.mutationOptions()'
+      case 'gcTime':
+        return 'gcTime: 5 * 60 * 1000'
+      case 'onMutate':
+        return 'onMutate: (data) => {\n return { foo: data }\n}'
+      case 'onError':
+        return 'onError: (error, variables, context) => {\n  console.log("error:", error, "context:", context)\n}'
+      case 'onSettled':
+        return 'onSettled: (data, error, variables, context) => {\n  console.log("settled", context)\n}'
+    }
+  }
+  return `
+    import { ${mutationFunction} } from '@tanstack/react-query'
+
+    ${mutationFunction}({
+        ${properties.map(getPropertyCode).join(',\n        ')}
+    })
+  `
+}
+
+const validTestCases = validTestMatrix.map(
+  ({ mutationFunction, properties }) => ({
+    name: `should pass when order is correct for ${mutationFunction} with order: ${properties.join(', ')}`,
+    code: getCode({
+      mutationFunction: mutationFunction,
+      properties,
+    }),
+  }),
+)
+
+const invalidTestCases = invalidTestMatrix.map(
+  ({ mutationFunction, properties }) => ({
+    name: `incorrect property order id detected for ${mutationFunction} with invalid order: ${properties.invalid.join(', ')}, valid order ${properties.valid.join(', ')}`,
+    code: getCode({
+      mutationFunction: mutationFunction,
+      properties: properties.invalid,
+    }),
+    errors: [{ messageId: 'invalidOrder' }],
+    output: getCode({
+      mutationFunction: mutationFunction,
+      properties: properties.valid,
+    }),
+  }),
+)
+
+ruleTester.run(name, rule, {
+  valid: validTestCases,
+  invalid: invalidTestCases,
+})
+
+const regressionTestCases = {
+  valid: [
+    {
+      name: 'should pass with call expression spread in useMutation',
+      code: normalizeIndent`
+      import { useMutation } from '@tanstack/react-query'
+
+      const { mutate } = useMutation({
+        ...mutationOptions({
+          retry: 3,
+          onSuccess: () => console.log('success'),
+        }),
+        onMutate: (data) => {
+          return { foo: data }
+        },
+        onError: (error, variables, context) => {
+          console.log(error, context)
+        },
+        onSettled: (data, error, variables, context) => {
+          console.log('settled', context)
+        },
+      })
+      `,
+    },
+  ],
+  invalid: [],
+}
+
+ruleTester.run(name, rule, regressionTestCases)

packages/eslint-plugin-query/src/index.ts

@@ -31,6 +31,7 @@ Object.assign(plugin.configs, {
       '@tanstack/query/no-unstable-deps': 'error',
       '@tanstack/query/infinite-query-property-order': 'error',
       '@tanstack/query/no-void-query-fn': 'error',
+      '@tanstack/query/mutation-property-order': 'error',
     },
   },
   'flat/recommended': [
@@ -46,6 +47,7 @@ Object.assign(plugin.configs, {
         '@tanstack/query/no-unstable-deps': 'error',
         '@tanstack/query/infinite-query-property-order': 'error',
         '@tanstack/query/no-void-query-fn': 'error',
+        '@tanstack/query/mutation-property-order': 'error',
       },
     },
   ],

packages/eslint-plugin-query/src/rules.ts

@@ -4,6 +4,7 @@ import * as noRestDestructuring from './rules/no-rest-destructuring/no-rest-dest
 import * as noUnstableDeps from './rules/no-unstable-deps/no-unstable-deps.rule'
 import * as infiniteQueryPropertyOrder from './rules/infinite-query-property-order/infinite-query-property-order.rule'
 import * as noVoidQueryFn from './rules/no-void-query-fn/no-void-query-fn.rule'
+import * as mutationPropertyOrder from './rules/mutation-property-order/mutation-property-order.rule'
 import type { ESLintUtils } from '@typescript-eslint/utils'
 import type { ExtraRuleDocs } from './types'
 
@@ -22,4 +23,5 @@ export const rules: Record<
   [noUnstableDeps.name]: noUnstableDeps.rule,
   [infiniteQueryPropertyOrder.name]: infiniteQueryPropertyOrder.rule,
   [noVoidQueryFn.name]: noVoidQueryFn.rule,
+  [mutationPropertyOrder.name]: mutationPropertyOrder.rule,
 }

packages/eslint-plugin-query/src/rules/mutation-property-order/constants.ts

@@ -0,0 +1,7 @@
+export const mutationFunctions = ['useMutation'] as const
+
+export type MutationFunctions = (typeof mutationFunctions)[number]
+
+export const checkedProperties = ['onMutate', 'onError', 'onSettled'] as const
+
+export const sortRules = [[['onMutate'], ['onError', 'onSettled']]] as const

packages/eslint-plugin-query/src/rules/mutation-property-order/mutation-property-order.rule.ts

@@ -0,0 +1,108 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackQueryImports } from '../../utils/detect-react-query-imports'
+import { sortDataByOrder } from './mutation-property-order.utils'
+import { mutationFunctions, sortRules } from './constants'
+import type { MutationFunctions } from './constants'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const mutationFunctionsSet = new Set(mutationFunctions)
+function isMutationFunction(node: any): node is MutationFunctions {
+  return mutationFunctionsSet.has(node)
+}
+
+export const name = 'mutation-property-order'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure correct order of inference-sensitive properties in useMutation()',
+      recommended: 'error',
+    },
+    messages: {
+      invalidOrder: 'Invalid order of properties for `{{function}}`.',
+    },
+    schema: [],
+    hasSuggestions: true,
+    fixable: 'code',
+  },
+  defaultOptions: [],
+
+  create: detectTanstackQueryImports((context) => {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== AST_NODE_TYPES.Identifier) {
+          return
+        }
+        const mutationFunction = node.callee.name
+        if (!isMutationFunction(mutationFunction)) {
+          return
+        }
+        const argument = node.arguments[0]
+        if (argument === undefined || argument.type !== 'ObjectExpression') {
+          return
+        }
+
+        const allProperties = argument.properties
+
+        // no need to sort if there is at max 1 property
+        if (allProperties.length < 2) {
+          return
+        }
+
+        const properties = allProperties.flatMap((p, index) => {
+          if (
+            p.type === AST_NODE_TYPES.Property &&
+            p.key.type === AST_NODE_TYPES.Identifier
+          ) {
+            return { name: p.key.name, property: p }
+          } else return { name: `_property_${index}`, property: p }
+        })
+
+        const sortedProperties = sortDataByOrder(properties, sortRules, 'name')
+        if (sortedProperties === null) {
+          return
+        }
+
+        context.report({
+          node: argument,
+          data: { function: node.callee.name },
+          messageId: 'invalidOrder',
+          fix(fixer) {
+            const sourceCode = context.sourceCode
+
+            const reorderedText = sortedProperties.reduce(
+              (sourceText, specifier, index) => {
+                let textBetweenProperties = ''
+                if (index < allProperties.length - 1) {
+                  textBetweenProperties = sourceCode
+                    .getText()
+                    .slice(
+                      allProperties[index]!.range[1],
+                      allProperties[index + 1]!.range[0],
+                    )
+                }
+                return (
+                  sourceText +
+                  sourceCode.getText(specifier.property) +
+                  textBetweenProperties
+                )
+              },
+              '',
+            )
+            return fixer.replaceTextRange(
+              [allProperties[0]!.range[0], allProperties.at(-1)!.range[1]],
+              reorderedText,
+            )
+          },
+        })
+      },
+    }
+  }),
+})