Merge remote-tracking branch 'react-query/alpha' into feature/persistQueryClient

Author: TkDodo

docs/src/pages/guides/migrating-to-react-query-4.md

@@ -217,18 +217,9 @@ The `useQueries` hook now accepts an object with a `queries` prop as its input.
 ```
 
 
-### Removed undocumented methods from the `queryClient` and `query`
+### Removed undocumented methods from the `queryClient`, `query` and `mutation`
 
-The methods `cancelMutatations` and `executeMutation` on the `QueryClient` were undocumented and unused internally, so we removed them. Since they were just wrappers around methods available on the `mutationCache`, you can still use the functionality.
-
-```diff
-- cancelMutations(): Promise<void> {
--   const promises = notifyManager.batch(() =>
--     this.mutationCache.getAll().map(mutation => mutation.cancel())
--   )
--   return Promise.all(promises).then(noop).catch(noop)
-- }
-```
+The methods `cancelMutatations` and `executeMutation` on the `QueryClient` were undocumented and unused internally, so we removed them. Since it was just a wrapper around a method available on the `mutationCache`, you can still use the functionality of `executeMutation`
 
 ```diff
 - executeMutation<
@@ -243,7 +234,7 @@ The methods `cancelMutatations` and `executeMutation` on the `QueryClient` were
 - }
 ```
 
-Additionally, `query.setDefaultOptions` was removed because it was also unused.
+Additionally, `query.setDefaultOptions` was removed because it was also unused. `mutation.cancel` was removed because it didn't actually cancel the outgoing request.
 
 ### TypeScript
 

docs/src/pages/guides/query-cancellation.md

@@ -99,6 +99,18 @@ const query = useQuery(['todos'], ({ signal }) => {
 
 ## Using `graphql-request`
 
+An `AbortSignal` can be set in the client `request` method.
+
+```js
+const client = new GraphQLClient(endpoint)
+
+const query = useQuery('todos', ({ signal }) => {
+  client.request({ document: query, signal })
+})
+```
+
+## Using `graphql-request`  version less than v4.0.0
+
 An `AbortSignal` can be set in the `GraphQLClient` constructor.
 
 ```js

docs/src/pages/reference/QueryClient.md

@@ -203,7 +203,7 @@ This distinction is more a "convenience" for ts devs that know which structure w
 
 ## `queryClient.setQueryData`
 
-`setQueryData` is a synchronous function that can be used to immediately update a query's cached data. If the query does not exist, it will be created. **If the query is not utilized by a query hook in the default `cacheTime` of 5 minutes, the query will be garbage collected**.
+`setQueryData` is a synchronous function that can be used to immediately update a query's cached data. If the query does not exist, it will be created. **If the query is not utilized by a query hook in the default `cacheTime` of 5 minutes, the query will be garbage collected**. To update multiple queries at once and match query keys partially, you need to use [`queryClient.setQueriesData`](#queryclientsetqueriesdata) instead. 
 
 > The difference between using `setQueryData` and `fetchQuery` is that `setQueryData` is sync and assumes that you already synchronously have the data available. If you need to fetch the data asynchronously, it's suggested that you either refetch the query key or use `fetchQuery` to handle the asynchronous fetch.
 
@@ -248,7 +248,7 @@ console.log(state.dataUpdatedAt)
 
 ## `queryClient.setQueriesData`
 
