setQueryDefaults more granularity with predicate function

[paulobmarcos]

Hey TanStack team 👋

Problem

There are times when developers may need more granularity when setting query defaults.

Disclaimer: The examples bellow are just for demonstration purposes.

Just as an example, let's say there are a few endpoints:

• /post/{id}/likes
• /post/{id}/comments
• /post/{id}/views

Let's also say cache keys are defined like this:

• ["post", {id}, "likes"]
• ["post", {id}, "comments"]
• ["post", {id}, "views"]

If there is a need to invalidate all caches for a specific post, it can easily be done with:

queryClient.invalidateQueries({
  queryKey: ['post', 5],
})

If there is a need to invalidate only the comments cache for all posts it's still easily managed with a predicate:

queryClient.invalidateQueries({
  predicate: (query) =>
    query.queryKey[0] === 'post' &&
    query.queryKey[2] === 'comments'
})

However, if we want to set a query default for all comments query keys, it's not really possible since setQueryDefaults does not provide a similar predicate.

If we rearranged cache keys from most generic to most specific, it could mitigate this but it would introduce a tradeoff when we want to invalidate all caches for a specific post:

queryClient.invalidateQueries({
  queryKey: ['post', 'likes', 5],
});
queryClient.invalidateQueries({
  queryKey: ['post', 'comments', 5],
});
queryClient.invalidateQueries({
  queryKey: ['post', 'views', 5],
});

There are also other scenarios where rearranging the keys from most generic to most specific could introduce challenges.

Currently, we have an issue where cache key factories are auto generated for hundreds of endpoints and rearranging them can lead to collisions or mismatches.

Idea

To make React Query even more flexible and adaptable to many different scenarios, it would be great to introduce a similar "match function" to setQueryDefaults.

Example:

queryClient.setQueryDefaults(
  (query) =>
    query.queryKey[0] === 'post' &&
    query.queryKey[2] === 'comments',
  {
    staleTime: Infinity,
    gcTime: Infinity,
  },
);

Or:

queryClient.setQueryDefaults(
  (queryKey) =>
    queryKey[0] === 'post' &&
    queryKey[2] === 'comments',
  {
    staleTime: Infinity,
    gcTime: Infinity,
  },
);

Even if anyone wanted to encapsulate completely different query keys with the same query defaults it would provide an easier/single way of doing so.

This would not be a breaking change, just an extension of setQueryDefaults.

Would this be something worth pursuing? If so, I will gladly contribute with the change.

[TkDodo]

My suggestion in these cases would be to re-structure your query keys to be one object, because objects have no order:

[{ entity: "post", id, type: "likes" }]
[{ entity: "post", id, type: "comments" }]
[{ entity: "post", id, type: "views" }]

because then you can do:

queryClient.invalidateQueries({
  queryKey: [{ entity: 'post', type: 'comments'}]
})

and it'll match all ids. You can then do the same with queryClient.setQueryDefaults.

[paulobmarcos]

Thanks @TkDodo, that's definitely possible!

From these examples, it's quite clear that we can split it by "entity" and "type".

Disclaimer: The examples bellow are just for demonstration purposes.

Let's imagine a couple of different endpoints:

• /books/{id}/authors/followers
• /books/{id}/publishers/followers
• /books/{id}/publishers/clients
• /libraries/{lib_id}/shelves/{shelve_id}/books/{book_id}

Unless we manually define and create good "keys" for each of the sub-paths, it would be quite hard to achieve a good cache key object structure.

In our real world scenario we have hundreds of endpoints, for which we auto generate cache key factories, that are all quite different and can have multiple "sub-paths"/"levels".

Unfortunately, it's also not always possible to have neat RESTful endpoints that match well with our query keys 😞

That's the reason why I think it would still be useful to provide the same flexibility we have with invalidateQueries in setQueryDefaults.

I'm probably not aware of a reason why it would only make sense for invalidate but not for defaults, though.

[TkDodo]

query defaults can be "stacked", you can e.g. see that in this test:

• query/packages/query-core/src/__tests__/queryClient.test.tsx

  Lines 137 to 148 in 3ef7887

  	test('should merge defaultOptions', async () => {
  	const key = queryKey()
  	queryClient.setQueryDefaults([...key, 'todo'], { suspense: true })
  	queryClient.setQueryDefaults([...key, 'todo', 'detail'], {
  	staleTime: 5000,
  	})
  	expect(
  	queryClient.getQueryDefaults([...key, 'todo', 'detail']),
  	).toMatchObject({ suspense: true, staleTime: 5000 })
  	})

we call setQueryDefaults twice with keys that are a sub-set of each other, and the result gets merged. So, we need the key for that and can't have a function.

[paulobmarcos]

Hey @TkDodo!

So I did a quick test and figured out that it's still possible to achieve the exact same results with the ability to set a function.

Here is what the test looked like after the change:

test('should merge defaultOptions', async () => {
  const key = queryKey()

  queryClient.setQueryDefaults(
    (qKey) => typeof qKey[0] === 'string' && qKey[0].startsWith('query_'),
    { gcTime: 10000 }
  )
  queryClient.setQueryDefaults([...key, 'todo'], { suspense: true })
  queryClient.setQueryDefaults([...key, 'todo', 'detail'], {
    staleTime: 5000,
  })

  expect(
    queryClient.getQueryDefaults([...key, 'todo', 'detail']),
  ).toMatchObject({ suspense: true, staleTime: 5000, gcTime: 10000 })
})

This is the change that was necessary in getQueryDefaults:

In setQueryDefaults there's a check to see if it's a queryKey or a function that receives one as a param and returns a boolean if it matches.

Would you mind if I open a PR for further evaluation?