Merge branch 'main' into feat/mutation_support_signal_input

TanStack · Mar 5, 2024 · 145bb9f · 145bb9f
2 parents ff67f11 + f366cae
commit 145bb9f
Show file tree

Hide file tree

Showing 91 changed files with 505 additions and 270 deletions.
diff --git a/docs/framework/angular/guides/disabling-queries.md b/docs/framework/angular/guides/disabling-queries.md
@@ -67,3 +67,27 @@ export class TodosComponent {
 ```
 
 [//]: # 'Example2'
+[//]: # 'Example3'
+
+```ts
+@Component({
+  selector: 'todos',
+  template: `
+    <div>
+      // 🚀 applying the filter will enable and execute the query
+      <filters-form onApply="filter.set" />
+      <todos-table data="query.data()" />
+    </div>
+  `,
+})
+export class TodosComponent {
+  filter = signal('')
+
+  todosQuery = injectQuery(() => ({
+    queryKey: ['todos', this.filter()],
+    queryFn: this.filter ? () => fetchTodos(this.filter()) : skipToken,
+  }))
+}
+```
+
+[//]: # 'Example3'
diff --git a/docs/framework/react/guides/disabling-queries.md b/docs/framework/react/guides/disabling-queries.md
@@ -12,7 +12,9 @@ When `enabled` is `false`:
 - The query will not automatically fetch on mount.
 - The query will not automatically refetch in the background.
 - The query will ignore query client `invalidateQueries` and `refetchQueries` calls that would normally result in the query refetching.
-- `refetch` returned from `useQuery` can be used to manually trigger the query to fetch.
+- `refetch` returned from `useQuery` can be used to manually trigger the query to fetch. However, it will not work with `skipToken`.
+
+> Typescript users may prefer to use [skipToken](#typesafe-disabling-of-queries-using-skiptoken) as an alternative to `enabled = false`.
 
 [//]: # 'Example'
 
@@ -92,3 +94,33 @@ If you are using disabled or lazy queries, you can use the `isLoading` flag inst
 `isPending && isFetching`
 
 so it will only be true if the query is currently fetching for the first time.
+
+## Typesafe disabling of queries using `skipToken`
+
+If you are using TypeScript, you can use the `skipToken` to disable a query. This is useful when you want to disable a query based on a condition, but you still want to keep the query to be type safe.
+
+> IMPORTANT: `refetch` from `useQuery` will not work with `skipToken`. Other than that, `skipToken` works the same as `enabled: false`.
+
+[//]: # 'Example3'
+
+```tsx
+function Todos() {
+  const [filter, setFilter] = React.useState<string | undefined>()
+
+  const { data } = useQuery({
+      queryKey: ['todos', filter],
+      // ⬇️ disabled as long as the filter is undefined or empty
+      queryFn: filter ? () => fetchTodos(filter) : skipToken,
+  })
+
+  return (
+      <div>
+        // 🚀 applying the filter will enable and execute the query
+        <FiltersForm onApply={setFilter} />
+        {data && <TodosTable data={data}} />
+      </div>
+  )
+}
+```
+
+[//]: # 'Example3'
diff --git a/docs/framework/react/react-native.md b/docs/framework/react/react-native.md
@@ -138,6 +138,6 @@ function MyComponent() {
     notifyOnChangeProps,
   })
 
-  return <div>DataUpdatedAt: {dataUpdatedAt}</div>
+  return <Text>DataUpdatedAt: {dataUpdatedAt}</Text>
 }
 ```
diff --git a/docs/framework/react/typescript.md b/docs/framework/react/typescript.md
@@ -227,3 +227,8 @@ For tips and tricks around type inference, have a look at [React Query and TypeS
 the Community Resources. To find out how to get the best possible type-safety, you can read [Type-safe React Query](./community/tkdodos-blog#19-type-safe-react-query).
 
 [//]: # 'Materials'
+
+## Typesafe disabling of queries using `skipToken`
+
+If you are using TypeScript, you can use the `skipToken` to disable a query. This is useful when you want to disable a query based on a condition, but you still want to keep the query to be type safe.
+Read more about it in the [Disabling Queries](./guides/disabling-queries.md) guide.
diff --git a/docs/framework/vue/guides/disabling-queries.md b/docs/framework/vue/guides/disabling-queries.md
@@ -53,3 +53,24 @@ const { data } = useQuery({
 ```
 
 [//]: # 'Example2'
+[//]: # 'Example3'
+
+```vue
+<script setup>
+import { useQuery, skipToken } from '@tanstack/vue-query'
+
+const filter = ref('')
+const isEnabled = computed(() => !!filter.value)
+const { data } = useQuery({
+  queryKey: ['todos', filter],
+  // ⬇️ disabled as long as the filter is undefined or empty
+  queryFn: filter ? () => fetchTodos(filter) : skipToken,
+})
+</script>
+
+<template>
+  <span v-if="data">Filter was set and data is here!</span>
+</template>
+```
+
+[//]: # 'Example3'
diff --git a/examples/angular/basic/package.json b/examples/angular/basic/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.1.3",
     "@angular/platform-browser-dynamic": "^17.1.3",
     "@angular/router": "^17.1.3",
-    "@tanstack/angular-query-experimental": "^5.24.8",
+    "@tanstack/angular-query-experimental": "^5.25.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.3"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.1.3",
     "@angular/cli": "^17.1.3",
     "@angular/compiler-cli": "^17.1.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.24.8",
+    "@tanstack/angular-query-devtools-experimental": "^5.25.0",
     "typescript": "5.2.2"
   },
   "overrides": {

diff --git a/examples/angular/infinite-query-with-max-pages/package.json b/examples/angular/infinite-query-with-max-pages/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.1.3",
     "@angular/platform-browser-dynamic": "^17.1.3",
     "@angular/router": "^17.1.3",
-    "@tanstack/angular-query-experimental": "^5.24.8",
+    "@tanstack/angular-query-experimental": "^5.25.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.3"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.1.3",
     "@angular/cli": "^17.1.3",
     "@angular/compiler-cli": "^17.1.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.24.8",
+    "@tanstack/angular-query-devtools-experimental": "^5.25.0",
     "typescript": "5.2.2"
   },
   "overrides": {

diff --git a/examples/angular/router/package.json b/examples/angular/router/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.1.3",
     "@angular/platform-browser-dynamic": "^17.1.3",
     "@angular/router": "^17.1.3",
-    "@tanstack/angular-query-experimental": "^5.24.8",
+    "@tanstack/angular-query-experimental": "^5.25.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.3"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.1.3",
     "@angular/cli": "^17.1.3",
     "@angular/compiler-cli": "^17.1.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.24.8",
+    "@tanstack/angular-query-devtools-experimental": "^5.25.0",
     "typescript": "5.2.2"
   },
   "overrides": {

diff --git a/examples/angular/simple/package.json b/examples/angular/simple/package.json
@@ -17,7 +17,7 @@
     "@angular/platform-browser": "^17.1.3",
     "@angular/platform-browser-dynamic": "^17.1.3",
     "@angular/router": "^17.1.3",
-    "@tanstack/angular-query-experimental": "^5.24.8",
+    "@tanstack/angular-query-experimental": "^5.25.0",
     "rxjs": "^7.8.1",
     "tslib": "^2.6.2",
     "zone.js": "^0.14.3"
@@ -26,7 +26,7 @@
     "@angular-devkit/build-angular": "^17.1.3",
     "@angular/cli": "^17.1.3",
     "@angular/compiler-cli": "^17.1.3",
-    "@tanstack/angular-query-devtools-experimental": "^5.24.8",
+    "@tanstack/angular-query-devtools-experimental": "^5.25.0",
     "typescript": "5.2.2"
   },
   "overrides": {

diff --git a/examples/react/algolia/package.json b/examples/react/algolia/package.json
@@ -11,8 +11,8 @@
   "dependencies": {
     "@algolia/client-search": "4.22.1",
     "@algolia/transporter": "4.22.1",
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "algoliasearch": "4.22.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

diff --git a/examples/react/algolia/src/SearchResults.tsx b/examples/react/algolia/src/SearchResults.tsx
@@ -25,7 +25,6 @@ export default function SearchResults({ query = '' }: SearchResultsProps) {
     hitsPerPage: 5,
     staleTime: 1000 * 30, // 30s
     gcTime: 1000 * 60 * 15, // 15m
-    enabled: !!query,
   })
 
   if (!query) return null

diff --git a/examples/react/algolia/src/useAlgolia.ts b/examples/react/algolia/src/useAlgolia.ts
@@ -1,4 +1,4 @@
-import { useInfiniteQuery } from '@tanstack/react-query'
+import { useInfiniteQuery, skipToken } from '@tanstack/react-query'
 import { search } from './algolia'
 
 export type UseAlgoliaOptions = {
@@ -7,7 +7,6 @@ export type UseAlgoliaOptions = {
   hitsPerPage?: number
   staleTime?: number
   gcTime?: number
-  enabled?: boolean
 }
 
 export default function useAlgolia<TData>({
@@ -16,17 +15,17 @@ export default function useAlgolia<TData>({
   hitsPerPage = 10,
   staleTime,
   gcTime,
-  enabled,
 }: UseAlgoliaOptions) {
   const queryInfo = useInfiniteQuery({
     queryKey: ['algolia', indexName, query, hitsPerPage],
-    queryFn: ({ pageParam }) =>
-      search<TData>({ indexName, query, pageParam, hitsPerPage }),
+    queryFn: query
+      ? ({ pageParam }) =>
+          search<TData>({ indexName, query, pageParam, hitsPerPage })
+      : skipToken,
     initialPageParam: 0,
     getNextPageParam: (lastPage) => lastPage?.nextPage,
     staleTime,
     gcTime,
-    enabled,
   })
 
   const hits = queryInfo.data?.pages.map((page) => page.hits).flat()

diff --git a/examples/react/auto-refetching/package.json b/examples/react/auto-refetching/package.json
@@ -7,8 +7,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "isomorphic-unfetch": "4.0.2",
     "next": "^14.0.0",

diff --git a/examples/react/basic-graphql-request/package.json b/examples/react/basic-graphql-request/package.json
@@ -8,8 +8,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "graphql": "^16.8.1",
     "graphql-request": "^6.1.0",
     "react": "^18.2.0",

diff --git a/examples/react/basic-typescript/package.json b/examples/react/basic-typescript/package.json
@@ -9,10 +9,10 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@tanstack/query-sync-storage-persister": "^5.24.8",
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
-    "@tanstack/react-query-persist-client": "^5.24.8",
+    "@tanstack/query-sync-storage-persister": "^5.25.0",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
+    "@tanstack/react-query-persist-client": "^5.25.0",
     "axios": "^1.6.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

diff --git a/examples/react/basic-typescript/src/index.tsx b/examples/react/basic-typescript/src/index.tsx
@@ -2,7 +2,12 @@
 import * as React from 'react'
 import ReactDOM from 'react-dom/client'
 import axios from 'axios'
-import { useQuery, useQueryClient, QueryClient } from '@tanstack/react-query'
+import {
+  QueryClient,
+  skipToken,
+  useQuery,
+  useQueryClient,
+} from '@tanstack/react-query'
 import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
 import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
@@ -95,8 +100,7 @@ const getPostById = async (id: number): Promise<Post> => {
 function usePost(postId: number) {
   return useQuery({
     queryKey: ['post', postId],
-    queryFn: () => getPostById(postId),
-    enabled: !!postId,
+    queryFn: postId ? () => getPostById(postId) : skipToken,
   })
 }
 

diff --git a/examples/react/basic/package.json b/examples/react/basic/package.json
@@ -8,8 +8,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

diff --git a/examples/react/default-query-function/package.json b/examples/react/default-query-function/package.json
@@ -8,8 +8,8 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"

diff --git a/examples/react/infinite-query-with-max-pages/package.json b/examples/react/infinite-query-with-max-pages/package.json
@@ -7,8 +7,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "isomorphic-unfetch": "4.0.2",
     "next": "^14.0.0",

diff --git a/examples/react/load-more-infinite-scroll/package.json b/examples/react/load-more-infinite-scroll/package.json
@@ -7,8 +7,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "isomorphic-unfetch": "4.0.2",
     "next": "^14.0.0",

diff --git a/examples/react/nextjs-suspense-streaming/package.json b/examples/react/nextjs-suspense-streaming/package.json
@@ -8,9 +8,9 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
-    "@tanstack/react-query-next-experimental": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
+    "@tanstack/react-query-next-experimental": "^5.25.0",
     "next": "^14.0.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

diff --git a/examples/react/nextjs/package.json b/examples/react/nextjs/package.json
@@ -7,8 +7,8 @@
     "start": "next start"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "ky": "^1.2.0",
     "next": "^14.0.0",
     "react": "^18.2.0",

diff --git a/examples/react/offline/package.json b/examples/react/offline/package.json
@@ -8,11 +8,11 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@tanstack/query-sync-storage-persister": "^5.24.8",
+    "@tanstack/query-sync-storage-persister": "^5.25.0",
     "@tanstack/react-location": "^3.7.4",
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
-    "@tanstack/react-query-persist-client": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
+    "@tanstack/react-query-persist-client": "^5.25.0",
     "ky": "^1.2.0",
     "msw": "^2.1.7",
     "react": "^18.2.0",

diff --git a/examples/react/optimistic-updates-cache/package.json b/examples/react/optimistic-updates-cache/package.json
@@ -8,8 +8,8 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@tanstack/react-query": "^5.24.8",
-    "@tanstack/react-query-devtools": "^5.24.8",
+    "@tanstack/react-query": "^5.25.0",
+    "@tanstack/react-query-devtools": "^5.25.0",
     "axios": "^1.6.7",
     "isomorphic-unfetch": "4.0.2",
     "next": "^14.0.0",