Proposal: Extend support for combined queries

[jasongerbes-vista]

Query options make it easy to encapsulate and reuse individual query configurations across hooks and queryClient methods:

import { queryOptions } from "@tanstack/react-query";

function groupOptions(id: number) {
  return queryOptions({
    queryKey: ["groups", id],
    queryFn: () => fetchGroups(id),
    staleTime: 5 * 1000,
  });
}

useQuery(groupOptions(1));
useSuspenseQuery(groupOptions(5));

queryClient.fetchQuery(groupOptions(10));
queryClient.prefetchQuery(groupOptions(23));
queryClient.ensureQueryData(groupOptions(42));

The same options can also be passed to useQueries to combine multiple queries together:

const groupIds = [1, 5, 10, 23, 42];

const combined = useQueries({
  queries: groupIds.map((id) => groupOptions(id)),
  combine: (results) => ({
    data: results.map((r) => r.data),
    pending: results.some((r) => r.isPending),
  }),
});

However, combined queries are limited to the useQueries hook. There is currently:

• No built-in way to encapsulate queries + combine into a reusable options object.
• No queryClient methods for fetching or prefetching combined queries on the server.

Proposal

Introduce a combineQueryOptions utility that applies the queryOptions pattern to combined queries:

import { combineQueryOptions } from "@tanstack/react-query";

function groupListOptions(groupIds: number[]) {
  return combineQueryOptions({
    queries: groupIds.map((id) => groupOptions(id)),
    combine: (results) => ({
      data: results.map((r) => r.data),
      pending: results.some((r) => r.isPending),
    }),
  });
}

useQueries(groupListOptions([1, 5, 10, 23, 42]));

And add methods to queryClient that support combined query options:

queryClient.fetchQueries(groupListOptions([1, 5, 10, 23, 42]));
queryClient.prefetchQueries(groupListOptions([1, 5, 10, 23, 42]));
queryClient.ensureQueriesData(groupListOptions([1, 5, 10, 23, 42]));

This would allow combined queries to be just as reusable and portable as individual queries, and enable server-side fetching/prefetching of combined queries.