Merge branch 'alpha' into feature/usequeries-combine

TanStack · May 15, 2023 · b318428 · b318428
2 parents 35149d0 + e76a2c3
commit b318428
Show file tree

Hide file tree

Showing 16 changed files with 39 additions and 30 deletions.
diff --git a/docs/react/guides/placeholder-query-data.md b/docs/react/guides/placeholder-query-data.md
@@ -16,9 +16,11 @@ There are a few ways to supply placeholder data for a query to the cache before
 - Imperatively:
   - [Prefetch or fetch the data using `queryClient` and the `placeholderData` option](../guides/prefetching)
 
+When we use `placeholderData`, our Query will not be in a `pending` state - it will start out as being in `success` state, because we have `data` to display - even if that data is just "placeholder" data. To distinguish it from "real" data, we will also have the `isPlaceholderData` flag set to `true` on the Query result.
+
 ## Placeholder Data as a Value
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 
 ```tsx
 function Todos() {
@@ -30,16 +32,13 @@ function Todos() {
 }
 ```
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 [//]: # 'Memoization'
 
 ### Placeholder Data Memoization
 
 If the process for accessing a query's placeholder data is intensive or just not something you want to perform on every render, you can memoize the value:
 
-[//]: # 'Memoization'
-[//]: # 'Example2'
-
 ```tsx
 function Todos() {
   const placeholderData = useMemo(() => generateFakeTodos(), [])
@@ -51,13 +50,25 @@ function Todos() {
 }
 ```
 
-[//]: # 'Example2'
+[//]: # 'Memoization'
+
+## Placeholder Data as a Function
+
+`placeholderData` can also be a function, where you can get access to the data and Query meta information of a "previous" successful Query. This is useful for situations where you want to use the data from one query as the placeholder data for another query. When the QueryKey changes, e.g. from `['todos', 1]` to `['todos', 2]`, we can keep displaying "old" data instead of having to show a loading spinner while data is _transitioning_ from one Query to the next. For more information, see [Paginated Queries](../guides/paginated-queries).
+
+```tsx
+const result = useQuery({
+  queryKey: ['todos', id],
+  queryFn: () => fetch(`/todos/${id}`),
+  placeholderData: (previousData, previousQuery) => previousData,
+})
+```
 
 ### Placeholder Data from Cache
 
 In some circumstances, you may be able to provide the placeholder data for a query from the cached result of another. A good example of this would be searching the cached data from a blog post list query for a preview version of the post, then using that as the placeholder data for your individual post query:
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 
 ```tsx
 function Todo({ blogPostId }) {
@@ -75,7 +86,7 @@ function Todo({ blogPostId }) {
 }
 ```
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 [//]: # 'Materials'
 
 ## Further reading

diff --git a/docs/react/reference/useQuery.md b/docs/react/reference/useQuery.md
@@ -148,11 +148,11 @@ const {
 - `initialDataUpdatedAt: number | (() => number | undefined)`
   - Optional
   - If set, this value will be used as the time (in milliseconds) of when the `initialData` itself was last updated.
-- `placeholderData: TData | (previousValue: TData) => TData`
+- `placeholderData: TData | (previousValue: TData | undefined; previousQuery: Query | undefined,) => TData`
   - Optional
-  - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` data and no initialData has been provided.
+  - If set, this value will be used as the placeholder data for this particular query observer while the query is still in the `pending` state.
   - `placeholderData` is **not persisted** to the cache
-  - If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available
+  - If you provide a function for `placeholderData`, as a first argument you will receive previously watched query data if available, and the second argument will be the complete previousQuery instance.
 - `structuralSharing: boolean | ((oldData: TData | undefined, newData: TData) => TData)`
   - Optional
   - Defaults to `true`

diff --git a/docs/vue/guides/placeholder-query-data.md b/docs/vue/guides/placeholder-query-data.md
@@ -4,7 +4,7 @@ title: Placeholder Query Data
 ref: docs/react/guides/placeholder-query-data.md
 ---
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 
 ```tsx
 const result = useQuery({
@@ -14,12 +14,10 @@ const result = useQuery({
 })
 ```
 
-[//]: # 'Example'
+[//]: # 'ExampleValue'
 [//]: # 'Memoization'
 [//]: # 'Memoization'
-[//]: # 'Example2'
-[//]: # 'Example2'
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 
 ```tsx
 const result = useQuery({
@@ -35,6 +33,6 @@ const result = useQuery({
 })
 ```
 
-[//]: # 'Example3'
+[//]: # 'ExampleCache'
 [//]: # 'Materials'
 [//]: # 'Materials'
diff --git a/packages/query-async-storage-persister/package.json b/packages/query-async-storage-persister/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-async-storage-persister",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "A persister for asynchronous storages, to be used with TanStack/Query",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/query-broadcast-client-experimental/package.json b/packages/query-broadcast-client-experimental/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-broadcast-client-experimental",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "An experimental plugin to for broadcasting the state of your queryClient between browser tabs/windows",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/query-core/package.json b/packages/query-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-core",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "The framework agnostic core that powers TanStack Query",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/query-devtools/package.json b/packages/query-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-devtools",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Developer tools to interact with and visualize the TanStack Query cache",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/query-persist-client-core/package.json b/packages/query-persist-client-core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-persist-client-core",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Set of utilities for interacting with persisters, which can save your queryClient for later use",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/query-sync-storage-persister/package.json b/packages/query-sync-storage-persister/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/query-sync-storage-persister",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "A persister for synchronous storages, to be used with TanStack/Query",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/react-query-devtools/package.json b/packages/react-query-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query-devtools",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Developer tools to interact with and visualize the TanStack/react-query cache",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/react-query-persist-client/package.json b/packages/react-query-persist-client/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query-persist-client",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "React bindings to work with persisters in TanStack/react-query",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/react-query/package.json b/packages/react-query/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/react-query",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in React",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/solid-query/package.json b/packages/solid-query/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-query",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Solid",
   "author": "tannerlinsley",
   "license": "MIT",

diff --git a/packages/svelte-query-devtools/package.json b/packages/svelte-query-devtools/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-query-devtools",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Developer tools to interact with and visualize the TanStack/svelte-query cache",
   "author": "Lachlan Collins",
   "license": "MIT",

diff --git a/packages/svelte-query/package.json b/packages/svelte-query/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/svelte-query",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Svelte",
   "author": "Lachlan Collins",
   "license": "MIT",

diff --git a/packages/vue-query/package.json b/packages/vue-query/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/vue-query",
-  "version": "5.0.0-alpha.31",
+  "version": "5.0.0-alpha.32",
   "description": "Hooks for managing, caching and syncing asynchronous and remote data in Vue",
   "author": "Damian Osipiuk",
   "license": "MIT",