Merge branch 'master' of https://github.com/tannerlinsley/react-query

Author: tannerlinsley

docs/src/pages/docs/api.md

@@ -24,7 +24,6 @@ const {
 } = useQuery(queryKey, queryFn?, {
   cacheTime,
   enabled,
-  forceFetchOnMount,
   initialData,
   initialStale,
   isDataEqual,
@@ -142,10 +141,6 @@ const queryInfo = useQuery({
   - Optional
   - Defaults to `false`
   - If set, any previous `data` will be kept when fetching new data because the query key changed.
-- `forceFetchOnMount: Boolean`
-  - Optional
-  - Defaults to `false`
-  - Set this to `true` to always fetch when the component mounts (regardless of staleness).
 - `queryFnParamsFilter: Function(args) => filteredArgs`
   - Optional
   - This function will filter the params that get passed to `queryFn`.
@@ -362,9 +357,11 @@ const queryCache = new QueryCache({
 
 Its available properties and methods are:
 
+- [`fetchQuery`](#querycachefetchquery)
 - [`prefetchQuery`](#querycacheprefetchquery)
 - [`getQueryData`](#querycachegetquerydata)
 - [`setQueryData`](#querycachesetquerydata)
+- [`refetchQueries`](#querycacherefetchqueries)
 - [`invalidateQueries`](#querycacheinvalidatequeries)
 - [`cancelQueries`](#querycachecancelqueries)
 - [`removeQueries`](#querycacheremovequeries)
@@ -380,9 +377,25 @@ Its available properties and methods are:
   - Optional
   - Define defaults for all queries and mutations using this query cache.
 
+## `queryCache.fetchQuery`
+
+`fetchQuery` is an asynchronous method that can be used to fetch and cache a query. It will either resolve with the data or throw with the error. Specify a `staleTime` to only trigger a fetch when the data is stale. Use the `prefetchQuery` method if you just want to fetch a query without needing the result.
+
+```js
+try {
+  const data = await queryCache.fetchQuery(queryKey, queryFn)
+} catch (error) {
+  console.log(error)
+}
+```
+
+**Returns**
+
+- `Promise<TResult>`
+
 ## `queryCache.prefetchQuery`
 
-`prefetchQuery` is an asynchronous function that can be used to fetch and cache a query response before it is needed or rendered with `useQuery` and friends.
+`prefetchQuery` is an asynchronous method that can be used to fetch and cache a query response before it is needed or rendered with `useQuery` and friends.
 
 - If either:
   - The query does not exist or
@@ -394,13 +407,13 @@ Its available properties and methods are:
 > The difference between using `prefetchQuery` and `setQueryData` is that `prefetchQuery` is async and will ensure that duplicate requests for this query are not created with `useQuery` instances for the same query are rendered while the data is fetching.
 
 ```js
-const data = await queryCache.prefetchQuery(queryKey, queryFn)
+await queryCache.prefetchQuery(queryKey, queryFn)
 ```
 
 To pass options like `force` or `throwOnError`, use the fourth options object:
 
 ```js
-const data = await queryCache.prefetchQuery(queryKey, queryFn, config, {
+await queryCache.prefetchQuery(queryKey, queryFn, config, {
   force: true,
   throwOnError: true,
 })
@@ -409,7 +422,7 @@ const data = await queryCache.prefetchQuery(queryKey, queryFn, config, {
 You can even use it with a default queryFn in your config!
 
 ```js
-const data = await queryCache.prefetchQuery(queryKey)
+await queryCache.prefetchQuery(queryKey)
 ```
 
 **Options**
@@ -423,7 +436,7 @@ The options for `prefetchQuery` are exactly the same as those of [`useQuery`](#u
 
 **Returns**
 
-- `promise: Promise`
+- `Promise<TResult | undefined>`
   - A promise is returned that will either immediately resolve with the query's cached response data, or resolve to the data returned by the fetch function. It **will not** throw an error if the fetch fails. This can be configured by setting the `throwOnError` option to `true`.
 
 ## `queryCache.getQueryData`
@@ -478,6 +491,52 @@ For convenience in syntax, you can also pass an updater function which receives
 setQueryData(queryKey, oldData => newData)
 ```
 
+## `queryCache.refetchQueries`
+
+The `refetchQueries` method can be used to refetch queries based on certain conditions.
+
+Examples:
+
+```js
+// refetch all queries:
+await queryCache.refetchQueries()
+
+// refetch all stale queries:
+await queryCache.refetchQueries([], { stale: true })
+
+// refetch all stale and active queries:
+await queryCache.refetchQueries([], { stale: true, active: true })
+
+// refetch all queries partially matching a query key:
+await queryCache.refetchQueries(['posts'])
+
+// refetch all queries exactly matching a query key:
+await queryCache.refetchQueries(['posts', 1], { exact: true })
+```
+
+**Options**
+
+- `queryKeyOrPredicateFn` can either be a [Query Key](#query-keys) or a `Function`
+  - `queryKey: QueryKey`
+    - If a query key is passed, queries will be filtered to those where this query key is included in the existing query's query key. This means that if you passed a query key of `'todos'`, it would match queries with the `todos`, `['todos']`, and `['todos', 5]`. See [Query Keys](./guides/queries#query-keys) for more information.
+  - `query => boolean`
+    - This predicate function will be called for every single query in the cache and be expected to return truthy for queries that are `found`.
+    - The `exact` option has no effect when using a function
+- `exact?: boolean`
+  - If you don't want to search queries inclusively by query key, you can pass the `exact: true` option to return only the query with the exact query key you have passed. Remember to destructure it out of the array!
+- `active?: boolean`
+  - When set to `true` it will refetch active queries.
+  - When set to `false` it will refetch inactive queries.
+- `stale?: boolean`
+  - When set to `true` it will match on stale queries.
+  - When set to `false` it will match on fresh queries.
+- `throwOnError?: boolean`
+  - When set to `true`, this method will throw if any of the query refetch tasks fail.
+
+**Returns**
+
+This function returns a promise that will resolve when all of the queries are done being refetched. By default, it **will not** throw an error if any of those queries refetches fail, but this can be configured by setting the `throwOnError` option to `true`
+
 ## `queryCache.invalidateQueries`
 
 The `invalidateQueries` method can be used to invalidate and refetch single or multiple queries in the cache based on their query keys or any other functionally accessible property/state of the query. By default, all matching queries are immediately marked as stale and active queries are refetched in the background.
@@ -549,7 +608,7 @@ This function does not return anything
 The `removeQueries` method can be used to remove queries from the cache based on their query keys or any other functionally accessible property/state of the query.
 
 ```js
-const queries = queryCache.removeQueries(queryKeyOrPredicateFn, {
+queryCache.removeQueries(queryKeyOrPredicateFn, {
   exact,
 })
 ```

docs/src/pages/docs/comparison.md

@@ -12,7 +12,7 @@ Feature/Capability Key:
 - 🔶 Supported and documented, but requires extra user-code to implement
 - 🛑 Not officially supported or documented.
 
-|                                              | React Query                            | SWR [_(Website)_](swr)     | Apollo Client [_(Website)_](apollo)   |
+|                                              | React Query                            | SWR [_(Website)_][swr]     | Apollo Client [_(Website)_][apollo]   |
 | -------------------------------------------- | -------------------------------------- | -------------------------- | ------------------------------------- |
 | Supported Query Syntax                       | Promise, REST, GraphQL                 | Promise, REST, GraphQL     | GraphQL                               |
 | Supported Query Keys                         | JSON                                   | JSON                       | GraphQL Query                         |

docs/src/pages/docs/guides/prefetching.md

@@ -3,13 +3,11 @@ id: prefetching
 title: Prefetching
 ---
 
-If you're lucky enough, you may know enough about what your users will do to be able to prefetch the data they need before it's needed! If this is the case, you can use the `prefetchQuery` function to prefetch the results of a query to be placed into the cache:
+If you're lucky enough, you may know enough about what your users will do to be able to prefetch the data they need before it's needed! If this is the case, you can use the `fetchQuery` or `prefetchQuery` methods to prefetch the results of a query to be placed into the cache:
 
 ```js
 const prefetchTodos = async () => {
-  const queryData = await queryCache.prefetchQuery('todos', () =>
-    fetch('/todos')
-  )
+  await queryCache.prefetchQuery('todos', () => fetch('/todos'))
   // The results of this query will be cached like a normal query
 }
 ```

docs/src/pages/docs/guides/ssr.md

@@ -118,12 +118,12 @@ Since there are many different possible setups for SSR, it's hard to give a deta
 > Note: The global `queryCache` you can import directly from 'react-query' does not cache queries on the server to avoid leaking sensitive information between requests.
 
 - Prefetch data
-  - Create a `prefetchQueryCache` specifically for prefetching by calling `const prefetchQueryCache = new QueryCache()`
-  - Call `prefetchQueryCache.prefetchQuery(...)` to prefetch queries
-  - Dehydrate by using `const dehydratedState = dehydrate(prefetchQueryCache)`
+  - Create a `prefetchCache` specifically for prefetching by calling `const prefetchCache = new QueryCache()`
+  - Call `prefetchCache.prefetchQuery(...)` to prefetch queries
+  - Dehydrate by using `const dehydratedState = dehydrate(prefetchCache)`
 - Render
-  - Create a new render query cache and hydrate the state. Use this query cache to render your app.
-    - **Do not** use the `prefetchQueryCache` to render your app, the server and client both needs to render from the dehydrated data to avoid React hydration mismatches. This is because queries with errors are excluded from dehydration by default.
+  - Create a new query cache for rendering and hydrate the state. Use this query cache to render your app.
+    - **Do not** use the `prefetchCache` to render your app, the server and client both needs to render from the dehydrated data to avoid React hydration mismatches. This is because queries with errors are excluded from dehydration by default.
 - Serialize and embed `dehydratedState` in the markup
   - Security note: Serializing data with `JSON.stringify` can put you at risk for XSS-vulnerabilities, [this blog post explains why and how to solve it](https://medium.com/node-security/the-most-common-xss-vulnerability-in-react-js-applications-2bdffbcc1fa0)
 
@@ -180,7 +180,7 @@ ReactDOM.hydrate(
 
 Any query with an error is automatically excluded from dehydration. This means that the default behaviour is to pretend these queries were never loaded on the server, usually showing a loading state instead, and retrying the queries on the client. This happens regardless of error.
 
-Sometimes this behavior is not desirable, maybe you want to render an error page with a correct status code instead on certain errors or queries. In those cases, pass `throwOnError: true` to the specific `prefetchQuery` to be able to catch and handle those errors manually.
+Sometimes this behavior is not desirable, maybe you want to render an error page with a correct status code instead on certain errors or queries. In those cases, use `fetchQuery` and catch any errors to handle those manually.
 
 **Staleness is measured from when the query was fetched on the server**
 

src/core/query.ts

@@ -110,7 +110,7 @@ export class Query<TResult, TError> {
   cacheTime: number
 
   private queryCache: QueryCache
-  private promise?: Promise<TResult | undefined>
+  private promise?: Promise<TResult>
   private gcTimeout?: number
   private cancelFetch?: (silent?: boolean) => void
   private continueFetch?: () => void
@@ -160,12 +160,15 @@ export class Query<TResult, TError> {
     }, this.cacheTime)
   }
 
-  async cancel(silent?: boolean): Promise<void> {
+  cancel(silent?: boolean): Promise<undefined> {
     const promise = this.promise
+
     if (promise && this.cancelFetch) {
       this.cancelFetch(silent)
-      await promise.catch(noop)
+      return promise.then(noop).catch(noop)
     }
+
+    return Promise.resolve(undefined)
   }
 
   private continue(): void {
@@ -316,17 +319,17 @@ export class Query<TResult, TError> {
     }
   }
 
-  async refetch(
+  refetch(
     options?: RefetchOptions,
     config?: ResolvedQueryConfig<TResult, TError>
   ): Promise<TResult | undefined> {
-    try {
-      return await this.fetch(undefined, config)
-    } catch (error) {
-      if (options?.throwOnError === true) {
-        throw error
-      }
+    let promise: Promise<TResult | undefined> = this.fetch(undefined, config)
+
+    if (!options?.throwOnError) {
+      promise = promise.catch(noop)
     }
+
+    return promise
   }
 
   fetchMore(
@@ -348,7 +351,7 @@ export class Query<TResult, TError> {
   async fetch(
     options?: FetchOptions,
     config?: ResolvedQueryConfig<TResult, TError>
-  ): Promise<TResult | undefined> {
+  ): Promise<TResult> {
     if (this.promise) {
       if (options?.fetchMore && this.state.data) {
         // Silently cancel current fetch if the user wants to fetch more