new useQueries API

[TkDodo]

just taking an Array of useQuery objects doesn't cover all the cases, because some options have to be the same for all queries, for example suspense or useErrorBoundary: We can't really have one query in the list suspend and some other query not suspend. Conceptually, useQueries is also more than a bunch of useQuery calls chained together.

Proposed solution

make useQueries take an object as input, where we can define top level options that are true for all queries and a list of queries, something like:

useQueries({
    queries: [{ queryKey1, queryFn1, options1 }, { queryKey2, queryFn2, options2 }],
    suspense: boolean,
    useErrorBoundary: boolean
})

[arnaudbzn]

if a query has suspense:false and the top level option is suspense:true, what would be the best behavior?

• remove suspense from the query option TypeScript type for useQueries
• throw a runtime error
• ignore the query option

[TkDodo]

omit it from the options on type level and ignore it at runtime is the plan.

[TkDodo]

If you know any other options that should be hoisted, please let me know :)

[arnaudbzn]

omit it from the options on type level and ignore it at runtime is the plan.

I'm not a huge fan of "silent" anomalies at runtime (from the developer point of view who set the option at the query level and could expect a certain behavior).

You may have this case with the current useQueries where one query do use suspense and another don't.

[TkDodo]

You may have this case with the current useQueries where one query do use suspense and another don't.

suspense doesn't work at all for useQueries at the moment, and having one suspend and the other not is exactly the issue that sparked this re-design. There is an old PR (#2109) that tries do to it, and the best thing we could come up with is suspending as soon as any of the queries suspends. That's pretty much the same as this proposal, except that this is more explicit.

from the developer point of view who set the option at the query level and could expect a certain behavior

hmm, imho, the options just doesn't exist anymore on that level in v4. TypeScript will enforce that, and we'll also highlight it in the migration guide. It is equivalent to passing forceFetchOnMount: true to a query and expecting it to do something. This option existed in v2, but not anymore in v3.

[arnaudbzn]

TypeScript will enforce that, and we'll also highlight it in the migration guide. It is equivalent to passing forceFetchOnMount: true to a query and expecting it to do something. This option existed in v2, but not anymore in v3.

It's fine with me!

[lubieowoce]

Some thoughts about mixing suspense settings within a component

Note: This wall of text mostly assumes that mixing suspense settings within a single component is a valid usecase, which reasonable people might disagree on. For an example of when you might want this, see my next comment, but replace "crash" with "suspend". I'm also assuming enabled: true for simplicity.

I originally agreed with this proposal, but now I'm not so sure. Here's how that went.
My original thinking was that an old-style mixed-suspense call like this:

// old API
useQueries([
  { ...A, suspense: false },
  { ...B, suspense: false },
  { ...C, suspense: true },
  { ...D, suspense: true },
])

can always be expressed as two separate calls:

// new API
useQueries({
  queries: [ A, B ],
  suspense: false,
});
useQueries({
  queries: [ C, D ],
  suspense: true,
})

so there's no problem with hoisting the setting out. but...

The issue

The issue is that in the current implementation, mixing suspense settings like this will have some unexpected behavior -
non-suspense queries establish the subscription (and begin fetching) in a useEffect, which won't run if the component suspends. So the non-suspense queries would only start fetching after all the suspense queries are done and the component mounts! Which is pretty bad [1].

Actually, useQuery has the same issue, in that

useQuery({ A, suspense: false });
useQuery({ B, suspense: true });

will behave like await B; await A instead of await Promise.all([A, B]). I'm not quite sure what to do about it, other than move everything over to fetch-during-render[2] instead of the current fetch-in-useEffect, and that feels a bit weird.

