@tanstack/eslint-plugin-query 5.72.1 → 5.73.3

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

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

@@ -0,0 +1,67 @@
+export function sortDataByOrder<T, TKey extends keyof T>(
+  data: Array<T> | ReadonlyArray<T>,
+  orderRules: ReadonlyArray<
+    Readonly<[ReadonlyArray<T[TKey]>, ReadonlyArray<T[TKey]>]>
+  >,
+  key: TKey,
+): Array<T> | null {
+  const getSubsetIndex = (
+    item: T[TKey],
+    subsets: ReadonlyArray<ReadonlyArray<T[TKey]> | Array<T[TKey]>>,
+  ): number | null => {
+    for (let i = 0; i < subsets.length; i++) {
+      if (subsets[i]?.includes(item)) {
+        return i
+      }
+    }
+    return null
+  }
+
+  const orderSets = orderRules.reduce(
+    (sets, [A, B]) => [...sets, A, B],
+    [] as Array<ReadonlyArray<T[TKey]> | Array<T[TKey]>>,
+  )
+
+  const inOrderArray = data.filter(
+    (item) => getSubsetIndex(item[key], orderSets) !== null,
+  )
+
+  let wasResorted = false as boolean
+
+  // Sort by the relative order defined by the rules
+  const sortedArray = inOrderArray.sort((a, b) => {
+    const aKey = a[key],
+      bKey = b[key]
+    const aSubsetIndex = getSubsetIndex(aKey, orderSets)
+    const bSubsetIndex = getSubsetIndex(bKey, orderSets)
+
+    // If both items belong to different subsets, sort by their subset order
+    if (
+      aSubsetIndex !== null &&
+      bSubsetIndex !== null &&
+      aSubsetIndex !== bSubsetIndex
+    ) {
+      return aSubsetIndex - bSubsetIndex
+    }
+
+    // If both items belong to the same subset or neither is in the subset, keep their relative order
+    return 0
+  })
+
+  const inOrderIterator = sortedArray.values()
+  const result = data.map((item) => {
+    if (getSubsetIndex(item[key], orderSets) !== null) {
+      const sortedItem = inOrderIterator.next().value!
+      if (sortedItem[key] !== item[key]) {
+        wasResorted = true
+      }
+      return sortedItem
+    }
+    return item
+  })
+
+  if (!wasResorted) {
+    return null
+  }
+  return result
+}

package/src/rules/no-rest-destructuring/no-rest-destructuring.rule.ts

@@ -0,0 +1,115 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { ASTUtils } from '../../utils/ast-utils'
+import { detectTanstackQueryImports } from '../../utils/detect-react-query-imports'
+import { NoRestDestructuringUtils } from './no-rest-destructuring.utils'
+import type { ExtraRuleDocs } from '../../types'
+
+export const name = 'no-rest-destructuring'
+
+const queryHooks = [
+  'useQuery',
+  'useQueries',
+  'useInfiniteQuery',
+  'useSuspenseQuery',
+  'useSuspenseQueries',
+  'useSuspenseInfiniteQuery',
+]
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallows rest destructuring in queries',
+      recommended: 'warn',
+    },
+    messages: {
+      objectRestDestructure: `Object rest destructuring on a query will observe all changes to the query, leading to excessive re-renders.`,
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackQueryImports((context, _, helpers) => {
+    const queryResultVariables = new Set<string>()
+
+    return {
+      CallExpression: (node) => {
+        if (
+          !ASTUtils.isIdentifierWithOneOfNames(node.callee, queryHooks) ||
+          node.parent.type !== AST_NODE_TYPES.VariableDeclarator ||
+          !helpers.isTanstackQueryImport(node.callee)
+        ) {
+          return
+        }
+
+        const returnValue = node.parent.id
+
+        if (
+          node.callee.name !== 'useQueries' &&
+          node.callee.name !== 'useSuspenseQueries'
+        ) {
+          if (NoRestDestructuringUtils.isObjectRestDestructuring(returnValue)) {
+            return context.report({
+              node: node.parent,
+              messageId: 'objectRestDestructure',
+            })
+          }
+
+          if (returnValue.type === AST_NODE_TYPES.Identifier) {
+            queryResultVariables.add(returnValue.name)
+          }
+
+          return
+        }
+
+        if (returnValue.type !== AST_NODE_TYPES.ArrayPattern) {
+          if (returnValue.type === AST_NODE_TYPES.Identifier) {
+            queryResultVariables.add(returnValue.name)
+          }
+          return
+        }
+
+        returnValue.elements.forEach((queryResult) => {
+          if (queryResult === null) {
+            return
+          }
+          if (NoRestDestructuringUtils.isObjectRestDestructuring(queryResult)) {
+            context.report({
+              node: queryResult,
+              messageId: 'objectRestDestructure',
+            })
+          }
+        })
+      },
+
+      VariableDeclarator: (node) => {
+        if (
+          node.init?.type === AST_NODE_TYPES.Identifier &&
+          queryResultVariables.has(node.init.name) &&
+          NoRestDestructuringUtils.isObjectRestDestructuring(node.id)
+        ) {
+          context.report({
+            node,
+            messageId: 'objectRestDestructure',
+          })
+        }
+      },
+
+      SpreadElement: (node) => {
+        if (
+          node.argument.type === AST_NODE_TYPES.Identifier &&
+          queryResultVariables.has(node.argument.name)
+        ) {
+          context.report({
+            node,
+            messageId: 'objectRestDestructure',
+          })
+        }
+      },
+    }
+  }),
+})

