RFC: @tanstack/query/prefer-query-options

[Newbie012]

Separating queryKey and queryFn can cause unexpected runtime issues when the same query key is accidentally used with more than one queryFn.

Rule Details

Examples of incorrect code for this rule:

/* eslint "@tanstack/query/prefer-query-options": "error" */

function Component({ id }) {
  const query = useQuery({
    queryKey: ["get", id],
    queryFn: () => Api.get(`/foo/${id}`),
  });
  // ...
}

/* eslint "@tanstack/query/prefer-query-options": "error" */

function useFooQuery() {
  return useQuery({
    queryKey: ["get", id],
    queryFn: () => Api.get(`/foo/${id}`),
  });
}

Examples of correct code for this rule:

/* eslint "@tanstack/query/prefer-query-options": "error" */

const options = queryOptions({
  queryKey: ["get", id],
  queryFn: () => Api.get(`/foo/${id}`)
});

function Component({ id }) {
  const query = useQuery(options);
  // ...
}

/* eslint "@tanstack/query/prefer-query-options": "error" */

const options = queryOptions({
  queryKey: ["get", id],
  queryFn: () => Api.get(`/foo/${id}`),
});

function useFooQuery() {
  return useQuery({ ...options, select: (data) => data.foo });
}

Options

ignorePatterns

An array of strings used to ignore specific query key patterns:

{
  "@tanstack/query/prefer-query-options": [
    "error",
    {
      "ignorePatterns": {
        "startsWith": ["ignore-key"],
        "endsWith": ["ignore-key"],
        "includes": ["ignore-key"],
      }
    }
  ]
}

collections

An array of strings used to enforce the use of queryOptions in specific collections of queries:

{
  "@tanstack/query/prefer-query-options": [
    "error",
    {
      "collections": ["fooQueries", "deeply.nested.queries"]
    }
  ]
}

When Not To Use It

If you do not want to enforce the use of queryOptions in your codebase, you will not need this rule.

Attributes

• ✅ Recommended
• 🔧 Fixable.

[TkDodo]

love it ❤️ . One question that remains is if we want to add this to the recommended ruleset, and if so, on which level ?

[Newbie012]

While I do advocate for co-locating queryKey and queryFn I feel like this rule is a bit more opinionated than the others. Maybe we could add recommendedStrict config and add it there.

[camjackson]

I would absolutely love for this to exist. I've just spent a bunch of time going through my repo and making sure we are using queryOptions helpers everywhere. Including both:

• functions that take the whole options object like useQuery
• functions that take just the key like getQueryData, as this helps greatly with type inference as per the docs

I really want to lock this down via eslint so that someone can't come and undo my hard work. In lieu of a proper dedicated rule like the one proposed here, I did manage to create a pretty gnarly set of no-restricted-syntax queries to enforce this.

Here's what I came up with:

// Selectors to find relevant react-query function calls
const callAFunctionThatTakesQueryOptions = 'CallExpression[callee.name=/^(useQuery|useSuspenseQuery)$/]'
const callAMethodThatTakeQueryOptions =
  'CallExpression[callee.property.name=/^(invalidateQueries|fetchQuery|removeQueries|getQueriesData)$/]'
const callAMethodThatTakesAQueryKey = 'CallExpression[callee.property.name=/^(getQueryData|setQueryData)$/]'

// "Assertions" to enforce that the first argument is either `fooQueryOptions()` or `fooQueryOptions().queryKey`
const firstArgMustBeSomethingQueryOptions = '[arguments.0.callee.name!=/.+QueryOptions/]'
const firstArgMustBeSomethingQueryOptionsDotQueryKey =
  ':matches([arguments.0.object.callee.name!=/.+QueryOptions/],[arguments.0.property.name!="queryKey"])'

// DRY-ing up the error messages
const queryOptionsDocs = `

See: https://tanstack.com/query/v5/docs/framework/react/guides/query-options`

// Glue it all together
const queryOptionsRules = [
  {
    selector: `${callAFunctionThatTakesQueryOptions}${firstArgMustBeSomethingQueryOptions}`,
    message: `Generate the query options using a helper e.g. \`profileQueryOptions()\` ${queryOptionsDocs}`,
  },
  {
    selector: `${callAMethodThatTakeQueryOptions}${firstArgMustBeSomethingQueryOptions}`,
    message: `Generate the query options using a helper e.g. \`profileQueryOptions()\` ${queryOptionsDocs}`,
  },
  {
    selector: `${callAMethodThatTakesAQueryKey}${firstArgMustBeSomethingQueryOptionsDotQueryKey}`,
    message: `Look up the queryKey using a queryOptions helper e.g. \`profileQueryOptions().queryKey\` ${queryOptionsDocs}`,
  },
]

Like I said, it's pretty gnarly, and it has some rough edges. I haven't listed every single function (e.g. use/fetchInfiniteQuery), only the ones that I'm using. And it doesn't allow for spreading and overriding of the query options as in this example from the docs:

// this is not allowed by the above rules :(
const query = useQuery({
  ...groupOptions(1),
  select: (data) => data.groupName,
})

It might be technically possible to cover every edge case with no-restricted-syntax but it would be difficult. It would be much better to have a first class rule to check this stuff.