blog/the-query-options-api

[giscus[bot]]

blog/the-query-options-api

v5 brought a new, powerful API, especially if you're using React Query with TypeScript...

https://tkdodo.eu/blog/the-query-options-api#inject-comments

[lgenzelis]

That dataTagSymbol TS magic is pure gold! It allowed me to remove lots of unsafe generics from my codebase.

[danfry1]

Wow this is epic! Can't wait to start using queryOptions 🚀

[ginzatron]

Could you expand a little more on what the query-factory achieves and how it differs from "define keys in one central place while having the functions far a way from them in our custom hooks". What was the default patter before react query v5 and how has that changed with the options api? I'm having trouble fitting all the pieces together. Thanks.

[TkDodo]

In the post, I've linked to the article that explains how I did query key factories before:

https://tkdodo.eu/blog/effective-react-query-keys#use-query-key-factories

so, you'd just have a factory that creates keys, and then in your custom hook, you'd do:

const useTodo = (id) => useQuery({
  queryKey: todoKeys.detail(id),
  queryFn: () => fetchTodo(id),
})

[lucsky]

I've been using the query definition pattern for quite a while now and queryOptions will definitely help catch stupid mistakes, but I also have been using mutation definitions, in the same way, but there's no mutationOptions in sight. Why is that?

[TkDodo]

I haven't seen it as necessary to add mutationOptions. I mean if lots of people want it, we can add it, but all the advantages of the queryOptions api are basically gone:

• mutations are almost exclusively triggered by useMutation, so the only abstraction you need is a custom hook. There's not sharing the options between different functions.
• There's no need for the tagging functionality either

If you want type-safety, I think satisfies MutationOptions works well, too.

[abmagil]

I had a long running thread about how I wanted this in v4 so this is a wonderful discovery!

I don't disagree about "necessary" but I ergonomics are a little weird that my factory is tied to the cache and the query, so I can just use the OptionsFactory attribute for the query but I can't use any of it for useMutation and then I can use some of it for modifying my cache data. Example:

const OptionsFactory = {
  ...
  entity: (id: Entity["id"]) => ({queryKey: ['entities', id], queryFn: myGetFn})
}

const { data: entity } = useQuery(OptionsFactory.entity(someId))

const create = useMutation({mutationFn: myPostFn})
const update = useMutation({mutationFn: myPutFn})

create.mutate({onSuccess: (returnedEntity) => queryClient.setCacheData(OptionsFactory.entity(returnedEntity.id) })

The ergonomics are even more pronounced if I were to use onSuccess inside the hook's options, instead of the .mutate's options.

Regardless, since I'd want to PUT and POST to different URLS (PUT /entities/{id} and POST /entities/ for updating and creating, respectively), I'm not sure how to best organize my OptionsFactory to support the various use cases.

[cobyme]

You have ads for Query.gg all over the place, but no way to actually purchase it yet. 😢 Eagerly awaiting that email & Tweet saying it's ready and available to purchase.

[TkDodo]

Hey 👋
I'm working as hard as I can on query.gg, but I only do this part-time. I have a job and a family, too :)

For now, please subscribe to the mailing list and I'll make sure to inform you as soon as we have the first lessons out 🚀

[matzeso]

Great to see typescript improvements coming with v5.
Having read your examples before we also built our newest product using react router + react query with abstracted query definitions, and we also handled the type safety situation by building our own query util function:

import { QueryKey, FetchQueryOptions } from '@tanstack/react-query';

export const createQuery = <
  TQueryFnData = unknown,
  TError = unknown,
  TData = TQueryFnData,
  TQueryKey extends QueryKey = QueryKey,
>(
  options: FetchQueryOptions<TQueryFnData, TError, TData, TQueryKey>,
) => options;

I guess we can replace that after migrating to v5 with the new queryOptions helper :)

[rlesniak]

[TkDodo]

Because it's a different thing? You want infiniteQueryOptions

[rudfoss]

This is a great addition to an already great library! I'm wondering if you have a recommended pattern for when context provided clients are used (or maybe I'm using it wrong to begin with)?