package/src/rules/no-rest-destructuring/no-rest-destructuring.utils.ts

@@ -0,0 +1,11 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils'
+import type { TSESTree } from '@typescript-eslint/utils'
+
+export const NoRestDestructuringUtils = {
+  isObjectRestDestructuring(node: TSESTree.Node): boolean {
+    if (node.type !== AST_NODE_TYPES.ObjectPattern) {
+      return false
+    }
+    return node.properties.some((p) => p.type === AST_NODE_TYPES.RestElement)
+  },
+}

package/src/rules/no-unstable-deps/no-unstable-deps.rule.ts

@@ -0,0 +1,129 @@
+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 type { TSESTree } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from '../../types'
+
+export const name = 'no-unstable-deps'
+
+export const reactHookNames = ['useEffect', 'useCallback', 'useMemo']
+export const useQueryHookNames = [
+  'useQuery',
+  'useSuspenseQuery',
+  'useQueries',
+  'useSuspenseQueries',
+  'useInfiniteQuery',
+  'useSuspenseInfiniteQuery',
+]
+const allHookNames = ['useMutation', ...useQueryHookNames]
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow putting the result of query hooks directly in a React hook dependency array',
+      recommended: 'error',
+    },
+    messages: {
+      noUnstableDeps: `The result of {{queryHook}} is not referentially stable, so don't pass it directly into the dependencies array of {{reactHook}}. Instead, destructure the return value of {{queryHook}} and pass the destructured values into the dependency array of {{reactHook}}.`,
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackQueryImports((context) => {
+    const trackedVariables: Record<string, string> = {}
+    const hookAliasMap: Record<string, string> = {}
+
+    function getReactHook(node: TSESTree.CallExpression): string | undefined {
+      if (node.callee.type === 'Identifier') {
+        const calleeName = node.callee.name
+        // Check if the identifier is a known React hook or an alias
+        if (reactHookNames.includes(calleeName) || calleeName in hookAliasMap) {
+          return calleeName
+        }
+      } else if (
+        node.callee.type === 'MemberExpression' &&
+        node.callee.object.type === 'Identifier' &&
+        node.callee.object.name === 'React' &&
+        node.callee.property.type === 'Identifier' &&
+        reactHookNames.includes(node.callee.property.name)
+      ) {
+        // Member expression case: `React.useCallback`
+        return node.callee.property.name
+      }
+      return undefined
+    }
+
+    function collectVariableNames(
+      pattern: TSESTree.BindingName,
+      queryHook: string,
+    ) {
+      if (pattern.type === AST_NODE_TYPES.Identifier) {
+        trackedVariables[pattern.name] = queryHook
+      }
+    }
+
+    return {
+      ImportDeclaration(node: TSESTree.ImportDeclaration) {
+        if (
+          node.specifiers.length > 0 &&
+          node.importKind === 'value' &&
+          node.source.value === 'React'
+        ) {
+          node.specifiers.forEach((specifier) => {
+            if (
+              specifier.type === AST_NODE_TYPES.ImportSpecifier &&
+              specifier.imported.type === AST_NODE_TYPES.Identifier &&
+              reactHookNames.includes(specifier.imported.name)
+            ) {
+              // Track alias or direct import
+              hookAliasMap[specifier.local.name] = specifier.imported.name
+            }
+          })
+        }
+      },
+
+      VariableDeclarator(node) {
+        if (
+          node.init !== null &&
+          node.init.type === AST_NODE_TYPES.CallExpression &&
+          node.init.callee.type === AST_NODE_TYPES.Identifier &&
+          allHookNames.includes(node.init.callee.name)
+        ) {
+          collectVariableNames(node.id, node.init.callee.name)
+        }
+      },
+      CallExpression: (node) => {
+        const reactHook = getReactHook(node)
+        if (
+          reactHook !== undefined &&
+          node.arguments.length > 1 &&
+          node.arguments[1]?.type === AST_NODE_TYPES.ArrayExpression
+        ) {
+          const depsArray = node.arguments[1].elements
+          depsArray.forEach((dep) => {
+            if (
+              dep !== null &&
+              dep.type === AST_NODE_TYPES.Identifier &&
+              trackedVariables[dep.name] !== undefined
+            ) {
+              const queryHook = trackedVariables[dep.name]
+              context.report({
+                node: dep,
+                messageId: 'noUnstableDeps',
+                data: {
+                  queryHook,
+                  reactHook,
+                },
+              })
+            }
+          })
+        }
+      },
+    }
+  }),
+})

