Why useSuspenseQuery works

Fellow reader Michael had a great question about yesterday's email – Why does this work!?

How does the Birthdays component use the return value from useBirths before the request is complete? Is it an empty array at first, and if so how? births.map is called below, so we assume it's an array at the point of first render.

Here's the code again:

const Birthdays: FC<{ day: Date }> = ({ day }) => {
  const births = useBirths(day)

  return <Table data-testid="birthday-list">
	  <tbody>
        {births.map((birth, index) => ( //...
  </Table>
}

Why can we call births.map and assume it's an array?

That's the clever trick behind React Suspense – in JavaScript you can throw a promise.

You've seen throw new Error() before. That lets you stop execution of your code when there's a problem and jump into the catch block of a try/catch.

But you don't have to throw an error. You could throw a different object and give it special behavior in the catch block. That's what React does with Suspense – it catches unresolved promises thrown from your component tree then comes back to finish rendering when the promise resolves.

That means somewhere inside useSuspenseQuery there will be code that throws your queryFn. Let's see ...

Yep, here it is

// Handle suspense
if (shouldSuspend(defaultedOptions, result)) {
  // Do the same thing as the effect right above because the effect won't run
  // when we suspend but also, the component won't re-mount so our observer would
  // be out of date.
  throw fetchOptimistic(defaultedOptions, observer, errorResetBoundary)
}

If we're using suspense, throw the promise returned by fetch.

Brilliant 🤩

~Swizec