Provide better support for parallel fetching with Suspense

[SebKranz]

The current api for suspense (useSuspenseQuery and useSuspenseQueries) makes waterfalls far too likely - especially when combined with custom hooks. In the original API, two tasks, initiating the fetch and reading the result, are done in the same call.

const students = useQuery('students') // initiates fetch, and provides result when ready
const teachers = useQuery('teachers') // initiates the fetch at the same time as above

This made a lot of sense when React required all hooks to be called unconditionally on every render.
However, with the introduction of suspense, this isn't guaranteed anymore. It is now far more likely that some fetches wont be initiated until others have finished. As a result, waterfalls become much more likely, and nearly every component that fetches multiple endpoints must require explicit consideration from the developer to prevent this.

While waterfalls can be avoided with useQueries or prefetching, it is much more difficult to work around when you want to extract logic into custom hooks.

const useStudents = () => useSuspenseQuery('students')
const useTeachers = () => useSuspenseQuery('teachers')

function CourseView() {
  useStudents()
  useTeachers() // will fetch only once useStudents is complete

  return <>...</>
}

In the above example, theres no obvious way to execute both custom hooks at the same time. I could prefetch queries in advance, but then CourseView must have knowledge of all the query keys that my custom hooks will use.
As a result, it is far more difficult to decouple logic and implement custom hooks independently of each other.
Further, since useSuspenseQuery and useQuery are different hooks, I can't simply configure my custom hook to use Suspense conditionally (useStudents({ withSuspense: false })). Instead, I need to implement multiple versions: useStudents and useStudentsSuspending.

Alternative solution

I would suggest disconnecting the place where the fetch is initiated, from the place where the result is read.

Add a suspending function .read() to UseQueryResult.

function MyComponent() {
  const resultA = useQuery()
  const resultB = useCustomHook()

  const a = resultA.read() // suspends
  const b = resultB.read()
  
  return <>{a}{b}</>
}

This has the following advantages:

• Custom hooks can be suspense-agnostic.
• There are no changes for users who just want to continue using useQuery without suspense.
• Components can flexibly & dynamically decide whether they want to manually handle loading states or suspend.

For example, I can imagine a design where a component extracts some data from the result, before passing it to a suspending component:

function SearchResults() {
  const results = useQuery(...)
  return <>
    { results.isSuccess ? `${results.data.length} results` : 'loading' }
    <Suspense ...>
      <ResultView results={results} />
    </Suspense>
  </>
}

function ResultView(props: { results: UseQueryResult<...> }) {
  const results = props.results.read()
  ...
}

[TkDodo]

Those are all valid points, and I think this is an intentional design decision by React Suspense. If you compare this to a server component, you'll have the same problem if you do:

async function CourseView() {
  const students = await fetchStudents()
  const teachers = await fetchTeachers()
}

maybe its more obvious because the syntax is async/await, but its the same problem. The react way to solve this is to split things up into multiple components (component composition). Even if they are in the same suspense boundary, fetches will start in parallel.

If you don't want to do that, you can useSuspenseQueries, because we use Promise.all internally:

const [students, teachers] = useSuspenseQueries({
  queries: [
    { queryKey: ['students'], queryFn: fetchStudents },
    { queryKey: ['teachers'], queryFn: fetchTeachers },
  ]
})

---

I think the read proposal could potentially work IF we could use the new use hook already, but that RFC hasn't gone anywhere in the last year.

I also don't see how this example is much different:

function MyComponent() {
  const resultA = useQuery()
  const resultB = useCustomHook()

  const a = resultA.read() // suspends
  const b = resultB.read()
  
  return <>{a}{b}</>
}

Here, when resultA.read() will suspend, we haven't initiated a fetch for B either, so how will this be parallelized ?

---

cc @Ephem I know you like to prevent fetch waterfalls and you're currently writing the docs on suspense / SSR, so maybe there's something I'm missing here?

[Ephem]

Thanks for opening this discussion (and the ping)!

I agree with a lot of the points you make @SebKranz and I need some time to process and digest. We have thought a little about separating fetch and read, but have kind of pushed it ahead to later when the use implementation is stable, but maaybe we don't have to..?

Here, when resultA.read() will suspend, we haven't initiated a fetch for B either, so how will this be parallelized ?

@TkDodo I don't think this is a problem, it's the useQuery that starts the fetch, so by the time you do .read() on A, B is already in flight.

I'm not sure we'd have to wait for use, it's possible we could move throwing the promise we currently do today to later in the .read() function instead..

I think there might be downsides to using the regular useQuery hook for both though. Could get confusing with two separate loading states (isLoading etc from RQ and the suspending from Suspense). Not sure if this could also mean mismatches and race conditions where these gets out of sync, practically it might not be possible(/feasible) to implement it this way. On the other hand, it's also pretty attractive, I definitely think this is worth pondering and investigating a bit.