package/src/rules/no-void-query-fn/no-void-query-fn.rule.ts

@@ -0,0 +1,84 @@
+import { ESLintUtils } from '@typescript-eslint/utils'
+import ts from 'typescript'
+import { ASTUtils } from '../../utils/ast-utils'
+import { detectTanstackQueryImports } from '../../utils/detect-react-query-imports'
+import { getDocsUrl } from '../../utils/get-docs-url'
+import type { ExtraRuleDocs } from '../../types'
+
+export const name = 'no-void-query-fn'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Ensures queryFn returns a non-undefined value',
+      recommended: 'error',
+    },
+    messages: {
+      noVoidReturn: 'queryFn must return a non-undefined value',
+    },
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackQueryImports((context) => {
+    return {
+      Property(node) {
+        if (
+          !ASTUtils.isObjectExpression(node.parent) ||
+          !ASTUtils.isIdentifierWithName(node.key, 'queryFn')
+        ) {
+          return
+        }
+
+        const parserServices = context.sourceCode.parserServices
+
+        if (
+          !parserServices ||
+          !parserServices.esTreeNodeToTSNodeMap ||
+          !parserServices.program
+        ) {
+          return
+        }
+
+        const checker = parserServices.program.getTypeChecker()
+        const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node.value)
+        const type = checker.getTypeAtLocation(tsNode)
+
+        // Get the return type of the function
+        if (type.getCallSignatures().length > 0) {
+          const returnType = type.getCallSignatures()[0]?.getReturnType()
+
+          if (!returnType) {
+            return
+          }
+
+          // Check if return type is void or undefined
+          if (isIllegalReturn(checker, returnType)) {
+            context.report({
+              node: node.value,
+              messageId: 'noVoidReturn',
+            })
+          }
+        }
+      },
+    }
+  }),
+})
+
+function isIllegalReturn(checker: ts.TypeChecker, type: ts.Type): boolean {
+  const awaited = checker.getAwaitedType(type)
+
+  if (!awaited) return false
+
+  if (awaited.isUnion()) {
+    return awaited.types.some((t) => isIllegalReturn(checker, t))
+  }
+
+  return awaited.flags & (ts.TypeFlags.Void | ts.TypeFlags.Undefined)
+    ? true
+    : false
+}