But... if we allowed mixing suspense within a single useQueries call, we can handle this case! i.e. if any queries have suspense: true, then we start fetching everything (during render) and suspend on until C & D are ready. Because unlike separate useQuery calls (that don't know about each other), useQueries has all the info available and can do the smart thing. Obviously that's a maintenance/implementaion burden, but it doesn't sound impossible.

Conclusion

At the end of the day, we could just say

If you mix suspense settings in a single component, you're gonna have a bad time. Don't do it!

But allowing it in useQueries, i.e. keeping the current API is actually the one situation where we can do "the right thing" without re-writing everything that uses useEffect. So maybe it's worth considering after all? If this takes a while to implement, we could throw an "Error: mixing suspense settings isn't supported yet", then adding it later would be backwards compatible!

---

[1] As in, we don't want to do the equivalent of this:

await Promise.all([C, D]);
await Promise.all([A, B]);

[2] One way to do this would be to do something like the following: (obviously super simplified)

function useQuery(...) {
  // ...
  // look ma, no useEffect!
  if (shouldFetch) {
    queryClient.scheduleFetch(options) // express an intent to fetch, but don't start it yet
  }
  // ...
}

function QueryClientProvider({ client: queryClient, children }) {
  // ...
  useEffect(() => {
    // Actually perform all the fetches scheduled during render.
    // Assuming there's a Suspense boundary below us, this will run
    // even if a child component suspends!
    queryClient.executeScheduledFetches();
  });
  // ...
}

This way we're doing just a little bit of side-effects, so ...maybe... it's alright to do it during render?

[lubieowoce]

I guess my feelings about useErrorBoundary are similar -- i think mixing them is actually a valid usecase. Something like:

// assuming `suspense: true` for brevity -- i don't feel like typing out `isLoading` stuff :)
const [
  { data: criticalData },
  { data: niceToHaveData }
] = useQueries([
  { ...criticalQuery,   useErrorBoundary: true }, // if this doesn't work, just crash, nothing we can do
  { ...niceToHaveQuery, useErrorBoundary: false }, // we can manage without this one though
]);

return (
  <div>
    <CriticalUI data={criticalData} />
    <NotThatImportantUI data={niceToHaveData ?? "it's okay, we can show a fallback or something"} />
  </div>

EDIT: of course, with a "hoisted" useErrorBoundary, the behavior desired in the example could technically be achieved by any variation of

niceToHaveQuery.queryFn
  .then(data => ({ ok: true, data }))
  .catch(error => ({ ok: false, error }))

but then react-query doesn't know the query failed, so you lose isError, retries, etc, which isn't great.

[TkDodo]

@lubieowoce thank you for your input. I really like the useErrorBoundary example you gave with critical / nice to have queries. That makes a lot of sense if we can make it work like that.

As for suspense, I have very little experience with it. From my last talk with @tannerlinsley, I took away that what we want to achieve is to use the same suspense boundary for all queries that do suspend and fetch them in parallel. The loading should stop when all queries are done.

if we mix suspense true / false within one useQueries, how would that behave? As you said:

the non-suspense queries would only start fetching after all the suspense queries are done and the component mounts!

Yes, you get basically the same with separate useQuery calls / separate useQueries calls, but at least it's explicit.

Changing the api now to an object will give us more room for extensibility in the future to have settings that need to be set for all queries in the list. I thought that suspense would be a good first candidate for it. I agree that useErrorBoundary could be kept separately though.

But allowing it in useQueries, i.e. keeping the current API is actually the one situation where we can do "the right thing"

I don't fully understand that. If users really want to mix suspense / non-suspense, couldn't they just do two separate useQueries with the new api?

[1] As in, we don't want to do the equivalent of this:

Why not? I think this would be the expected behaviour for me. How else should it be?

FYI, with React 18, we will likely move over to useSyncExternalStorage instead of manually fetching in a useEffect, and maybe we'll even someday move to a suspense-cache from react, but all of this sounds like the far away future.

[lubieowoce]

Why not? I think this would be the expected behaviour for me. How else should it be?

If users really want to mix suspense / non-suspense, couldn't they just do two separate useQueries with the new api?

unfortunately they can't. this won't start fetching [A,B,C,D] in parallel (which is what i personally would expect):

useQueries([A, B], { suspense: false }); // #1
useQueries([C, D], { suspense: true }); // #2

because when a component suspends (because of #2), its effects don't run, so #1 won't do observer.subscribe(...) and thus won't start. it'll only start when #2 completes and the component "resumes", rerenders & mounts. so, assuming we're staying with useEffect for now, i don't see a way to start all 4 in parallel without mixed-suspense. as mentioned before, the usecase is the same as my useErrorBoundary example above.

(obviously if we swapped the calls and did the suspense one first, i wouldn't expect them to start in parallel, because control flow wouldn't reach the non-suspense one during the initial render. but it's way less obvious that the order in the example won't be parallel)

please let me know if I can explain anything better! i tried my best to be explicit about the assumptions/expectations i have for the behavior, but maybe I'm missing something :)

[TkDodo]

unfortunately they can't. this won't start fetching [A,B,C,D] in parallel (which is what i personally would expect):

I think it would be fine to suspend two and then start the other two, but yeah, it's not ideal. It's also a question of "who does this?", and "is this really a use-case"? Why would you suspend one query but not the other?

i don't see a way to start all 4 in parallel without mixed-suspense.

the current suspense implementation in useQuery throws the promise during render:

https://github.com/tannerlinsley/react-query/blob/16baba415058a8317cd7fd588c98ab0d56ca6dd2/src/react/useBaseQuery.ts#L116-L129

not sure how useQueries would do that in a mixed array that the non-suspense things start to query while the others are suspending ?

please let me know if I can explain anything better! i tried my best to be explicit about the assumptions/expectations i have for the behavior, but maybe I'm missing something :)

you're doing a very good job explaining me all this suspense stuff, so thank you for that 🙏

[lubieowoce]

not sure how useQueries would do that in a mixed array that the non-suspense things start to query while the others are suspending ?

idk, i wasn't imagining anything fancy, just something in the vein of

if (defaultedOptions.some((q) => q.suspense) {
  const willSuspend = ...
  if (willSuspend) {
    // kick off the ones that don't use suspense
    startFetching(defaultedOptions.filter((q) => !q.suspense))
  }
  // suspend on the ones that *do* use suspense
  throw fetchAll(defaultedOptions.filter((q) => q.suspense));
}

It's also a question of "who does this?", and "is this really a use-case"? Why would you suspend one query but not the other?

well... i would like to do it, sometimes 😁 Here's an example of when you might want this, a variation on the criticalData/niceToHaveData pattern from above:

const Page = () => (
  <div>
    <h1>FooHub</h1>
    <Suspense fallback={<UserWidgetSkeleton />}
      <UserWidget />
    </Suspense>
  </div>
);

const UserWidget = () => {
  const [
    { data: profile },
    repos,
  ] = useQueries([
    { ...profileQuery, suspense: true },
    { ...reposQuery, suspense: false },
  ]);
  return (
    <div>
      <img src={profile.avatarUrl} />
      <h2>@{profile.username}</h1>
      <div>Joined {profile.joinedDate}</div>
      <div>
        {repos.isLoading
          ? <Spinner />
          : `this user has ${repos.data.length} repositories`
        }
      </div>
    </div>
  );
}

The gist is, we can't really show anything until profileQuery is ready, so Suspense works well. But if profileQuery is ready, we want to render a profile-thingy, with a small spinner at the bottom until reposQuery is done.

Of course, you could get around this by preloading stuff on Page, which probably should be happening anyway... but I'm not sure if that means we shouldn't support this pattern. Maybe it does?