useSuspenseQuery and enabled v5

[ahammer-sc]

Hello, I am trying to upgrade to v5, but i have some queries that need to be enabled or disabled based on some parameters, but I also want to use suspense with them. Unfortanately, when i switch to useSuspenseQuery we cannot use enabled. But if I try to use useQuery with enabled and suspense: true i get typescript errors. How are we supposed to fix this error:

 Object literal may only specify known properties, and 'suspense' does not exist in type 'UseQueryOptions<_, Error, _, QueryKey>'

Another issue when migrating, is we have suspense: true and placeholderData: () => readFromCache - this happens when we watch to populate the cache of a query based on the data of other query that is (probably) already in the cache. However, this object is a partial, and just allows us to start rendering some thing ASAP while the more expensive query gets run in background immediately. Is this pattern also possible in v5? useSuspenseQuery does not seem to support this. I can do this without suspense, but then i cannot use suspense for that query 😢

[TkDodo]

enabled is not included because one of the main expectations of suspense is that if you call useSuspenseQuery, data will be T, not T | undefined, because loading states are handled by suspense and errors by error boundaries. That's not the case if we allow to disable a query. Further, you don't need it for dependent queries, because with suspense, queries run in serial anyways. If you need enabled to wait for user input, component composition is the way to go (splitting components up)

or, you can just return null from the queryFn:

useQuery({
  queryKey['something', param],
  queryFn: () => fetchSomething(param),
  enabled: !!param
})

becomes:

useSuspenseQuery({
  queryKey['something', param],
  queryFn: () => param ? fetchSomething(param) : null,
})

regarding placeholderData: I need to think about it. The idea was that placeholderData isn't really needed with suspense because for showing previous data, you would use transitions. For static data, you could still use initialData. On type level, they are the same.

[austinh]

Yes to all of this ^ we will not be able to migrate to v5 and will likely be stuck on v4

[TkDodo]

Ideally, we'd keep suspense on useQuery with a deprecation notice for the next major.

It was clearly marked as experimental from the beginning, because suspense for data fetching was also experimental. We could've even make the change in a v4 minor, but we did it in a major anyways. So putting your decision to build hundreds of components on an an experimental pattern is nothing you can put on my plate.

Having queries run in serial is sometimes what you want though. We have plenty of of dependent queries and conditional queries that also leverage suspense which is quite nice to work with.

Sure, can you please show an example component? Dependent queries work with suspense out of the box without needing enabled at all ...

[olivierbeaulieu]

So putting your decision to build hundreds of components on an an experimental pattern is nothing you can put on my plate.

That's fair, but it doesn't seem like it would be hard to provide a transition path here, given the suspense option still exists on useBaseQuery?

