fix(eslint-plugin-query): detect rest destructuring on custom query hooks

.changeset/no-rest-destructuring-custom-hooks.md

@@ -0,0 +1,5 @@
+---
+"@tanstack/eslint-plugin-query": minor
+---
+
+`no-rest-destructuring` now also flags rest destructuring on custom hooks that return a TanStack Query result. Detection uses the TypeScript type checker and runs only when typed linting is enabled, so untyped projects are unaffected. Closes #8951.

docs/eslint/no-rest-destructuring.md

@@ -34,6 +34,8 @@ const todosQuery = useQuery({
 const { data: todos } = todosQuery
 ```
 
+When [typed linting](https://typescript-eslint.io/getting-started/typed-linting/) is enabled, the rule also flags rest destructuring on custom hooks that return a TanStack Query result.
+
 ## When Not To Use It
 
 If you set the `notifyOnChangeProps` options manually, you can disable this rule.

packages/eslint-plugin-query/src/__tests__/no-rest-destructuring.test.ts

@@ -1,7 +1,13 @@
+import path from 'node:path'
 import { RuleTester } from '@typescript-eslint/rule-tester'
+import { afterAll, describe, it } from 'vitest'
 import { rule } from '../rules/no-rest-destructuring/no-rest-destructuring.rule'
 import { normalizeIndent } from './test-utils'
 
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
 const ruleTester = new RuleTester()
 
 ruleTester.run('no-rest-destructuring', rule, {
@@ -392,3 +398,109 @@ ruleTester.run('no-rest-destructuring', rule, {
     },
   ],
 })
+
+const ruleTesterTypeChecked = new RuleTester({
+  languageOptions: {
+    parser: await import('@typescript-eslint/parser'),
+    parserOptions: {
+      project: true,
+      tsconfigRootDir: path.resolve(__dirname, './ts-fixture'),
+    },
+  },
+})
+
+ruleTesterTypeChecked.run('no-rest-destructuring with type information', rule, {
+  valid: [
+    {
+      name: 'custom hook not returning a query result is destructured with rest',
+      code: normalizeIndent`
+        const useThing = () => ({ data: 1, isError: false })
+
+        function Component() {
+          const { data, ...rest } = useThing()
+          return null
+        }
+      `,
+    },
+    {
+      name: 'custom hook returning a query result is destructured without rest',
+      code: normalizeIndent`
+        import { useQuery } from '@tanstack/react-query'
+
+        const useTodos = () =>
+          useQuery({ queryKey: ['todos'], queryFn: () => Promise.resolve([]) })
+
+        function Component() {
+          const { data, isLoading } = useTodos()
+          return null
+        }
+      `,
+    },
+  ],
+  invalid: [
+    {
+      name: 'custom hook returning useQuery is destructured with rest',
+      code: normalizeIndent`
+        import { useQuery } from '@tanstack/react-query'
+
+        const useTodos = () =>
+          useQuery({ queryKey: ['todos'], queryFn: () => Promise.resolve([]) })
+
+        function Component() {
+          const { data, ...rest } = useTodos()
+          return null
+        }
+      `,
+      errors: [{ messageId: 'objectRestDestructure' }],
+    },
+    {
+      name: 'custom hook result is spread in object expression',
+      code: normalizeIndent`
+        import { useQuery } from '@tanstack/react-query'
+
+        const useTodos = () =>
+          useQuery({ queryKey: ['todos'], queryFn: () => Promise.resolve([]) })
+
+        function Component() {
+          const todosQuery = useTodos()
+          return { ...todosQuery }
+        }
+      `,
+      errors: [{ messageId: 'objectRestDestructure' }],
+    },
+    {
+      name: 'custom hook result is assigned then destructured with rest',
+      code: normalizeIndent`
+        import { useQuery } from '@tanstack/react-query'
+
+        const useTodos = () =>
+          useQuery({ queryKey: ['todos'], queryFn: () => Promise.resolve([]) })
+
+        function Component() {
+          const todosQuery = useTodos()
+          const { data, ...rest } = todosQuery
+          return null
+        }
+      `,
+      errors: [{ messageId: 'objectRestDestructure' }],
+    },
+    {
+      name: 'custom hook returning an interface query result is destructured with rest',
+      code: normalizeIndent`
+        import type { QueryObserverResult } from '@tanstack/react-query'
+
+        const useTodos = (): QueryObserverResult => ({
+          data: undefined,
+          isLoading: false,
+          isError: false,
+        })
+
+        function Component() {
+          const { data, ...rest } = useTodos()
+          return null
+        }
+      `,
+      errors: [{ messageId: 'objectRestDestructure' }],
+    },
+  ],
+})

packages/eslint-plugin-query/src/__tests__/ts-fixture/react-query.d.ts

@@ -0,0 +1,20 @@
+// Ambient stub so type-checked tests can resolve `@tanstack/react-query`
+// without adding it as a devDependency of this plugin.
+declare module '@tanstack/react-query' {
+  export type UseQueryResult<TData = unknown> = {
+    data: TData | undefined
+    isLoading: boolean
+    isError: boolean
+  }
+  // Declared as an interface so its type resolves via `getSymbol()` rather
+  // than `aliasSymbol`, exercising the non-alias detection path.
+  export interface QueryObserverResult<TData = unknown> {
+    data: TData | undefined
+    isLoading: boolean
+    isError: boolean
+  }
+  export function useQuery<TData>(options: {
+    queryKey: ReadonlyArray<unknown>
+    queryFn: () => Promise<TData>
+  }): UseQueryResult<TData>
+}

packages/eslint-plugin-query/src/rules/no-rest-destructuring/no-rest-destructuring.rule.ts

@@ -38,20 +38,40 @@ export const rule = createRule({
 
     return {
       CallExpression: (node) => {
-        if (
-          !ASTUtils.isIdentifierWithOneOfNames(node.callee, queryHooks) ||
-          node.parent.type !== AST_NODE_TYPES.VariableDeclarator ||
-          !helpers.isTanstackQueryImport(node.callee)
-        ) {
+        if (node.parent.type !== AST_NODE_TYPES.VariableDeclarator) {
           return
         }
 
         const returnValue = node.parent.id
 
-        if (
-          node.callee.name !== 'useQueries' &&
-          node.callee.name !== 'useSuspenseQueries'
-        ) {
+        const isDirectHook =
+          ASTUtils.isIdentifierWithOneOfNames(node.callee, queryHooks) &&
+          helpers.isTanstackQueryImport(node.callee)
+
+        if (!isDirectHook) {
+          // The type-aware path can only report when the result is rest
+          // destructured or assigned to an identifier that may later be
+          // spread. Skip the expensive type lookup for any other binding.
+          const canReportQueryResult =
+            returnValue.type === AST_NODE_TYPES.Identifier ||
+            NoRestDestructuringUtils.isObjectRestDestructuring(returnValue)
+
+          if (
+            !canReportQueryResult ||
+            !NoRestDestructuringUtils.isQueryResultCall(
+              node,
+              context.sourceCode.parserServices,
+            )
+          ) {
+            return
+          }
+        }
+
+        const calleeName = ASTUtils.isIdentifier(node.callee)
+          ? node.callee.name
+          : null
+
+        if (calleeName !== 'useQueries' && calleeName !== 'useSuspenseQueries') {
           if (NoRestDestructuringUtils.isObjectRestDestructuring(returnValue)) {
             return context.report({
               node: node.parent,

packages/eslint-plugin-query/src/rules/no-rest-destructuring/no-rest-destructuring.utils.ts

@@ -1,5 +1,37 @@
 import { AST_NODE_TYPES } from '@typescript-eslint/utils'
-import type { TSESTree } from '@typescript-eslint/utils'
+import type {
+  ParserServices,
+  ParserServicesWithTypeInformation,
+  TSESTree,
+} from '@typescript-eslint/utils'
+
+type TypeChecker = ReturnType<
+  ParserServicesWithTypeInformation['program']['getTypeChecker']
+>
+type Type = ReturnType<TypeChecker['getTypeAtLocation']>
+
+const QUERY_RESULT_TYPE_NAMES = new Set([
+  'UseBaseQueryResult',
+  'UseQueryResult',
+  'UseSuspenseQueryResult',
+  'DefinedUseQueryResult',
+  'UseInfiniteQueryResult',
+  'UseSuspenseInfiniteQueryResult',
+  'DefinedUseInfiniteQueryResult',
+  'QueryObserverResult',
+  'InfiniteQueryObserverResult',
+])
+
+function isQueryResultType(type: Type): boolean {
+  if (type.aliasSymbol && QUERY_RESULT_TYPE_NAMES.has(type.aliasSymbol.name)) {
+    return true
+  }
+  const symbol = type.getSymbol()
+  if (symbol && QUERY_RESULT_TYPE_NAMES.has(symbol.name)) {
+    return true
+  }
+  return type.isUnion() && type.types.some(isQueryResultType)
+}
 
 export const NoRestDestructuringUtils = {
   isObjectRestDestructuring(node: TSESTree.Node): boolean {
@@ -8,4 +40,16 @@ export const NoRestDestructuringUtils = {
     }
     return node.properties.some((p) => p.type === AST_NODE_TYPES.RestElement)
   },
+  isQueryResultCall(
+    node: TSESTree.CallExpression,
+    parserServices: Partial<ParserServices> | null | undefined,
+  ): boolean {
+    if (!parserServices?.program || !parserServices.esTreeNodeToTSNodeMap) {
+      return false
+    }
+    const checker = parserServices.program.getTypeChecker()
+    const tsNode = parserServices.esTreeNodeToTSNodeMap.get(node.callee)
+    const signatures = checker.getTypeAtLocation(tsNode).getCallSignatures()
+    return signatures.some((sig) => isQueryResultType(sig.getReturnType()))
+  },
 }