@openapi-qraft/eslint-plugin-query 2.12.0

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

@@ -0,0 +1,135 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import type { ExtraRuleDocs } from '../../types';
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { createClientNameRegex } from '../../utils/create-client-name-regex';
+import { getDocsUrl } from '../../utils/get-docs-url';
+import { getRootIdentifier } from '../../utils/get-root-identifier';
+import { NoRestDestructuringUtils } from './no-rest-destructuring.utils';
+
+export const name = 'no-rest-destructuring';
+
+const createRule = ESLintUtils.RuleCreator<ExtraRuleDocs>(getDocsUrl);
+
+const queryHooks = [
+  'useQuery',
+  'useQueries',
+  'useInfiniteQuery',
+  'useSuspenseQuery',
+  'useSuspenseQueries',
+  'useSuspenseInfiniteQuery',
+];
+
+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: [
+      {
+        type: 'object',
+        properties: {
+          clientNamePattern: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{}],
+
+  create: (context) => {
+    const option =
+      (context.options[0] as { clientNamePattern?: string } | undefined) ?? {};
+
+    const clientRegex = createClientNameRegex(option.clientNamePattern);
+
+    const queryResultVariables = new Set<string>();
+
+    return {
+      CallExpression: (node) => {
+        if (node.parent.type !== AST_NODE_TYPES.VariableDeclarator) return;
+
+        const callee = node.callee;
+        if (callee.type !== AST_NODE_TYPES.MemberExpression) return;
+        const hookName = getHookNameIfTargetFromClient(clientRegex, callee);
+        if (!hookName) return;
+        const returnValue = node.parent.id;
+
+        if (hookName !== 'useQueries' && hookName !== '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',
+          });
+        }
+      },
+    };
+  },
+});
+
+function getHookNameIfTargetFromClient(
+  clientRegex: RegExp,
+  callee: TSESTree.MemberExpression
+): string | undefined {
+  if (callee.property.type !== AST_NODE_TYPES.Identifier) return;
+  const name = callee.property.name;
+  if (!queryHooks.includes(name)) return;
+  const root = getRootIdentifier(callee.object);
+  return root && clientRegex.test(root.name) ? name : undefined;
+}

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

@@ -0,0 +1,11 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } 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,137 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import type { ExtraRuleDocs } from '../../types';
+import { AST_NODE_TYPES, ESLintUtils } from '@typescript-eslint/utils';
+import { createClientNameRegex } from '../../utils/create-client-name-regex';
+import { getDocsUrl } from '../../utils/get-docs-url';
+import { getRootIdentifier } from '../../utils/get-root-identifier';
+
+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: [
+      {
+        type: 'object',
+        properties: {
+          clientNamePattern: { type: 'string' },
+        },
+        additionalProperties: false,
+      },
+    ],
+  },
+  defaultOptions: [{}],
+
+  create: (context) => {
+    const option =
+      (context.options[0] as { clientNamePattern?: string } | undefined) ?? {};
+    const clientRegex = createClientNameRegex(option.clientNamePattern);
+
+    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;
+        if (reactHookNames.includes(calleeName) || calleeName in hookAliasMap) {
+          // Return the actually used identifier (could be alias)
+          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)
+      ) {
+        return node.callee.property.name;
+      }
+      return undefined;
+    }
+
+    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)
+            ) {
+              hookAliasMap[specifier.local.name] = specifier.imported.name;
+            }
+          });
+        }
+      },
+
+      VariableDeclarator(node) {
+        if (node.init?.type !== AST_NODE_TYPES.CallExpression) return;
+        const hook = isQueryHookFromClient(clientRegex, node.init);
+        if (!hook) return;
+        if (node.id.type === AST_NODE_TYPES.Identifier) {
+          trackedVariables[node.id.name] = hook;
+        }
+      },
+      CallExpression: (node) => {
+        const reactHook = getReactHook(node);
+        if (!reactHook) return;
+        if (node.arguments.length <= 1) return;
+        if (node.arguments[1]?.type !== AST_NODE_TYPES.ArrayExpression) return;
+
+        const depsArray = node.arguments[1].elements;
+        depsArray.forEach((dep) => {
+          if (dep?.type !== AST_NODE_TYPES.Identifier) return;
+          const queryHook = trackedVariables[dep.name];
+          if (!queryHook) return;
+          context.report({
+            node: dep,
+            messageId: 'noUnstableDeps',
+            data: {
+              queryHook,
+              reactHook,
+            },
+          });
+        });
+      },
+    };
+  },
+});
+
+function isQueryHookFromClient(
+  clientRegex: RegExp,
+  call: TSESTree.CallExpression
+): string | null {
+  if (call.callee.type !== AST_NODE_TYPES.MemberExpression) return null;
+  const member = call.callee;
+  if (member.property.type !== AST_NODE_TYPES.Identifier) return null;
+  const hook = member.property.name;
+  if (!allHookNames.includes(hook)) return null;
+  const root = getRootIdentifier(member.object);
+  if (!root) return null;
+  return clientRegex.test(root.name) ? hook : null;
+}

