feat(eslint-plugin-query): add prefer-query-options rule

.changeset/perky-comics-dig.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/eslint-plugin-query': minor
+---
+
+Add prefer-query-options rule

packages/eslint-plugin-query/src/__tests__/prefer-query-options.test.ts

@@ -0,0 +1,76 @@
+import { RuleTester } from '@typescript-eslint/rule-tester'
+import { afterAll, describe, it } from 'vitest'
+import { rule } from '../rules/prefer-query-options/prefer-query-options.rule'
+
+const ruleTester = new RuleTester()
+
+RuleTester.afterAll = afterAll
+RuleTester.describe = describe
+RuleTester.it = it
+
+// useQuery hooks
+ruleTester.run(rule.name, rule, {
+ valid: [
+ { code: `useQuery(usersQuery)` },
+ { code: `useQuery({ ...usersQuery })` },
+ { code: `useQuery({ ...usersQuery() })` },
+ { code: `useQuery({ ...usersQuery, meta: {} })` },
+ ],
+ invalid: [
+ {
+ code: `useQuery({ queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `const users = useQuery({ ...queryOptions, queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `const users = useQuery({ queryFn: () => {} })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `const users = useQuery({ ...queryOptions, queryFn: () => {} })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `useInfiniteQuery({ queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `useSuspenseQuery({ queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ {
+ code: `useSuspenseInfiniteQuery({ queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-hook' }],
+ },
+ ],
+})
+
+// queryClient.invalidateQueries expressions
+ruleTester.run(rule.name, rule, {
+ valid: [
+ { code: `queryClient.invalidateQueries(usersQuery)` },
+ { code: `queryClient.invalidateQueries({ ...usersQuery })` },
+ { code: `queryClient.invalidateQueries({ ...usersQuery() })` },
+ ],
+ invalid: [
+ {
+ code: `queryClient.invalidateQueries({ queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-invalidate' }],
+ },
+ {
+ code: `queryClient.invalidateQueries({ ...queryOptions, queryKey: [] })`,
+ errors: [{ messageId: 'no-inline-query-invalidate' }],
+ },
+ {
+ code: `queryClient.invalidateQueries({ queryFn: () => {} })`,
+ errors: [{ messageId: 'no-inline-query-invalidate' }],
+ },
+ {
+ code: `queryClient.invalidateQueries({ ...queryOptions, queryFn: () => {} })`,
+ errors: [{ messageId: 'no-inline-query-invalidate' }],
+ },
+ ],
+})

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

@@ -9,6 +9,7 @@ export interface Plugin extends Omit<ESLint.Plugin, 'rules'> {
  configs: {
  recommended: ESLint.ConfigData
  'flat/recommended': Array<Linter.Config>
+ 'flat/recommendedStrict': Array<Linter.Config>
  }
 }
 
@@ -46,10 +47,29 @@ export const plugin = {
  },
  },
  ],
+ 'flat/recommendedStrict': [
+ {
+ name: 'tanstack/query/flat/recommendedStrict',
+ plugins: {
+ '@tanstack/query': {}, // Assigned after plugin object created
+ },
+ rules: {
+ '@tanstack/query/exhaustive-deps': 'error',
+ '@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',
+ '@tanstack/query/no-void-query-fn': 'error',
+ '@tanstack/query/mutation-property-order': 'error',
+ '@tanstack/query/prefer-query-options': 'error',
+ },
+ },
+ ],
  },
  rules,
 } satisfies Plugin
 
 plugin.configs['flat/recommended'][0]!.plugins['@tanstack/query'] = plugin
+plugin.configs['flat/recommendedStrict'][0]!.plugins['@tanstack/query'] = plugin
 
 export default plugin

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

@@ -5,6 +5,7 @@ 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 * as preferQueryOptions from './rules/prefer-query-options/prefer-query-options.rule'
 import type { ESLintUtils } from '@typescript-eslint/utils'
 import type { ExtraRuleDocs } from './types'
 
@@ -24,4 +25,5 @@ export const rules: Record<
  [infiniteQueryPropertyOrder.name]: infiniteQueryPropertyOrder.rule,
  [noVoidQueryFn.name]: noVoidQueryFn.rule,
  [mutationPropertyOrder.name]: mutationPropertyOrder.rule,
+ [preferQueryOptions.name]: preferQueryOptions.rule,
 }

packages/eslint-plugin-query/src/rules/prefer-query-options/prefer-query-options.rule.ts

@@ -0,0 +1,77 @@
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils'
+import { getDocsUrl } from '../../utils/get-docs-url'
+import { detectQueryOptionsInObject } from './prefer-query-options.utils'
+import type { TSESTree } from '@typescript-eslint/utils'
+import type { ExtraRuleDocs } from '../../types'
+
+export const name = 'prefer-query-options'
+
+const useQueryHooks = [
+ // see https://tanstack.com/query/latest/docs/framework/react/reference/useQuery
+ 'useQuery',
+ // 'useQueries', // only works for single queries for now
+ 'useInfiniteQuery',
+ 'useSuspenseQuery',
+ // 'useSuspenseQueries',
+ 'useSuspenseInfiniteQuery',
+]
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl)
+
+/** @returns true if it's a `useQuery` hook call expression node */
+function isQueryHookCallExpression(node: TSESTree.CallExpression) {
+ if (node.callee.type !== AST_NODE_TYPES.Identifier) return false
+ if (!useQueryHooks.includes(node.callee.name)) return false
+ return true
+}
+
+/** @returns true if it's a call to `*.invalidateQueries` */
+function isInvalidateQueriesCallExpression(node: TSESTree.CallExpression) {
+ return (
+ node.callee.type === AST_NODE_TYPES.MemberExpression &&
+ node.callee.property.type === AST_NODE_TYPES.Identifier &&
+ node.callee.property.name === 'invalidateQueries'
+ )
+}
+
+export const rule = createRule({
+ name,
+ meta: {
+ type: 'suggestion',
+ docs: {
+ description:
+ 'Ensures queryOptions constructor pattern is used when calling query apis',
+ recommended: 'strict',
+ },
+ messages: {
+ 'no-inline-query-hook': 'Expected query hook to use queryOptions pattern',
+ 'no-inline-query-invalidate':
+ 'Expected query invalidate call to use queryOptions pattern',
+ },
+ schema: [],
+ },
+ defaultOptions: [],
+ create(context) {
+ return {
+ CallExpression(node) {
+ // use*Query hook call
+ if (
+ isQueryHookCallExpression(node) &&
+ node.arguments[0] &&
+ detectQueryOptionsInObject(node.arguments[0])
+ ) {
+ context.report({ messageId: 'no-inline-query-hook', node })
+ }
+
+ // queryClient.invalidateQueries call
+ if (
+ isInvalidateQueriesCallExpression(node) &&
+ node.arguments[0] &&
+ detectQueryOptionsInObject(node.arguments[0])
+ ) {
+ context.report({ messageId: 'no-inline-query-invalidate', node })
+ }
+ },
+ }
+ },
+})

packages/eslint-plugin-query/src/rules/prefer-query-options/prefer-query-options.utils.ts

@@ -0,0 +1,23 @@
+import { AST_NODE_TYPES } from '@typescript-eslint/utils'
+import type { TSESTree } from '@typescript-eslint/utils'
+
+const MAIN_QUERY_PROPERTIES = ['queryKey', 'queryFn']
+
+/**
+ * @returns true if the node is an object that has main query options (ie queryKey or queryFn).
+ * This is used for detecting inline query options in hooks and functions
+ */
+export function detectQueryOptionsInObject(queryNode: TSESTree.Node): boolean {
+ // skip if it's not an object
+ if (queryNode.type !== AST_NODE_TYPES.ObjectExpression) return false
+
+ // check if any of the properties is queryKey or queryFn
+ const hasMainQueryProperties = queryNode.properties.find(
+ (property) =>
+ property.type === AST_NODE_TYPES.Property &&
+ property.key.type === AST_NODE_TYPES.Identifier &&
+ MAIN_QUERY_PROPERTIES.includes(property.key.name),
+ )
+
+ return !!hasMainQueryProperties
+}