-`setQueriesData` is a synchronous function that can be used to immediately update cached data of multiple queries. Only queries that match the passed queryKey or queryFilter will be updated - no new cache entries will be created. Under the hood, [`setQueryData`](#queryclientsetquerydata) is called for each query.
+`setQueriesData` is a synchronous function that can be used to immediately update cached data of multiple queries by using filter function or partially matching the query key. Only queries that match the passed queryKey or queryFilter will be updated - no new cache entries will be created. Under the hood, [`setQueryData`](#queryclientsetquerydata) is called for each query.
 
 ```js
 queryClient.setQueriesData(queryKey | filters, updater)
@@ -257,7 +257,7 @@ queryClient.setQueriesData(queryKey | filters, updater)
 **Options**
 
 - `queryKey: QueryKey`: [Query Keys](../guides/query-keys) | `filters: QueryFilters`: [Query Filters](../guides/filters#query-filters)
-  - if a queryKey is passed as first argument, queryKeys fuzzily matching this param will be updated
+  - if a queryKey is passed as first argument, queryKeys partially matching this param will be updated
   - if a filter is passed, queryKeys matching the filter will be updated
 - `updater: TData | (oldData: TData | undefined) => TData`
   - the [setQueryData](#queryclientsetquerydata) updater function or new data, will be called for each matching queryKey
@@ -474,6 +474,9 @@ The `getQueryDefaults` method returns the default options which have been set fo
 const defaultOptions = queryClient.getQueryDefaults(['posts'])
 ```
 
+> Note that if several query defaults match the given query key, the **first** matching one is returned.
+> This could lead to unexpected behaviours. See [`setQueryDefaults`](#queryclientsetquerydefaults).
+
 ## `queryClient.setQueryDefaults`
 
 `setQueryDefaults` can be used to set default options for specific queries:
@@ -491,6 +494,9 @@ function Component() {
 - `queryKey: QueryKey`: [Query Keys](../guides/query-keys)
 - `options: QueryOptions`
 
+> As stated in [`getQueryDefaults`](#queryclientgetquerydefaults), the order of registration of query defaults does matter.
+> Since the **first** matching defaults are returned by `getQueryDefaults`, the registration should be made in the following order: from the **least generic key** to the **most generic one**. This way, in case of specific key, the first matching one would be the expected one.
+
 ## `queryClient.getMutationDefaults`
 
 The `getMutationDefaults` method returns the default options which have been set for specific mutations:
@@ -516,6 +522,8 @@ function Component() {
 - `mutationKey: string | unknown[]`
 - `options: MutationOptions`
 
+> Similar to [`setQueryDefaults`](#queryclientsetquerydefaults), the order of registration does matter here.
+
 ## `queryClient.getQueryCache`
 
 The `getQueryCache` method returns the query cache this client is connected to.

examples/load-more-infinite-scroll/pages/index.js

@@ -48,7 +48,7 @@ function Example() {
   useIntersectionObserver({
     target: loadMoreButtonRef,
     onIntersect: fetchNextPage,
-    enabled: hasNextPage,
+    enabled: !!hasNextPage,
   })
 
   return (

src/core/mutation.ts

@@ -5,7 +5,6 @@ import { getLogger } from './logger'
 import { notifyManager } from './notifyManager'
 import { Removable } from './removable'
 import { canFetch, Retryer, createRetryer } from './retryer'
-import { noop } from './utils'
 
 // TYPES
 
@@ -150,14 +149,6 @@ export class Mutation<
     }
   }
 
-  cancel(): Promise<void> {
-    if (this.retryer) {
-      this.retryer.cancel()
-      return this.retryer.promise.then(noop).catch(noop)
-    }
-    return Promise.resolve()
-  }
-
   continue(): Promise<TData> {
     if (this.retryer) {
       this.retryer.continue()

src/core/mutationCache.ts

@@ -106,7 +106,6 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
 
   remove(mutation: Mutation<any, any, any, any>): void {
     this.mutations = this.mutations.filter(x => x !== mutation)
-    mutation.cancel()
     this.notify({ type: 'removed', mutation })
   }
 

src/core/queryClient.ts

@@ -38,6 +38,7 @@ import { onlineManager } from './onlineManager'
 import { notifyManager } from './notifyManager'
 import { infiniteQueryBehavior } from './infiniteQueryBehavior'
 import { CancelOptions, DefaultedQueryObserverOptions } from './types'
+import { getLogger } from './logger'
 
 // TYPES
 
@@ -535,10 +536,32 @@ export class QueryClient {
   getQueryDefaults(
     queryKey?: QueryKey
   ): QueryObserverOptions<any, any, any, any, any> | undefined {
-    return queryKey
-      ? this.queryDefaults.find(x => partialMatchKey(queryKey, x.queryKey))
-          ?.defaultOptions
-      : undefined
+    if (!queryKey) {
+      return undefined
+    }
+
+    // Get the first matching defaults
+    const firstMatchingDefaults = this.queryDefaults.find(x =>
+      partialMatchKey(queryKey, x.queryKey)
+    )
+
+    // Additional checks and error in dev mode
+    if (process.env.NODE_ENV !== 'production') {
+      // Retrieve all matching defaults for the given key
+      const matchingDefaults = this.queryDefaults.filter(x =>
+        partialMatchKey(queryKey, x.queryKey)
+      )
+      // It is ok not having defaults, but it is error prone to have more than 1 default for a given key
+      if (matchingDefaults.length > 1) {
+        getLogger().error(
+          `[QueryClient] Several query defaults match with key '${JSON.stringify(
+            queryKey
+          )}'. The first matching query defaults are used. Please check how query defaults are registered. Order does matter here. cf. https://react-query.tanstack.com/reference/QueryClient#queryclientsetquerydefaults.`
+        )
+      }
+    }
+
+    return firstMatchingDefaults?.defaultOptions
   }
 
   setMutationDefaults(
@@ -558,11 +581,32 @@ export class QueryClient {
   getMutationDefaults(
     mutationKey?: MutationKey
   ): MutationObserverOptions<any, any, any, any> | undefined {
-    return mutationKey
-      ? this.mutationDefaults.find(x =>
-          partialMatchKey(mutationKey, x.mutationKey)
-        )?.defaultOptions
-      : undefined
+    if (!mutationKey) {
+      return undefined
+    }
+
+    // Get the first matching defaults
+    const firstMatchingDefaults = this.mutationDefaults.find(x =>
+      partialMatchKey(mutationKey, x.mutationKey)
+    )
+
+    // Additional checks and error in dev mode
+    if (process.env.NODE_ENV !== 'production') {
+      // Retrieve all matching defaults for the given key
+      const matchingDefaults = this.mutationDefaults.filter(x =>
+        partialMatchKey(mutationKey, x.mutationKey)
+      )
+      // It is ok not having defaults, but it is error prone to have more than 1 default for a given key
+      if (matchingDefaults.length > 1) {
+        getLogger().error(
+          `[QueryClient] Several mutation defaults match with key '${JSON.stringify(
+            mutationKey
+          )}'. The first matching mutation defaults are used. Please check how mutation defaults are registered. Order does matter here. cf. https://react-query.tanstack.com/reference/QueryClient#queryclientsetmutationdefaults.`
+        )
+      }
+    }
+
+    return firstMatchingDefaults?.defaultOptions
   }
 
   defaultQueryOptions<

src/core/tests/mutations.test.tsx

@@ -369,33 +369,6 @@ describe('mutations', () => {
     consoleMock.mockRestore()
   })
 
-  test('cancel mutation should not call mutationFn if the current retrier is undefined', async () => {
-    const mutationFn = jest.fn().mockImplementation(async () => {
-      await sleep(20)
-      return 'data'
-    })
-
-    const observer = new MutationObserver(queryClient, {
-      mutationKey: ['key'],
-      mutationFn,
-    })
-
-    observer.mutate()
-    const mutation = queryClient
-      .getMutationCache()
-      .find({ mutationKey: ['key'] })!
-    await sleep(10)
-
-    // Force current mutation retryer to be undefined
-    // because not use case has been found
-    mutation['retryer'] = undefined
-    mutationFn.mockReset()
-    await mutation.cancel()
-
-    await sleep(30)
-    expect(mutationFn).toHaveBeenCalledTimes(0)
-  })
-
   test('reducer should return the state for an unknown action type', async () => {
     const observer = new MutationObserver(queryClient, {
       mutationKey: ['key'],

src/core/tests/queryClient.test.tsx

@@ -130,6 +130,132 @@ describe('queryClient', () => {
       queryClient.setQueryDefaults(key, queryOptions2)
       expect(queryClient.getQueryDefaults(key)).toMatchObject(queryOptions2)
     })
+
+    test('should warn in dev if several query defaults match a given key', () => {
+      // Check discussion here: https://github.com/tannerlinsley/react-query/discussions/3199
+      const consoleErrorMock = jest.spyOn(console, 'error')
+      consoleErrorMock.mockImplementation(() => true)
+
+      const keyABCD = [
+        {
+          a: 'a',
+          b: 'b',
+          c: 'c',
+          d: 'd',
+        },
+      ]
+
+      // The key below "contains" keyABCD => it is more generic
+      const keyABC = [
+        {
+          a: 'a',
+          b: 'b',
+          c: 'c',
+        },
+      ]
+
+      // The defaults for query matching key "ABCD" (least generic)
+      const defaultsOfABCD = {
+        queryFn: function ABCDQueryFn() {
+          return 'ABCD'
+        },
+      }
+
+      // The defaults for query matching key "ABC" (most generic)
+      const defaultsOfABC = {
+        queryFn: function ABCQueryFn() {
+          return 'ABC'
+        },
+      }
+
+      // No defaults, no warning
+      const noDefaults = queryClient.getQueryDefaults(keyABCD)
+      expect(noDefaults).toBeUndefined()
+      expect(consoleErrorMock).not.toHaveBeenCalled()
+
+      // If defaults for key ABCD are registered **before** the ones of key ABC (more generic)…
+      queryClient.setQueryDefaults(keyABCD, defaultsOfABCD)
+      queryClient.setQueryDefaults(keyABC, defaultsOfABC)
+      // … then the "good" defaults are retrieved: we get the ones for key "ABCD"
+      const goodDefaults = queryClient.getQueryDefaults(keyABCD)
+      expect(goodDefaults).toBe(defaultsOfABCD)
+      // The warning is still raised since several defaults are matching
+      expect(consoleErrorMock).toHaveBeenCalledTimes(1)
+
+      // Let's create another queryClient and change the order of registration
+      const newQueryClient = new QueryClient()
+      // The defaults for key ABC (more generic) are registered **before** the ones of key ABCD…
+      newQueryClient.setQueryDefaults(keyABC, defaultsOfABC)
+      newQueryClient.setQueryDefaults(keyABCD, defaultsOfABCD)
+      // … then the "wrong" defaults are retrieved: we get the ones for key "ABC"
+      const badDefaults = newQueryClient.getQueryDefaults(keyABCD)
+      expect(badDefaults).not.toBe(defaultsOfABCD)
+      expect(badDefaults).toBe(defaultsOfABC)
+      expect(consoleErrorMock).toHaveBeenCalledTimes(2)
+
+      consoleErrorMock.mockRestore()
+    })
+
+    test('should warn in dev if several mutation defaults match a given key', () => {
+      // Check discussion here: https://github.com/tannerlinsley/react-query/discussions/3199
+      const consoleErrorMock = jest.spyOn(console, 'error')
+      consoleErrorMock.mockImplementation(() => true)
+
+      const keyABCD = [
+        {
+          a: 'a',
+          b: 'b',
+          c: 'c',
+          d: 'd',
+        },
+      ]
+
+      // The key below "contains" keyABCD => it is more generic
+      const keyABC = [
+        {
+          a: 'a',
+          b: 'b',
+          c: 'c',
+        },
+      ]
+
+      // The defaults for mutation matching key "ABCD" (least generic)
+      const defaultsOfABCD = {
+        mutationFn: Promise.resolve,
+      }
+
+      // The defaults for mutation matching key "ABC" (most generic)
+      const defaultsOfABC = {
+        mutationFn: Promise.resolve,
+      }
+
+      // No defaults, no warning
+      const noDefaults = queryClient.getMutationDefaults(keyABCD)
+      expect(noDefaults).toBeUndefined()
+      expect(consoleErrorMock).not.toHaveBeenCalled()
+
+      // If defaults for key ABCD are registered **before** the ones of key ABC (more generic)…
+      queryClient.setMutationDefaults(keyABCD, defaultsOfABCD)
+      queryClient.setMutationDefaults(keyABC, defaultsOfABC)
+      // … then the "good" defaults are retrieved: we get the ones for key "ABCD"
+      const goodDefaults = queryClient.getMutationDefaults(keyABCD)
+      expect(goodDefaults).toBe(defaultsOfABCD)
+      // The warning is still raised since several defaults are matching
+      expect(consoleErrorMock).toHaveBeenCalledTimes(1)
+
+      // Let's create another queryClient and change the order of registration
+      const newQueryClient = new QueryClient()
+      // The defaults for key ABC (more generic) are registered **before** the ones of key ABCD…
+      newQueryClient.setMutationDefaults(keyABC, defaultsOfABC)
+      newQueryClient.setMutationDefaults(keyABCD, defaultsOfABCD)
+      // … then the "wrong" defaults are retrieved: we get the ones for key "ABC"
+      const badDefaults = newQueryClient.getMutationDefaults(keyABCD)
+      expect(badDefaults).not.toBe(defaultsOfABCD)
+      expect(badDefaults).toBe(defaultsOfABC)
+      expect(consoleErrorMock).toHaveBeenCalledTimes(2)
+
+      consoleErrorMock.mockRestore()
+    })
   })
 
   describe('setQueryData', () => {

src/reactjs/index.ts

@@ -25,3 +25,4 @@ export * from './types'
 export type { QueryClientProviderProps } from './QueryClientProvider'
 export type { QueryErrorResetBoundaryProps } from './QueryErrorResetBoundary'
 export type { HydrateProps } from './Hydrate'
+export type { QueriesOptions, QueriesResults } from './useQueries'