package/src/rules.ts

@@ -0,0 +1,17 @@
+import type { ESLintUtils } from '@typescript-eslint/utils';
+import type { ExtraRuleDocs } from './types';
+import * as noRestDestructuring from './rules/no-rest-destructuring/no-rest-destructuring.rule';
+import * as noUnstableDeps from './rules/no-unstable-deps/no-unstable-deps.rule';
+
+export const rules: Record<
+  string,
+  ESLintUtils.RuleModule<
+    string,
+    ReadonlyArray<unknown>,
+    ExtraRuleDocs,
+    ESLintUtils.RuleListener
+  >
+> = {
+  [noRestDestructuring.name]: noRestDestructuring.rule,
+  [noUnstableDeps.name]: noUnstableDeps.rule,
+};

package/src/types.ts

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

package/src/utils/create-client-name-regex.ts

@@ -0,0 +1,32 @@
+export function createClientNameRegex(clientNamePattern: string | undefined) {
+  clientNamePattern = clientNamePattern?.trim();
+
+  if (clientNamePattern) {
+    // Check if pattern is in regex format: /pattern/flags
+    const regexMatch = clientNamePattern.match(/^\/(.*)\/([gimuy]*)$/);
+
+    if (regexMatch) {
+      const regexPattern = regexMatch[1].trim();
+      const flags = regexMatch[2];
+
+      // Validate that regex pattern is not empty or whitespace-only
+      if (regexPattern === '') {
+        throw new Error(
+          'clientNamePattern cannot be empty or contain only whitespace'
+        );
+      }
+
+      return new RegExp(regexPattern, flags);
+    }
+
+    // Fallback to treating as plain string pattern
+    return new RegExp(clientNamePattern);
+  } else if (clientNamePattern === '') {
+    throw new Error(
+      'clientNamePattern cannot be empty or contain only whitespace'
+    );
+  }
+
+  // Default if no pattern provided
+  return /qraft|api/i;
+}

package/src/utils/get-docs-url.ts

@@ -0,0 +1,2 @@
+export const getDocsUrl = (ruleName: string): string =>
+  `https://openapi-qraft.github.io/openapi-qraft/docs/eslint/${ruleName}`;

package/src/utils/get-root-identifier.ts

@@ -0,0 +1,25 @@
+import type { TSESTree } from '@typescript-eslint/utils';
+import { AST_NODE_TYPES } from '@typescript-eslint/utils';
+
+export function getRootIdentifier(
+  node: TSESTree.Node
+): TSESTree.Identifier | undefined {
+  let current: TSESTree.Node | undefined = node;
+  while (
+    current.type === AST_NODE_TYPES.MemberExpression ||
+    current.type === AST_NODE_TYPES.TSNonNullExpression ||
+    current.type === AST_NODE_TYPES.ChainExpression
+  ) {
+    if (current.type === AST_NODE_TYPES.MemberExpression) {
+      current = current.object;
+      continue;
+    }
+    if (current.type === AST_NODE_TYPES.TSNonNullExpression) {
+      current = current.expression;
+      continue;
+    }
+
+    current = current.expression;
+  }
+  return current.type === AST_NODE_TYPES.Identifier ? current : undefined;
+}