RFC: Combine keepPreviousData with placeholderData

[TkDodo]

Motivation

The API surface of TanStack query is quite large, and we have a couple of things that do seemingly similar things as different config options. keepPreviousData and placeholderData are two of those that are very similar:

• they are both used to show some data that does not logically belong to the current query while the current query if initially loading.
• they are both not persisted to the cache (because they don't belong to the current query)
• they are both no longer shown once the query completes (either successfully, or with an error)

The interesting thing is further: You cannot show both previousData and placeholderData at the same time. We also return two flags from useQuery: isPreviousData and isPlaceholderData. Again, you cannot be both things at the same time, because only "one data" can be shown.

If you supply both things, it is an implementation detail about what takes precedence:

useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
  placeholderData: { "id": -1, "title": "my fake post" },
  keepPreviousData: true
})

if we show the first post, we would of course see the placeholderData. If we would then switch the queryKey and transition to the second post, we would likely still see data from the first post (due to keepPreviousData). We could however also argue that placeholderData takes precedence and we show this one. It is not clear from the api what binds "stronger", and it could also be kind of an impossible state that you have placeholder and previous data at the same time.

Proposal

We could treat previousData as placeholderData by allowing the placeholderData function syntax to pass the data from previous queries (if one exists) in as parameter. The above example would become:

useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
  placeholderData: (previousData => previousData ?? { id: -1, title: "my fake post" }),
})

Please note: The placeholderData function syntax exists today, it just doesn't receive any parameters.

Advantages

• Reduced api surface: combining two options (and two return flags) into one
• Apparent what is happening: In the functional example, we can clearly see that we keep the previous data if we have any, and use a fake placeholder if not. That wasn't 100% obvious with the current syntax - you need to know that keepPreviousData takes precedence over placeholderData. Or, you had to try it out to see what happens
• Allows for more granular previous data keeping. For example, when switching between posts, you might want to remove the body of the previous post but keep everything else:

useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
  placeholderData: (previousData => previousData ? { ...previousData, body: "" } : undefined )
})

This might also be interesting for infinite queries (e.g. a todo list with filters), where you know that the new query will only have one page, so you can decide to only keep one page of the old query (e.g. to make scrollbars disappear and re-align content earlier):

useInfiniteQuery({
  queryKey: ["todos", filter],
  queryFn: () => fetchTodos(filter),
  placeholderData: (previousData => previousData ? {
    pages: data.pages.slice(0,1),
    pageParams: data.pageParams.slice(0,1),
  } : undefined
})

Differences

There are a couple of slight differences in implementation between the two:

• placeholderData will always put you into success state, while keepPreviousData will give you the status of the previous query. That status could be error if we have data fetched successfully and then got a background refetch error. However, the error itself is not shared. This doesn't seem quite right in any case...

• keepPreviousData will give you the dataUpdatedAt timestamp of the previous data, while with placeholderData, dataUpdatedAt will stay at 0. This might be annoying if you want to show that timestamp continuously on screen.

Both of these things are edge case differences and largely irrelevant. If we treat previousData like placeholderData, I would argue to keep things aligned with the current implementation of placeholderData

Drawbacks

• it's more syntax in user-land. To get the same behaviour as keepPreviousData, you would need:

useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
- keepPreviousData: true,
+ placeholderData: previousData => previousData,
})

• you'll lose dataUpdatedAt from previous queries

Alternatives considered

We could introduce a Symbol for keepPreviousData that users could import and pass to placeholderData to get the same behaviour as now:

import { keepPreviousData } from '@tanstack/react-query'

useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
  placeholderData: keepPreviousData
})

this also reads nice and still combines the api into one field. We could do this instead of the function syntax, however, it has the distinct drawback that you cannot do what you can do now, which is: show a placeholder for the first query, and then when the key changes, show data from the previous query (see the initial example).

We could however do this additionally to avoid users having to pass placeholderData: previousData => previousData. In that case, instead of a symbol, we could also export an identity function.

Unknowns