I'm using generated clients (NSwag) that I provide to my application through contexts. This has served me well as an abstraction and allows me to relatively easily set up clients for different environments and use them in my application.

My custom query hooks look something like this:

export const useUserInformation = (userId: string) => {
  const { userInformationClient } = useUserInformationClient()
  return useQuery({
    queryKey: ["users", "byId", id],
    queryFn: () => userInformationClient.getUserInformation(userId),
    ... // other options
  })
}

From my components I can then simply use the hook without knowing about the underlying dependency:

const { data: userInformation } = useUserInformation(userId)

With queryOptions it seems I would have to expose the client in every component that uses the query or maybe capturing the client in a closure or something. How would you recommend I encapsulate the client instance? Or perhaps I should rethink how I structure my "API layer"?

Pure queryOptions:

const userInformationQueries = {
  byId: (client: UserInformationClient, userId: string) => queryOptions({
    queryKey: ["users", "byId", id],
    queryFn: () => client.getUserInformation(userId),
    ... // other options
  })
}

// Usage from a component (works, but must repeat a lot of stuff)
const { userInformationClient } = useUserInformationClient()
const { data: userInformation } = useQuery(userInformationQueries.byId(userInformationClient, userId))

In closure (seems like a better approach if combined with context):

const userInformationQueries = (client: UserInformationClient) => ({
  byId: (client: UserInformationClient, userId: string) => queryOptions({
    queryKey: ["users", "byId", id],
    queryFn: () => client.getUserInformation(userId),
    ... // other options
  })
})

// In a component (could be abstracted to a separate context and provided)
const { userInformationClient } = useUserInformationClient()
const { data: userInformation } = useQuery(userInformationQueries(userInformationClient).byId(userId))

// Or if provided from context (still have multiple lines, but at least it hides the client dependency):
const { byId } = useUserInformationQueries()
const {data: userInformation } = useQuery(byId(userId))

[TkDodo]

I don't think its generally a good idea to have the client live in react context - what's the advantage here? If you're using our eslint plugin, the exhaustive-deps rule will also flag that userInformationClient is used in the queryFn, but it isn't part of the key. You can technically run into stale closure issues if your client ever gets re-created, because the queryFn might not read the latest value then.

So yeah, you avoid all of that if the client doesn't live in react context at all, but is just a stable value that you import.

[rudfoss]

The primary advantage I see is that I'm using the same mechanism to "inject" dependencies for everything. This makes it easier to follow the lifecycle flow of code in the application (IMHO) and configurations can be passed through props just like any other component.

The idea is not that clients vary greatly while the application lives. They are usually instantiated with some configuration on startup and only updated if the user logs in and a token needs to be added to the client headers or some such process. It's rather that I can use one mechanism to pass them around my application along with any other dependencies just like the Tanstack Query Provider provides a centrally configured client. Using contexts means there is no "custom mechanism" to learn for other developers when working with clients and it follows the same lifecycle as any other react component.

I can't seem to agree with myself whether it is cleaner than introducing a "management" mechanism for clients outside of the react tree, hence why I was asking, but it does make for a type-safe and relatively clean API when using the queries and mutations. It will cause some extra re-renders that could be avoided, perhaps by using refs, but at least it follows pre-existing react render- and lifecycle flows.

const createApiClientQueries = (apiClient: IApiControllerClient) => {
  const queries = {
    users: () => ["users"],
    byId: (id: string) => queryOptions({
      queryKey: [...queries.users(), "byId", id]
      queryFn: () => apiClient.getUser(id),
      staleTime: 60_000
    })
  } as const
  return queries
}