(Let me know if this would be best discussed in a separate issue since it's unrelated to the original point)

Sure, can you please show an example component? Dependent queries work with suspense out of the box without needing enabled at all ...

Sure thing, lemme whip something up. Thank you for your replies!

[olivierbeaulieu]

On the topic of migrating to v5, it seems like a viable path would be to migrate all v4 suspense usage to @suspensive/react-query, and once that's done you can move to v5 easily since the API appears to be the same.

[TkDodo]

The suspense option still exists, but that's an implementation detail. We changed the public api first so that we can change things internally later for a better integration with react suspense.

Right now, we still just throw a promise, but if that api changes, we'll do it differently. I'm not sure if adding enabled back, even if we get the typings right, will then make that integration harder.

[austinh]

Thanks for getting back to me so quickly! The enabled comments makes sense. When you say component composition, what do you mean? The reason we need enabled is that sometimes the param is undefined, and we don't want to make a request yet in that case . I guess the best way to handle this is like you said, in the queryFn. But im curious what an example of component composition looks like - im unfamiliar with that term.

As for the placeholderData, I think i see what you mean. InitialData wont work for us because it gets stored in the cache, and its a partial result. I guess with suspense, we would need to move it to the fallback prop, but then, i need to read directly from the cache of another query to render that partial fallback. It would work, but its a little messy since we are calling this hook all over the place. The placeholderData makes it so that it’s much cleaner and the rest of the components dont care how or where that placeholderData comes from - if its partially available render a partial view, if its fully available, render full view, if its not available at all, show loading spinner. V4 allowed us to do this while also using suspense.

[TkDodo]

So we can't call hooks conditionally, but we can render components conditionally and move the hooks there:

instead of:

const [param, setParam] = useState()

const { data } = useQuery({
  queryKey['something', param],
  queryFn: () => fetchSomething(param),
  enabled: !!param
})

you would do:

const [param, setParam] = useState()

<div>
{param && <MyQueryComponent param={param} />
</div>

then inside MyQueryComponent, you can run the query as you like because param is always defined.

and its a partial result

Just saying: TypeScript wouldn't allow partial results either for placeholderData ;)

[TkDodo]

I think we could add placeholderData back in the non-function form.

[ahammer-sc]

Yeah it would be valuable for the current scenario:

interface Person {
  id: string;
  name: string;
  avatarUrl: string;
}

interface PersonWithDetails extends Person {
   details?: Record<string, string>;
   // ... other expensive/large to fetch fields here
}


// returns Person[]
function usePeople() {
   return useSuspenseQuery({
     queryKey: ["people-list"]
   });
}

// returns PersonWithDetails
function usePersonWithDetails(id: string) {
  return useSuspenseQuery({ 
    queryKey: "...",
    placeholderData() { // ... get from usePeople cache "people-list" and do a .find(p => p.id => id)}
  );
}

Here is the user flow:

1. User goes to /people list page.
   react query usePeople() hook fetches from a backend a list of Person (Person[])
   ----> it suspends and shows a loading fallback, then shows the list of persons

2. User clicks on people going to /people/:id
   ----> usePersonWithDetails(id) will have nothing in cache, but it will already have a simplified partial of the data
   ----> there is already data in the cache via placeholderData so i want to render right way (no suspense fallback)
   ----> while we are rendering a partial view (where details is null), react query is fetching the more expensive endpoint in background and we can show a placeholder. The user can still interact with the rest of the page, just not things that aren't fully ready yet.

All of this is fully typesafe, because the application expects that sometimes we may not have those extra detailed fields.

If the user goes to /people/:id first (nothing in cache from previous people list query) - the user will see the full suspense fallback with a larger loading spinner and we load the full PeopleWithDetails results anyways.

<Suspense fallback={<Loading />}>
if(placeholderData) showPlaceHolder
if(fullData) showFullData;
</Suspense>

If there is a way to do this with transitions, or with initialData, feel free to suggest. This is a contrived example to make it easy to explain on github, but actually, its more complicated in the real world app im working on.

[maxsbelt]

I'm trying to migrate codebase to v5 and I've faced an issue with the new useQuery and useSuspenseQuery separation. I've used useQuery that way:

const query = useQuery({
   queryFn: () => apiCall(params),
   queryKey: ['someKey', params],
   suspense: true,
   keepPreviousData: true,
})

And it've worked that way:

• user opens the page and see loader from <Suspense />
• once list is loaded user can see the content
• user types query in search field
• params in queryKey are updated so it triggers new API call. User still can see previous data and there is an loader displayed in the right bottom of the page that indicates that data is updating.
• data is updated so user can see the new list (loader disappear)

So with a new useSuspenseQuery there is no keepPreviousData or placeholderData parameter so when user changes the filter user can't see the previous data only loader from <Suspense /> component. Maybe is there any suggestion/best practice how I can achieve described behaviour with v5?

[TkDodo]

you want react transitions. This is documented here:

https://tanstack.com/query/v5/docs/react/guides/suspense

and it links right to the react docs:

https://react.dev/reference/react/Suspense#preventing-unwanted-fallbacks

keepPreviousData was a way to give suspense like behaviour to useQuery without having to use suspense. It's not needed if you use suspense, because react can do this out of the box.

[artem-malko]

By the way, is it a good idea to use useQuery in that places, where you need enabled? useSuspenseQuery and useQuery shares the same cache if they have the same queryKey.

@TkDodo what do you think about it?