feat(eslint-plugin): refactor and add mutation-property-order rule (#9191)

Co-authored-by: Dominik Dorfmeister <[email protected]>

Author: jochongs

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/__tests__/infinite-query-property-order.utils.test.ts renamed to packages/eslint-plugin-query/src/__tests__/sort-data-by-order.utils.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'vitest'
-import { sortDataByOrder } from '../rules/infinite-query-property-order/infinite-query-property-order.utils'
+import { sortDataByOrder } from '../utils/sort-data-by-order'
 
 describe('create-route-property-order utils', () => {
   describe('sortDataByOrder', () => {

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/infinite-query-property-order/constants.ts

@@ -12,6 +12,8 @@ export const checkedProperties = [
   'getNextPageParam',
 ] as const
 
+export type InfiniteQueryProperties = (typeof checkedProperties)[number]
+
 export const sortRules = [
   [['queryFn'], ['getPreviousPageParam', 'getNextPageParam']],
 ] as const