useSuspenseQuery is awkward

[artem-malko]

Hi)

Till v5.7.2 I lived like a boss with useQuery and

suspense: true,
throwOnError: false

cause I need to handle errors in my components, near any query usage. I have a lot of queries, where my backend can answer with an error. And this error can have a useful body. For example, 403 error with a description about restrictions.

But, in 5.7.2 you've removed the suspense option. So, I have to switch to useSuspenseQuery. And, as I can see from the source code it is not possible to override throwOnError option. It's just a function, which returns typeof query.state.data === 'undefined'. And yeah, there is info about it in docs. That is ok. But now it is not possible for me to resolve my issue in a comfortable way for me. I have to create several wrappers around every component with useSuspenseQuery like:

<ErrorBoundary
      FallbackComponent={(error) => <div>{JSON.stringify(error)}</div>}
    >
      <Suspense fallback={<Preloader />}>
        <CompWithUseSuspenseQueryInside />
      </Suspense>
    </ErrorBoundary>

Moreover, if I need a boundary reset, I have to wrap it with one more wrapper: <QueryErrorResetBoundary>. Every time! And the last thing — useTransition inside my component.

Ok, it is a react way. So, I need to be adaptive. But it is so painful. It was like a charm, when we had suspense and working throwOnError option.

And there is an interesting case. I have a query, which has refetchInterval. This query requests a user info in a background. And I have SSR with renderToPipeableStream from React. So, when I had throwOnError: false, this query didn't affect my render, when there was any error. But now, my global Error boundary is used, cause I have to use useSuspenseQuery to make it works on server side too. I need that user's info to be fetched on my server side. Looks like I need a separate component with useSuspenseQuery({ queryFunction: fetchUser, refetchInterval: 3600 }), that has to be wrapped with Suspense and ErrorBoundary instead of just a custom hook with useSuspenseQuery({ queryFunction: fetchUser, refetchInterval: 3600 }) inside.

I have to say, useSuspenseQuery is a really interesting idea. And I can understand your motivation to remove the suspense option. But not the throwOnError. Yes, data now can not be undefined. But what is the price?)

By the way, what if I want to render errors from my back and I do not want to refetch on client after SSR? I just can not imagine, how to implement it with useSuspenseQuery.

So, the main question is — is it possible (or you have any ideas about it) to set throwOnError to false for useSuspenseQuery? How can I handle errors with data inside in a convenient way? Should I work with react-query in a react-way only?

[TkDodo]

But, in 5.7.2 you've removed the suspense option

suspense was left accidentally on the typings of the defaultOptions. It shouldn't have been there with v5, sorry.

So, I have to switch to useSuspenseQuery.

That's the intended API change for v5, yes.

is not possible to override throwOnError

that is correct. if you were to set throwOnError: false, we couldn't guarantee that data would be defined when the component renders, because it could be in error state, where it wouldn't have data. The idiomatic react way to handle errors with suspense is to use error boundaries. We've slightly modified this with the function so that stale data is kept for background errors.

And yeah, there is info about it in docs.

yes there is: https://tanstack.com/query/v5/docs/react/guides/suspense#throwonerror-default

I have to wrap it with one more wrapper: . Every time!

This is easily abstractable into a QueryErrorBoundary component.

Ok, it is a react way. So, I need to be adaptive. But it is so painful. It was like a charm, when we had suspense and working throwOnError option.

Yes, it's the react way. Suspense is an architectural change, not just a way to show a global loading spinner.

I need that user's info to be fetched on my server side.

You can still use a useQuery and prefetching + hydration on the server. suspense + streaming is a very new thing.

By the way, what if I want to render errors from my back and I do not want to refetch on client after SSR?

Again, this is how suspense is designed by react. If it fails to fetch on the server, it will render the fallback on the client and re-fetch there. Only if that fails, the error boundary will be shown.

[artem-malko]

@TkDodo glad to see you in the discussion)

I was sure you would say that) I mean, React-way is a new way for us. That makes sense. But for the convenience it would be nice to have working throwOnError. By the way, it's not obviously, that throwOnError is not working for useSuspense*Query. And sorry, but I don't know the correct way how to name this option(

You can still use a useQuery and prefetching + hydration on the server. suspense + streaming is a very new thing.

What do you mean by suspense + streaming is a very new thing? Do you mean, that there are no any correct ways, which are approved by maintainers to handle suspense + streaming?

You can still use a useQuery and prefetching + hydration is not working for me. And looks like a legacy approach, when we have renderToPipeableStream)