Interestingly, if we could make it work, I think we could possibly do it without breaking current Suspense usage either. If suspense: true, we throw immediately (that useQuery is an instant .read() so to speak). Otherwise the developer can choose to Suspend (even if suspense: false) by calling .read().

I'll give this some deep thought this week.

(And yes, I'm mostly finished with a new Request Waterfalls doc page and a rewritten and more fleshed out Prefetching doc page, but those doesn't currently tackle the custom hook case)

[TkDodo]

I don't think this is a problem, it's the useQuery that starts the fetch, so by the time you do .read() on A, B is already in flight.

just wanted to point out that this is, as of right now, incorrect. useA() and useB() both only schedule a fetch - it would happen in an effect. If a call to resultA.read() would then suspend, B still hasn't started to fetch.

If suspense: true, we throw immediately (that useQuery is an instant .read() so to speak). Otherwise the developer can choose to Suspend (even if suspense: false) by calling .read().

Not sure I understand this. In v5, there is no suspense:boolen flag anymore. We have a separate useSuspenseQuery hook, which always suspends if there is no data yet.

[SebKranz]

@TkDodo , That's right, I had missed this.

Effects don't run on suspending components, so useBaseQuery({ suspense: true }) will initiate the fetch in the render function, whereas normally it would happen via the subscription callback in useSyncExternalStore.
So if this functionality was joined into useQuery as described above, useQuery would need to initiate the fetch while rendering, just in case someone wants to read() it.

Another flaw that I noticed in the .read() approach, is that you might still find unavoidable waterfalls if you have parallel dependent queries:

// (Assumes that the fetch is initiated on useQuery)
const a = useA()
const b = useB()
const aa = useQueryDependentOnA(a.read())
const bb = useQueryDependentOnB(b.read()) // potentially blocked by a

I originally thought this was avoidable by directly the query state in these cases. The reason why i found it appealing to use useQuery for both suspending and non-suspending flows, is that it would allow spinning off dependent queries before suspending for the result.

// (Assumes that the fetch is initiated on useQuery)
function useCustomHook() {
  const resultA = useA() 
  const resultAA = useQueryDependentOnA(a.data, { enabled: a.isSuccess })

  return {
    read: () => {
      const a = resultA.read()
      const aa = resultAA.read()
      return combine(a, aa)
    }
  }
}

However, even this doesn't work as intuitively expected:

// (Assumes that the fetch is initiated on useQuery)
function useStudentsWithGrades() {
  const a = useA() 
  const aa = useQueryDependentOnA(a.data, { enabled: a.isSuccess })
  const b = useB()
  const bb = useQueryDependentOnB(b.data, { enabled: b.isSuccess }) // ⚡ bb wont be initiated until a, aa and b are done

  a.read()
  aa.read()
  b.read()  
  bb.read()
}

I'm getting the feeling that, if custom hooks should continue to be a primary use-case, and we don't want to rely on prefetching, there might be no way around a system similar to promises, where developers can combine and transform queries before awaiting them all in a single line:

const a = useQuery(...)
const b = useQuery(...)
const transformedA = a.map(() => { ... })
Queries.all([a, b]).read()

But I also understand that this might overcomplicate the library.

[Ephem]

just wanted to point out that this is, as of right now, incorrect. useA() and useB() both only schedule a fetch - it would happen in an effect. If a call to resultA.read() would then suspend, B still hasn't started to fetch.

@TkDodo Absolutely true, sorry, I was being sloppy with my wording. I meant that in this example it would start fetching in useQuery/render which as we talked about offline maaybe, possibly could be made to work, but would be tricky in practice.

I do think decoupling fetch/read is a great use case to support (and one we could probably introduce even before use is stable) but after thinking about it and talking to @TkDodo I think it makes more sense to introduce in a minor as separate hooks.

[enszrlu]

Is there any update to this? @Ephem

Did you find a solution to your problem? I am facing the same bottleneck now. @SebKranz

[SebKranz]

There now seems to be an experimental API, but I haven't looked at it yet.

For the time, I've been very happy with the excellent queryOptions-API. Rather than writing custom hooks, write functions to generate query-options:

function queryA() {
    return queryOptions({
        queryKey: ...
        queryFn: ...
    })
}

Then you have way more flexibility in how you use the queries. You can...

A: ...run multiple queries in parallel:

useSuspenseQueries({
	queries: [queryA(), queryB()]
})

B: ...prefetch queries in your loader functions: Prefetching & Router Integration | TanStack Query React Docs

In cases with an unavoidably complex graph of dependent queries, it could also make sense to use an atomic state manager. We happened to still have an rxjs dependency, so I used that. But jotai might work too (I haven't tried).