package/src/rules/stable-query-client/stable-query-client.rule.ts

@@ -0,0 +1,88 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+import { ASTUtils } from '../../utils/ast-utils'
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectTanstackQueryImports } from '../../utils/detect-react-query-imports'
+import type { TSESLint } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from '../../types'
+
+export const name = 'stable-query-client'
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+export const rule = createRule({
+  name,
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Makes sure that QueryClient is stable',
+      recommended: 'error',
+    },
+    messages: {
+      unstable: [
+        'QueryClient is not stable. It should be either extracted from the component or wrapped in React.useState.',
+        'See https://tkdodo.eu/blog/react-query-fa-qs#2-the-queryclient-is-not-stable',
+      ].join('\n'),
+      fixTo: 'Fix to {{result}}',
+    },
+    hasSuggestions: true,
+    fixable: 'code',
+    schema: [],
+  },
+  defaultOptions: [],
+
+  create: detectTanstackQueryImports((context, _, helpers) => {
+    return {
+      NewExpression: (node) => {
+        if (
+          node.callee.type !== AST_NODE_TYPES.Identifier ||
+          node.callee.name !== 'QueryClient' ||
+          node.parent.type !== AST_NODE_TYPES.VariableDeclarator ||
+          !helpers.isSpecificTanstackQueryImport(
+            node.callee,
+            '@tanstack/react-query',
+          )
+        ) {
+          return
+        }
+
+        const fnAncestor = ASTUtils.getFunctionAncestor(
+          context.sourceCode,
+          node,
+        )
+        const isReactServerComponent = fnAncestor?.async === true
+
+        if (
+          !ASTUtils.isValidReactComponentOrHookName(fnAncestor?.id) ||
+          isReactServerComponent
+        ) {
+          return
+        }
+
+        context.report({
+          node: node.parent,
+          messageId: 'unstable',
+          fix: (() => {
+            const { parent } = node
+
+            if (parent.id.type !== AST_NODE_TYPES.Identifier) {
+              return
+            }
+
+            // we need the fallbacks for backwards compat with eslint < 8.37.0
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            const sourceCode = context.sourceCode ?? context.getSourceCode()
+            const nodeText = sourceCode.getText(node)
+            const variableName = parent.id.name
+
+            return (fixer: TSESLint.RuleFixer) => {
+              return fixer.replaceTextRange(
+                [parent.range[0], parent.range[1]],
+                `[${variableName}] = React.useState(() => ${nodeText})`,
+              )
+            }
+          })(),
+        })
+      },
+    }
+  }),
+})

package/src/rules.ts

@@ -0,0 +1,25 @@
+import * as exhaustiveDeps from './rules/exhaustive-deps/exhaustive-deps.rule'
+import * as stableQueryClient from './rules/stable-query-client/stable-query-client.rule'
+import * as noRestDestructuring from './rules/no-rest-destructuring/no-rest-destructuring.rule'
+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 type { ESLintUtils } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from './types'
+
+export const rules: Record<
+  string,
+  ESLintUtils.RuleModule<
+    string,
+    ReadonlyArray<unknown>,
+    ExtraRuleDocs,
+    ESLintUtils.RuleListener
+  >
+> = {
+  [exhaustiveDeps.name]: exhaustiveDeps.rule,
+  [stableQueryClient.name]: stableQueryClient.rule,
+  [noRestDestructuring.name]: noRestDestructuring.rule,
+  [noUnstableDeps.name]: noUnstableDeps.rule,
+  [infiniteQueryPropertyOrder.name]: infiniteQueryPropertyOrder.rule,
+  [noVoidQueryFn.name]: noVoidQueryFn.rule,
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type ExtraRuleDocs = {
+  recommended: 'strict' | 'error' | 'warn'
+}