[TkDodo]

@TkDodo glad to see you in the discussion)

did you expect someone else 😅

By the way, it's not obviously, that throwOnError is not working for useSuspense*Query

we have it documented though, a) in the link I sent above and b) in the api docs: https://tanstack.com/query/v5/docs/react/reference/useSuspenseQuery

I've just seen that the API docs for suspense are missing in the navigation bar. Will fix this asap.

What do you mean by suspense + streaming is a very new thing

suspense on the server only works since next13 and app directory, because that's the only framework currently that supports suspense on the server with streaming and partial hydration. If you call useSuspenseQuery in the next13 app directory, the fetch will happen on the server, but for it to wind up in the QueryClient in the browser too, you need our experimental next streaming suspense plugin: https://tanstack.com/query/v5/docs/react/guides/advanced-ssr#experimental-streaming-without-prefetching-in-nextjs

or you need to prefetch in a server component manually. All of this is documented, we took a lot of effort to re-write the docs around server side rendering. Please read them.

when we have renderToPipeableStream

I don't know what that means exactly. Are you using a framework for server side rendering or not?

[artem-malko]

suspense on the server works not only in Next ;) https://github.com/artem-malko/react-ssr-template/blob/main/src/framework/applications/server/utils/reactStreamRenderEnhancer.ts#L50

We have a nice discussion about it — #2942

I'll update my demo to make it work with useSuspenseQuery. Just need to add wrappers, but the main idea from https://github.com/artem-malko/react-ssr-template/blob/main/src/framework/applications/server/utils/reactStreamRenderEnhancer.ts#L50 won't be changed.

[TkDodo]

suspense on the server works not only in Next

this does look a lot like our next adapter 👍

[artem-malko]

By the way, do you have a working group or branch or pull request? If you need any help I'd like to help)

You're talking about https://github.com/TanStack/query/tree/main/packages/react-query-next-experimental as I understand?

[artem-malko]

@TkDodo sorry to bother you, but there are some strange things in useSuspsenseQuery and useInfinitySuspenseQuery.

1. As you mentioned before, data can not be undefined. But, what if my API responses with empty body, but with 200 code. I know, sounds quite strange. I can get a requested data from cookies or other headers. But in useSuspsenseQuery and useInfinitySuspenseQuery such queries throws an error(

2. As you mentioned before, data can not be undefined and all loading/error states have to be handled in a react way. But why do we have isError, isLoadingError, isRefetchError, isPending , isLoading and event status flags in useSuspsenseQuery and useInfinitySuspenseQuery? Looks like, these flags have to be false all the time in a component with a query? The same idea is about error, errorUpdateCount, failureCount, failureReason and errorUpdatedAt.

Actually, looks like that all is* flags (exceptions are isFetch* flags like isFetching and etc) are useless. Should we remove them from typings in useSuspsenseQuery and useInfinitySuspenseQuery? Looks like, my suggestion is quite interesting, cause you said in #6095

because you don't need to handle loading states (handled by suspense boundary) and error states (handled by error boundaries)

3. What about retries? Pls, correct me if I'm wrong, but after the first thrown error my ErrorBoundary renders a fallback without that query, which had thrown the error. So, retries are impossible?

[TkDodo]

1. if you want to return something empty from the queryFn, it can't be undefined - it has to be null or something else. This is independent of suspense - undefined is reserved for pending or error state, and we use it to bail out of state updates, too. It can't be used for a "successful" query.
2. The flags are there because we return the same thing as useQuery. Internally, the same observer is used, and that's where the result comes from. But you should see that some of these flags, like isPending, have a fixed value, and status is just success or error. Background refetches can still happen and they can also error, which means your query can be in error state and render accordingly. We think its better to show stale data than always show an error screen, which is why errors are still exposed, and you can be in error state and render the component for refetch errors.
3. retries are an internal process. The query only throws when it reaches error state, and the error state is only reached after all retries have failed. Until then, the query is pending.

[artem-malko]

Thx for your answer)