// assume the context is defined to contain what is provided in `value`
const ProvideApiClient = ({baseUrl, children}: {baseUrl: string, children: ReactNode) => {
  const [token, setToken] = useState<string>("")
  const apiClient = useMemo(() => new ApiControllerClient(baseUrl, token), [baseUrl, token])
  const queries = useMemo(() => createApiClientQueries(apiClient), [apiClient])

  return (
    <ApiClientContext.Provider value={{apiClient, queries, token, setToken}}>{children}</ApiClientContext.Provider />
  )
}

const UsersPage = () => {
  const { queries, token } = useContext(ApiClientContext)
  const { data } = useQuery({...queries.getUsers(), enabled: !!token })
  const { mutate: login } = useLogin() // Custom mutation hook following suggested pattern

  if (data) {
    return <UsersTable users={data} />
  }

  return <LoginForm onLogin={login} />
}

const App = () => (
  <ProvideApiClient baseUrl="http://localhost:1234">
    <UsersPage />
  </ProvideApiClient>
)

[TkDodo]

the problem is that APIClient depends on token, and if token changes, API client changes. Then, in your queryFn, you call apiClient.getUser, which will then e.g. add the current token as a header parameter.

But since token isn't part of your queryKey, when you invalidate a query, it might read an older queryFn, where the apiClient still has an older token. That's a stale-closure issue. I have a blogpost on this topic: https://tkdodo.eu/blog/hooks-dependencies-and-stale-closures

Our lint rule warns against that, but the solution to add apiClient to the key is wrong unless the client is serializable. Also, you don't really want separate cache entries just because the token changed.

So the solution is to imperatively read the token rather than declaratively depend on it. Like, put it in a ref or a zustand store and in the queryFn call getState().token or whatever

[rudfoss]

ah, sorry. I didn't fully get the queryFn-caching mechanism. That would indeed make this impractical and hide a potentially big problem in a closure... A zustand store would still introduce a new mechanism though as I cannot use the store-hook to create queries so I would have to call it directly.

The issue as I see it still remains though. We have an "injection mechanism" with prop-management in Contexts that is built into React. I want to "inject" dependencies (clients) so they can be used by my components, and manage their lifecycles so that changes that require a new client propagate properly. The client is a dependency the queryFn needs to deal with, but it cannot use the built in dependency injection mechanism or indeed any state mechanism to do so requiring some workaround or external management mechanism (or refs) to work correctly.

I understand your reasoning though and it makes perfect sense, though I'm conflicted in trying to keep it simple by avoiding a new mechanism or by introducing unnecessary wrappers. It seems "correct" to me that parameters provided as props (e.g. baseUrl, tokens etc) should be allowed to follow the lifecycle of react throughout my application. There is probably something wrong with my underlying assumptions here. In any case thanks for replying here. I really appreciate the help! I'll take a step back and grab an extra 🍵 and see if I can rework it from the top to fit with your recommendations.

[TkDodo]

The client is a dependency the queryFn needs to deal with, but it cannot use the built in dependency injection mechanism or indeed any state mechanism to do so requiring some workaround

what you can do is:

• add the client to the queryKey
• implement a custom queryKeyHashFn (globally)
  • serialize the client to some static value, e.g. an id (by using client.getId() or so)
  • serialize everything else with our default hashKey fn (you can import it)
• make sure that id increases / changes every time the client is re-created, like when a new token is issued or baseUrl changes.

that will satisfy the linter and will not have any stale closure problems, while still allowing you to use react-context for dependency injection

[hrachhovsepyanqless]

Thanks for the article, great read! How would you recommend to handle the possibility to add (extend) queryOptions for each query? Let's say I want to disable a certain query in some scenarios, is there any pattern here that handles it in the query factory?

[TkDodo]

you could just pass it as an argument to the function of the factory, or you'd just spread it onto the useQuery call where you need it:

const useMyQuery = () => useQuery({
 ...myQueryOptions(),
 enabled: someCondition
})

[gerardosabetta]

So what if you wanted to make this super flexible but also type safe? is there a way to do

const useMyQuery = (config) => useQuery({
 ...myQueryOptions(),
 ...config
})

while making that config parameter type safe? I'm thinking maybe I don't want to create useMyQueryCount which would be basically the same thing with a select implementation on it. How would you type this config object?

[TkDodo]

I always recommend against doing that. Getting the types 100% right for this, you'd need to implement basically what useQuery is doing, which means 4 type parameters and 3 overloads. It's not worth it. This abstraction doesn't do anything when queryOptions are involved. Suppose I'd want to call:

const { data } = useMyQuery({ refetchInterval: 1000 })

I could just as well do:

const { data } = useQuery({
  ...myQueryOptions(),
  refetchInterval: 1000
})

you need absolutely zero type shenanigans for this. It'll be 100% type safe, even when select is involved. And you can pass that to useQuery or useSuspenseQuery or useQueries or queryClient.prefetchQuery and so on ... queryOptions() is by far the best and likely only abstraction you need to make things type-safe AND super flexible.

[Thanaen]

Thanks for this great article!
I'd love to implement it, but I'm wondering something:
In my application, all requests systematically take a parameter from a store (in this case, zustand). It's useful for determining the URL of the API call, and it's passed in all react-query keys.

What would be the best way to set up a query factory in this situation? I'm thinking that systematically retrieving the value as a parameter from the factory would be very cumbersome, and it would force each component to retrieve the value from the store before calling the query.

I'm thinking I could do a wrap with, say, useUserQuery and useSuspenseUserQuery, which take care of retrieving the value from the store and injecting it, but Typescript won't be happy about that, as I'm using the QueryFunctionContext to determine the parameters of my API helpers...
Do I need to make a wrapper beyond "queryOptions", which automatically adds the "userId" (in my example) to the list of queryKeys?

Sorry if I'm asking a lot, but I'm sure you've come across this situation before 😄

Once again, thank you very much for your work!

[Thanaen]

Follow up on what I've done so far:

I created a "userQueries" function like this:

export const userQueries = (userId: string) => ({
  getUserDetails: () =>
    queryOptions({
      queryKey: ["userDetails", { userId }],
      queryFn: getUserDetails,
    }),
});

Then I created a context like this:

const userQueriesContext = React.createContext<ReturnType<
  typeof userQueries
| null>(null);

export const UserQueriesProvider = ({
  children,
}: ServerQueriesProviderProps) => {
  const userId = useStore(currentUserIdSelector);

  const computedUserQueries = React.useMemo(
    () => userQueries(userId),
    [userId],
  );

  return (
    <userQueriesContext.Provider value={computedUserQueries}>
      {children}
    </userQueriesContext.Provider>
  );
};

I don't think it's too bad!

[Thanaen]

Then all I have to do is call this hook in my components, and voila!

const useUserQueries = () => {
  const context = React.useContext(userQueriesContext);
  if (!context) {
    throw new Error(
      "useUserQueries must be used within a UserQueriesProvider",
    );
  }
  return context;
};

This also allows me to invalidate / interact with queries outside of React components, since I can easily call my "userQueries" function by passing it the userId by hand!

[TkDodo]

I'd make a custom hook:

export const useUserDetailsOptions = () => {
  const userId = useStore(currentUserIdSelector)

  return queryOptions({
    queryKey: ["userDetails", { userId }],
    queryFn: getUserDetails,
  })
}

[Arcades2]

So cool as always ! For the query factory would you still recommend the queryKey as an array of one object like in your article "Leveraging the Query Function Context" ? I love the fact that it forces me to put in the queryKey what I need in my queryFn. That way, there's less chance of misidentifying my query.

[TkDodo]

yeah I still do that, but it doesn't matter as much if key + fn are colocated

[wuarmin]

Hey,
just one question about prefetching in the context of tanstack Router: Which react query function do you recommend for prefetching in the route (loader-fn)? I keep seeing ensureQueryData in the router examples. Here you mention prefetchQuery. What is the right one? And why?

Thanks for your great Work!

[TkDodo]

I prefer ensureQueryData because of the reasons outlined here:

• https://tkdodo.eu/blog/react-query-meets-react-router#getquerydata--fetchquery

[dreyescabrera]

Thanks a lot Dom. Couldn't we do something similar with mutations?

[TkDodo]

There isn't really a need for something similar for mutations because:

• they have no key, so the dataTag association between key / fn isn't necessary.
• you can thus just make a function that returns something that satisfies MutationOptions and you're good to go.