There is quite some code for useQueries that make sure keepPreviousData works (somewhat). In an Array of dynamic length, it is not easy to find out which the "previous" query was. I'm not sure if we can (and should) keep the behaviour there, or if we would just always pass undefined to the placeholderData function.

Closing thoughts

keepPreviousData might become less relevant as we move more towards suspense and starTransition. By wrapping the state setting that changes the query key into startTransition, you can achieve the same behaviour as keepPreviousData. You can see that in the suspense example. So, moving away from a dedicated flag might be a good thing, and the more verbose syntax to achieve what we have today might not be so relevant in the grand scheme...

[DamianOsipiuk]

This totally makes sense.

About the differences:

keepPreviousData will give you the dataUpdatedAt timestamp of the previous data, while with placeholderData, dataUpdatedAt will stay at 0.

I not entirely sure about the implementation of this, but to inject the placeholderData argument, we probably have a handle to the previous query anyway?
Could we enhance it even more to retain access to previous query attributes with

placeholderData: (previousData, previousQuery) => {
  return previousQuery.dataUpdatedAt > myTimestamp ? previousData : { myNewPlaceholder: 'foo' };
}

or even

placeholderData: (previousQuery) => {
  return previousQuery.dataUpdatedAt > myTimestamp ? previousQuery.data : { myNewPlaceholder: 'foo' };
}

Not sure if this is feasible though.

[TkDodo]

I think I wasn't clear in my description - I was referring to this implementation:

query/packages/query-core/src/queryObserver.ts

Lines 475 to 478 in 1614c31

	data = prevQueryResult.data
	dataUpdatedAt = prevQueryResult.dataUpdatedAt
	status = prevQueryResult.status
	isPreviousData = true

This enables you to render dataUpdatedAt on screen and keep its value while transitioning to the next query. For example:

const { data, dataUpdatedAt } = useQuery({
  queryKey: ["post", id],
  queryFn: () => fetchPost(id),
  keepPreviousData: true
}

return (
  <div>
    <Post data={data} />
    <span>Updated at: {dataUpdatedAt}</span>
  </div>
)

if you transition from one post to the next, dataUpdatedAt will always be a timestamp. With the placeholderData solution, you will:

• see the timestamp of the first post
• go to the next
• briefly see 0
• see the timestamp of the new post

Unless wee expect users to also return the previous dataUpdatedAt from the placeholderData function, or we do something like placeholderDataUpdatedAt (which isn't very ergonomic), you wouldn't be able to do this anymore. But maybe that's okay...

[DamianOsipiuk]

In theory you could useMemo to cache the value and bail from update if dataUpdatedAt is 0?
So there would be a workaround if someone is relying on it always being there.

[TkDodo]

Hmm how would that code look like? There isn't really a way to bail from updating in userland

[DamianOsipiuk]

Something along:

const [updatedAt, setUpdatedAt] = useState(0)

const { data, dataUpdatedAt } = useQuery(['projects', page], () => fetchProjects(page))
  
useEffect(
  () => {
    if (dataUpdatedAt > updatedAt) {
      setUpdatedAt(dataUpdatedAt)
    }
  },
  [dataUpdatedAt]
)

useMemo won't work since you still need memoized value to reference if it's != 0

Nevertheless if someone really needs to display this timestamp all the time without flashes, there will be a way to achieve that.

[TkDodo]

you're right - this would indeed work 👍

[vaynevayne]

I don't use placeholder data, let me talk about my business scenario:
A table with server-side page flipping,

When I am on page n, if the data of this page is pre-fetched by me, or already exists in the cache, then I hope that loading will not be displayed,
On the contrary, when I come to the nth page for the first time, I want to display the loading. My purpose is to have something that allows me to control whether the loading is displayed. It is like a judgment result to judge whether there is this page in the cache. data

[TkDodo]

this should be the default behaviour without you doing anything extra (no placeholderData, no keepPreviousData) ...

[vaynevayne]

Do you mean that you can use isFetching directly?
If data is fetched from the cache,isFetching is false?

[TkDodo]

I don't fully understand what you are trying to achieve so please show a codesandbox reproduction. Just from your writing:

const [page, setPage] = useState(0)

const queryInfo = useQuery({
  queryKey: ['something', page],
  queryFn: () => fetchSomething(page)
})

• you'll get a loading state for page 0, then data is in the cache for that page
• you go to page 1, get a loading state, then data
• you go to page 2, get a loading state, then data
• you go back to page 1, you get data from the cache immediately, no loading state

[vaynevayne]

1, get a loading state

loading state mans query.isLoading , I thought it was isFetching,
isLoading is only related to the first request. If page changes,isLoading will not change and is still false

[TkDodo]

isLoading is only related to the first request. If page changes,isLoading will not change and is still false

if page changes and it is part of the queryKey, as it should be, you will get a "hard loading state" again because there will be no data in the cache for that key. You're not showing your code so I'm still guessing what you are doing or not doing 🤷

[vaynevayne]

about isPreviousData mean use cacheData ? if no, i think need add a flag

const Demo = () => {
  const [page, setPage] = useState(1)
  const params = {
    username: '',
    page: page,
  }
  const { isFetching, data, isPreviousData } = useQuery({
    queryKey: ['post', params],
    queryFn: () => axios.post('post', params),
    keepPreviousData: true,
  })

  // if it is  first fetching some page,show loading, else hide loading
  if (isPreviousData && isFetching) {
    return 'loading'
  }

  return (
    <>
      <div>{data}</div>
      <button onClick={() => setPage(page - 1)}> - </button>
      {page}
      <button onClick={() => setPage(page + 1)}> + </button>
    </>
  )
}

@TkDodo

[TkDodo]

about isPreviousData mean use cacheData ?

no, again, that's not what it means. it means keep the data from the previous queryKey when the queryKey changes. it has nothing to do with cached data for the same key ...

in the code snippet you've shown, just remove keepPreviousData: true and don't check for isPreviousData

[vaynevayne]

IsFetching doesn't solve the problem, you don't want to show loading when you're using the cache to fill the data, but isDetching is trunkIsFetching does not solve the problem. When filling data with cache, you do not want to show loading but isDetching is true

[TkDodo]

is misread that in your code.

if (isLoading) {
  return 'loading'
}

this works

[vaynevayne]

You don't understand what I mean. Let me rephrase it, keepPreviousData is associated with queryKey, isPreviousData is associated with keepPreviousData, but IsPreviouseData is not associated with queryKey. Is there a problem?

[TkDodo]

you're right, I don't understand what you mean. We're talking past each other. Please show a codesandbox reproduction that clearly shows your problem. Everything else is just pointless.

[bennettdams]

Sorry for bike-shedding!

TL;DR I think the new placeholderData's two use cases is what you conceptually think of as "initial data".

---

Now that placeholderData has an additional use case, maybe it's also a good time to rename it?

When I hear "placeholder", I think about static, made-up data.
Before this change, it was clear that placeholderData is used for when a query initially runs, so you can show some local data.
But now it is also used for the "start data" of a new query (via the previousData param).

The field now has two different use cases.

(For anyone wondering, the second use case still works totally fine with placeholderData(previousData => ...))
https://codesandbox.io/s/admiring-mclaren-82nvyg?file=/src/App.tsx

I just think that the naming now could be confusing.

But the existing initialData has a different meaning right now, as it is also used to fill the cache of the query, which you most probably don't want to do with the two described use cases.

With that in mind, we could rename like so to better represent their usage:

initialData -> initialCacheData
This would actively represent the purpose, which is to also fill the cache.

placeholderData -> initialData
This would now conceptually bring the naming closer to the mindset of "here's some data to show while my query initially fetches".

[TkDodo]

placeholder is still a conceptually valid name because for the current Query, you're using data from the previously observed Query as placeholder until your request settles (either resolves or rejects). So, it is "fake" data, because it has nothing to do with the Query you are currently observing. It's what react refers to as deferredValue (from the useDeferredValue hook).

previousData and keepPreviousData is what has been misleading to many, because "previous" of what? It refers to data from a previous observer, which is only relevant when the queryKey changes...

initialCacheData is a good idea, but I think it's not a big difference / gain. We can communicate that initialData refers to data being used when the cache entry is initially created.