@tanstack/eslint-plugin-query 5.56.1 → 5.57.1

package/dist/esm/rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"rules.js","sources":["../../src/rules.ts"],"sourcesContent":["import * as exhaustiveDeps from './rules/exhaustive-deps/exhaustive-deps.rule'\nimport * as stableQueryClient from './rules/stable-query-client/stable-query-client.rule'\nimport * as noRestDestructuring from './rules/no-rest-destructuring/no-rest-destructuring.rule'\nimport * as noUnstableDeps from './rules/no-unstable-deps/no-unstable-deps.rule'\nimport type { ESLintUtils } from '@typescript-eslint/utils'\nimport type { ExtraRuleDocs } from './types'\n\nexport const rules: Record<\n  string,\n  ESLintUtils.RuleModule<\n    string,\n    ReadonlyArray<unknown>,\n    ExtraRuleDocs,\n    ESLintUtils.RuleListener\n  >\n> = {\n  [exhaustiveDeps.name]: exhaustiveDeps.rule,\n  [stableQueryClient.name]: stableQueryClient.rule,\n  [noRestDestructuring.name]: noRestDestructuring.rule,\n  [noUnstableDeps.name]: noUnstableDeps.rule,\n}\n"],"names":["exhaustiveDeps.name","exhaustiveDeps.rule","stableQueryClient.name","stableQueryClient.rule","noRestDestructuring.name","noRestDestructuring.rule","noUnstableDeps.name","noUnstableDeps.rule"],"mappings":";;;;AAOO,MAAM,QAQT;AAAA,EACF,CAACA,IAAmB,GAAGC;AAAAA,EACvB,CAACC,MAAsB,GAAGC;AAAAA,EAC1B,CAACC,MAAwB,GAAGC;AAAAA,EAC5B,CAACC,MAAmB,GAAGC;AACzB;"}
+{"version":3,"file":"rules.js","sources":["../../src/rules.ts"],"sourcesContent":["import * as exhaustiveDeps from './rules/exhaustive-deps/exhaustive-deps.rule'\nimport * as stableQueryClient from './rules/stable-query-client/stable-query-client.rule'\nimport * as noRestDestructuring from './rules/no-rest-destructuring/no-rest-destructuring.rule'\nimport * as noUnstableDeps from './rules/no-unstable-deps/no-unstable-deps.rule'\nimport * as infiniteQueryPropertyOrder from './rules/infinite-query-property-order/infinite-query-property-order.rule'\nimport type { ESLintUtils } from '@typescript-eslint/utils'\nimport type { ExtraRuleDocs } from './types'\n\nexport const rules: Record<\n  string,\n  ESLintUtils.RuleModule<\n    string,\n    ReadonlyArray<unknown>,\n    ExtraRuleDocs,\n    ESLintUtils.RuleListener\n  >\n> = {\n  [exhaustiveDeps.name]: exhaustiveDeps.rule,\n  [stableQueryClient.name]: stableQueryClient.rule,\n  [noRestDestructuring.name]: noRestDestructuring.rule,\n  [noUnstableDeps.name]: noUnstableDeps.rule,\n  [infiniteQueryPropertyOrder.name]: infiniteQueryPropertyOrder.rule,\n}\n"],"names":["exhaustiveDeps.name","exhaustiveDeps.rule","stableQueryClient.name","stableQueryClient.rule","noRestDestructuring.name","noRestDestructuring.rule","noUnstableDeps.name","noUnstableDeps.rule","infiniteQueryPropertyOrder.name","infiniteQueryPropertyOrder.rule"],"mappings":";;;;;AAQO,MAAM,QAQT;AAAA,EACF,CAACA,IAAmB,GAAGC;AAAAA,EACvB,CAACC,MAAsB,GAAGC;AAAAA,EAC1B,CAACC,MAAwB,GAAGC;AAAAA,EAC5B,CAACC,MAAmB,GAAGC;AAAAA,EACvB,CAACC,MAA+B,GAAGC;AACrC;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/eslint-plugin-query",
-  "version": "5.56.1",
+  "version": "5.57.1",
   "description": "ESLint plugin for TanStack Query",
   "author": "Eliya Cohen",
   "license": "MIT",
@@ -41,6 +41,7 @@
   },
   "devDependencies": {
     "@typescript-eslint/rule-tester": "^8.3.0",
+    "combinate": "^1.1.11",
     "eslint": "^9.9.1"
   },
   "peerDependencies": {

package/src/__tests__/infinite-query-property-order.rule.test.ts

@@ -0,0 +1,182 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import combinate from 'combinate'
+
+import {
+  checkedProperties,
+  infiniteQueryFunctions,
+} from '../rules/infinite-query-property-order/constants'
+import {
+  name,
+  rule,
+} from '../rules/infinite-query-property-order/infinite-query-property-order.rule'
+import {
+  generateInterleavedCombinations,
+  generatePartialCombinations,
+  generatePermutations,
+} from './test-utils'
+import type { InfiniteQueryFunctions } from '../rules/infinite-query-property-order/constants'
+
+const ruleTester = new RuleTester()
+
+type CheckedProperties = (typeof checkedProperties)[number]
+const orderIndependentProps = ['queryKey', '...foo'] as const
+type OrderIndependentProps = (typeof orderIndependentProps)[number]
+
+interface TestCase {
+  infiniteQueryFunction: InfiniteQueryFunctions
+  properties: Array<CheckedProperties | OrderIndependentProps>
+}
+
+const validTestMatrix = combinate({
+  infiniteQueryFunction: [...infiniteQueryFunctions],
+  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('getNextPageParam') &&
+      combination.includes('getPreviousPageParam')
+    ) {
+      if (
+        combination.indexOf('getNextPageParam') <
+        combination.indexOf('getPreviousPageParam')
+      ) {
+        // since we ignore the relative order of 'getPreviousPageParam' and 'getNextPageParam', we skip this combination (but keep the other one where `getPreviousPageParam` is before `getNextPageParam`)
+
+        continue
+      }
+    }
+
+    allPermutations.push(
+      ...invalidPermutations
+        .map((p) => {
+          // ignore the relative order of 'getPreviousPageParam' and 'getNextPageParam'
+          const correctedValid = [...combination].sort((a, b) => {
+            if (
+              (a === 'getNextPageParam' && b === 'getPreviousPageParam') ||
+              (a === 'getPreviousPageParam' && b === 'getNextPageParam')
+            ) {
+              return p.indexOf(a) - p.indexOf(b)
+            }
+            return checkedProperties.indexOf(a) - checkedProperties.indexOf(b)
+          })
+          return { invalid: p, valid: correctedValid }
+        })
+        .filter(
+          ({ invalid }) =>
+            // if `getPreviousPageParam` and `getNextPageParam` are next to each other and `queryFn` is not present, we skip this invalid permutation
+            Math.abs(
+              invalid.indexOf('getNextPageParam') -
+                invalid.indexOf('getPreviousPageParam'),
+            ) !== 1 && !invalid.includes('queryFn'),
+        ),
+    )
+  }
+
+  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({
+  infiniteQueryFunction: [...infiniteQueryFunctions],
+  properties: interleavedInvalidPermutations,
+})
+
+function getCode({
+  infiniteQueryFunction: infiniteQueryFunction,
+  properties,
+}: TestCase) {
+  function getPropertyCode(
+    property: CheckedProperties | OrderIndependentProps,
+  ) {
+    if (property.startsWith('...')) {
+      return property
+    }
+    switch (property) {
+      case 'queryKey':
+        return `queryKey: ['projects']`
+      case 'queryFn':
+        return 'queryFn: async ({ pageParam }) => { \n await fetch(`/api/projects?cursor=${pageParam}`) \n return await response.json() \n }'
+      case 'getPreviousPageParam':
+        return 'getPreviousPageParam: (firstPage) => firstPage.previousId ?? undefined'
+      case 'getNextPageParam':
+        return 'getNextPageParam: (lastPage) => lastPage.nextId ?? undefined'
+    }
+
+    return `${property}: () => null`
+  }
+  return `
+    import { ${infiniteQueryFunction} } from '@tanstack/react-query'
+
+    ${infiniteQueryFunction}({
+        ${properties.map(getPropertyCode).join(',\n        ')}
+    })
+  `
+}
+
+const validTestCases = validTestMatrix.map(
+  ({ infiniteQueryFunction, properties }) => ({
+    name: `should pass when order is correct for ${infiniteQueryFunction} with order: ${properties.join(', ')}`,
+    code: getCode({ infiniteQueryFunction, properties }),
+  }),
+)
+
+const invalidTestCases = invalidTestMatrix.map(
+  ({ infiniteQueryFunction, properties }) => ({
+    name: `incorrect property order is detected for ${infiniteQueryFunction} with invalid order: ${properties.invalid.join(', ')}, valid order: ${properties.valid.join(', ')}`,
+    code: getCode({
+      infiniteQueryFunction: infiniteQueryFunction,
+      properties: properties.invalid,
+    }),
+    errors: [{ messageId: 'invalidOrder' }],
+    output: getCode({
+      infiniteQueryFunction: infiniteQueryFunction,
+      properties: properties.valid,
+    }),
+  }),
+)
+
+ruleTester.run(name, rule, {
+  valid: validTestCases,
+  invalid: invalidTestCases,
+})

package/src/__tests__/infinite-query-property-order.utils.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'vitest'
+import { sortDataByOrder } from '../rules/infinite-query-property-order/infinite-query-property-order.utils'
+
+describe('create-route-property-order utils', () => {
+  describe('sortDataByOrder', () => {
+    const testCases = [
+      {
+        data: [{ key: 'a' }, { key: 'c' }, { key: 'b' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+      {
+        data: [{ key: 'b' }, { key: 'a' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'c' }, { key: 'd' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'a' }, { key: 'b' }, { key: 'd' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'd' }, { key: 'a' }, { key: 'b' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: null,
+      },
+      {
+        data: [{ key: 'd' }, { key: 'b' }, { key: 'a' }, { key: 'c' }],
+        orderArray: [
+          [['a'], ['b']],
+          [['b'], ['c']],
+        ],
+        key: 'key',
+        expected: [{ key: 'd' }, { key: 'a' }, { key: 'b' }, { key: 'c' }],
+      },
+    ] as const
+    test.each(testCases)(
+      '$data $orderArray $key $expected',
+      ({ data, orderArray, key, expected }) => {
+        const sortedData = sortDataByOrder(data, orderArray, key)
+        expect(sortedData).toEqual(expected)
+      },
+    )
+  })
+})

package/src/__tests__/test-utils.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from 'vitest'
+import {
+  expectArrayEqualIgnoreOrder,
+  generateInterleavedCombinations,
+  generatePartialCombinations,
+  generatePermutations,
+} from './test-utils'
+
+describe('test-utils', () => {
+  describe('generatePermutations', () => {
+    const testCases = [
+      {
+        input: ['a', 'b', 'c'],
+        expected: [
+          ['a', 'b', 'c'],
+          ['a', 'c', 'b'],
+          ['b', 'a', 'c'],
+          ['b', 'c', 'a'],
+          ['c', 'a', 'b'],
+          ['c', 'b', 'a'],
+        ],
+      },
+      {
+        input: ['a', 'b'],
+        expected: [
+          ['a', 'b'],
+          ['b', 'a'],
+        ],
+      },
+      {
+        input: ['a'],
+        expected: [['a']],
+      },
+    ]
+    test.each(testCases)('$input $expected', ({ input, expected }) => {
+      const permutations = generatePermutations(input)
+      expect(permutations).toEqual(expected)
+    })
+  })
+
+  describe('generatePartialCombinations', () => {
+    const testCases = [
+      {
+        input: ['a', 'b', 'c'],
+        minLength: 2,
+        expected: [
+          ['a', 'b'],
+          ['a', 'c'],
+          ['b', 'c'],
+          ['a', 'b', 'c'],
+        ],
+      },
+      {
+        input: ['a', 'b'],
+        expected: [['a', 'b']],
+        minLength: 2,
+      },
+      {
+        input: ['a'],
+        expected: [],
+        minLength: 2,
+      },
+      {
+        input: ['a'],
+        expected: [['a']],
+        minLength: 1,
+      },
+      {
+        input: ['a'],
+        expected: [[], ['a']],
+        minLength: 0,
+      },
+    ]
+    test.each(testCases)(
+      '$input $minLength $expected',
+      ({ input, minLength, expected }) => {
+        const combinations = generatePartialCombinations(input, minLength)
+        expectArrayEqualIgnoreOrder(combinations, expected)
+      },
+    )
+  })
+
+  describe('generateInterleavedCombinations', () => {
+    const testCases = [
+      {
+        data: ['a', 'b'],
+        additional: ['x'],
+        expected: [
+          ['a', 'b'],
+          ['x', 'a', 'b'],
+          ['a', 'x', 'b'],
+          ['a', 'b', 'x'],
+        ],
+      },
+    ]
+    test.each(testCases)(
+      '$input $expected',
+      ({ data, additional, expected }) => {
+        const combinations = generateInterleavedCombinations(data, additional)
+        expectArrayEqualIgnoreOrder(combinations, expected)
+      },
+    )
+  })
+})

package/src/__tests__/test-utils.ts

@@ -1,5 +1,108 @@
+import { expect } from 'vitest'
+
 export function normalizeIndent(template: TemplateStringsArray) {
   const codeLines = template[0]?.split('\n') ?? ['']
   const leftPadding = codeLines[1]?.match(/\s+/)?.[0] ?? ''
   return codeLines.map((line) => line.slice(leftPadding.length)).join('\n')
 }
+
+export function generatePermutations<T>(arr: Array<T>): Array<Array<T>> {
+  if (arr.length <= 1) {
+    return [arr]
+  }
+
+  const result: Array<Array<T>> = []
+  for (let i = 0; i < arr.length; i++) {
+    const rest = arr.slice(0, i).concat(arr.slice(i + 1))
+    const restPermutations = generatePermutations(rest)
+    for (const perm of restPermutations) {
+      result.push([arr[i]!, ...perm])
+    }
+  }
+
+  return result
+}
+
+export function generatePartialCombinations<T>(
+  arr: ReadonlyArray<T>,
+  minLength: number,
+): Array<Array<T>> {
+  const result: Array<Array<T>> = []
+
+  function backtrack(start: number, current: Array<T>) {
+    if (current.length > minLength - 1) {
+      result.push([...current])
+    }
+    for (let i = start; i < arr.length; i++) {
+      current.push(arr[i]!)
+      backtrack(i + 1, current)
+      current.pop()
+    }
+  }
+  backtrack(0, [])
+  return result
+}
+
+export function expectArrayEqualIgnoreOrder<T>(a: Array<T>, b: Array<T>) {
+  expect([...a].sort()).toEqual([...b].sort())
+}
+
+export function generateInterleavedCombinations<
+  TData,
+  TAdditional,
+  TResult extends TData | TAdditional,
+>(
+  data: Array<TData> | ReadonlyArray<TData>,
+  additional: Array<TAdditional> | ReadonlyArray<TAdditional>,
+): Array<Array<TResult>> {
+  const result: Array<Array<TResult>> = []
+
+  function getSubsets(array: Array<TAdditional>): Array<Array<TAdditional>> {
+    return array.reduce(
+      (subsets, value) => {
+        return subsets.concat(subsets.map((set) => [...set, value]))
+      },
+      [[]] as Array<Array<TAdditional>>,
+    )
+  }
+
+  function insertAtPositions(
+    data: Array<TResult>,
+    subset: Array<TResult>,
+  ): Array<Array<TResult>> {
+    const combinations: Array<Array<TResult>> = []
+
+    const recurse = (
+      currentData: Array<TResult>,
+      currentSubset: Array<TResult>,
+      start: number,
+    ): void => {
+      if (currentSubset.length === 0) {
+        combinations.push([...currentData])
+        return
+      }
+
+      for (let i = start; i <= currentData.length; i++) {
+        const newData = [
+          ...currentData.slice(0, i),
+          currentSubset[0]!,
+          ...currentData.slice(i),
+        ]
+        recurse(newData, currentSubset.slice(1), i + 1)
+      }
+    }
+
+    recurse(data, subset, 0)
+    return combinations
+  }
+
+  const subsets = getSubsets(additional as Array<TAdditional>)
+
+  subsets.forEach((subset) => {
+    result.push(
+      ...insertAtPositions(data as Array<TResult>, subset as Array<TResult>),
+    )
+  })
+
+  return result
+}

package/src/index.ts

@@ -29,6 +29,7 @@ Object.assign(plugin.configs, {
       '@tanstack/query/no-rest-destructuring': 'warn',
       '@tanstack/query/stable-query-client': 'error',
       '@tanstack/query/no-unstable-deps': 'error',
+      '@tanstack/query/infinite-query-property-order': 'error',
     },
   },
   'flat/recommended': [
@@ -41,6 +42,7 @@ Object.assign(plugin.configs, {
         '@tanstack/query/no-rest-destructuring': 'warn',
         '@tanstack/query/stable-query-client': 'error',
         '@tanstack/query/no-unstable-deps': 'error',
+        '@tanstack/query/infinite-query-property-order': 'error',
       },
     },
   ],

package/src/rules/infinite-query-property-order/constants.ts

@@ -0,0 +1,17 @@
+export const infiniteQueryFunctions = [
+  'infiniteQueryOptions',
+  'useInfiniteQuery',
+  'useSuspenseInfiniteQuery',
+] as const
+
+export type InfiniteQueryFunctions = (typeof infiniteQueryFunctions)[number]
+
+export const checkedProperties = [
+  'queryFn',
+  'getPreviousPageParam',
+  'getNextPageParam',
+] as const
+
+export const sortRules = [
+  [['queryFn'], ['getPreviousPageParam', 'getNextPageParam']],
+] as const

package/src/rules/infinite-query-property-order/infinite-query-property-order.rule.ts

@@ -0,0 +1,112 @@
+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 './infinite-query-property-order.utils'
+import { infiniteQueryFunctions, sortRules } from './constants'
+import type { InfiniteQueryFunctions } from './constants'
+import type { ExtraRuleDocs } from '../../types'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+const infiniteQueryFunctionsSet = new Set(infiniteQueryFunctions)
+function isInfiniteQueryFunction(node: any): node is InfiniteQueryFunctions {
+  return infiniteQueryFunctionsSet.has(node)
+}
+
+export const name = 'infinite-query-property-order'
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Ensure correct order of inference sensitive properties for infinite queries',
+      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 infiniteQueryFunction = node.callee.name
+        if (!isInfiniteQueryFunction(infiniteQueryFunction)) {
+          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) => {
+          if (
+            p.type === AST_NODE_TYPES.Property &&
+            p.key.type === AST_NODE_TYPES.Identifier
+          ) {
+            return { name: p.key.name, property: p }
+          } else if (p.type === AST_NODE_TYPES.SpreadElement) {
+            if (p.argument.type === AST_NODE_TYPES.Identifier) {
+              return { name: p.argument.name, property: p }
+            } else {
+              throw new Error('Unsupported spread element')
+            }
+          }
+          return []
+        })
+
+        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 text = sortedProperties.reduce(
+              (sourceText, specifier, index) => {
+                let text = ''
+                if (index < allProperties.length - 1) {
+                  text = sourceCode
+                    .getText()
+                    .slice(
+                      allProperties[index]!.range[1],
+                      allProperties[index + 1]!.range[0],
+                    )
+                }
+                return (
+                  sourceText + sourceCode.getText(specifier.property) + text
+                )
+              },
+              '',
+            )
+            return fixer.replaceTextRange(
+              [allProperties[0]!.range[0], allProperties.at(-1)!.range[1]],
+              text,
+            )
+          },
+        })
+      },
+    }
+  }),
+})