Merge branch 'v4' into feat/make-persist-query-client-stable

TanStack · Nov 18, 2021 · ded3f9d · ded3f9d
2 parents 8453bd4 + ac1eefd
commit ded3f9d
Show file tree

Hide file tree

Showing 69 changed files with 545 additions and 134 deletions.
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -148,6 +148,24 @@
         "review"
       ]
     },
+    {
+      "login": "KATT",
+      "name": "Alex Johansson",
+      "avatar_url": "https://avatars.githubusercontent.com/u/459267?v=4",
+      "profile": "https://katt.dev",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "EddyVinck",
+      "name": "Eddy",
+      "avatar_url": "https://avatars.githubusercontent.com/u/23434753?v=4",
+      "profile": "http://www.eddyvinck.nl",
+      "contributions": [
+        "code"
+      ]
+    }
   ],
   "contributorsPerLine": 7,
   "skipCi": true

diff --git a/README.md b/README.md
@@ -58,26 +58,30 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
 <!-- markdownlint-disable -->
 <table>
   <tr>
-    <td align="center"><a href="https://tannerlinsley.com"><img src="https://avatars0.githubusercontent.com/u/5580297?v=4" width="100px;" alt=""/><br /><sub><b>Tanner Linsley</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tannerlinsley" title="Code">💻</a> <a href="#ideas-tannerlinsley" title="Ideas, Planning, & Feedback">🤔</a> <a href="#example-tannerlinsley" title="Examples">💡</a> <a href="#maintenance-tannerlinsley" title="Maintenance">🚧</a> <a href="https://github.com/tannerlinsley/react-query/pulls?q=is%3Apr+reviewed-by%3Atannerlinsley" title="Reviewed Pull Requests">👀</a></td>
-    <td align="center"><a href="http://cherniavskii.com"><img src="https://avatars2.githubusercontent.com/u/13808724?v=4" width="100px;" alt=""/><br /><sub><b>Andrew Cherniavskii</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=cherniavskii" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3Acherniavskii" title="Bug reports">🐛</a></td>
-    <td align="center"><a href="http://twitter.com/tibotiber"><img src="https://avatars3.githubusercontent.com/u/5635553?v=4" width="100px;" alt=""/><br /><sub><b>Thibaut Tiberghien</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tibotiber" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/gargroh"><img src="https://avatars3.githubusercontent.com/u/42495927?v=4" width="100px;" alt=""/><br /><sub><b>Rohit Garg</b></sub></a><br /><a href="#tool-gargroh" title="Tools">🔧</a></td>
-    <td align="center"><a href="https://github.com/Avi98"><img src="https://avatars1.githubusercontent.com/u/26133749?v=4" width="100px;" alt=""/><br /><sub><b>Avinash</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=Avi98" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3AAvi98" title="Bug reports">🐛</a></td>
-    <td align="center"><a href="https://github.com/CreativeTechGuy"><img src="https://avatars1.githubusercontent.com/u/12002072?v=4" width="100px;" alt=""/><br /><sub><b>Jason O'Neill</b></sub></a><br /><a href="#maintenance-CreativeTechGuy" title="Maintenance">🚧</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=CreativeTechGuy" title="Tests">⚠️</a></td>
-    <td align="center"><a href="http://fb.me/yz"><img src="https://avatars3.githubusercontent.com/u/14841421?v=4" width="100px;" alt=""/><br /><sub><b>Jack Zhao</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=bugzpodder" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3Abugzpodder" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="https://tannerlinsley.com"><img src="https://avatars0.githubusercontent.com/u/5580297?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Tanner Linsley</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tannerlinsley" title="Code">💻</a> <a href="#ideas-tannerlinsley" title="Ideas, Planning, & Feedback">🤔</a> <a href="#example-tannerlinsley" title="Examples">💡</a> <a href="#maintenance-tannerlinsley" title="Maintenance">🚧</a> <a href="https://github.com/tannerlinsley/react-query/pulls?q=is%3Apr+reviewed-by%3Atannerlinsley" title="Reviewed Pull Requests">👀</a></td>
+    <td align="center"><a href="http://cherniavskii.com"><img src="https://avatars2.githubusercontent.com/u/13808724?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Andrew Cherniavskii</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=cherniavskii" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3Acherniavskii" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="http://twitter.com/tibotiber"><img src="https://avatars3.githubusercontent.com/u/5635553?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Thibaut Tiberghien</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tibotiber" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/gargroh"><img src="https://avatars3.githubusercontent.com/u/42495927?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Rohit Garg</b></sub></a><br /><a href="#tool-gargroh" title="Tools">🔧</a></td>
+    <td align="center"><a href="https://github.com/Avi98"><img src="https://avatars1.githubusercontent.com/u/26133749?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Avinash</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=Avi98" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3AAvi98" title="Bug reports">🐛</a></td>
+    <td align="center"><a href="https://github.com/CreativeTechGuy"><img src="https://avatars1.githubusercontent.com/u/12002072?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jason O'Neill</b></sub></a><br /><a href="#maintenance-CreativeTechGuy" title="Maintenance">🚧</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=CreativeTechGuy" title="Tests">⚠️</a></td>
+    <td align="center"><a href="http://fb.me/yz"><img src="https://avatars3.githubusercontent.com/u/14841421?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jack Zhao</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=bugzpodder" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/issues?q=author%3Abugzpodder" title="Bug reports">🐛</a></td>
   </tr>
   <tr>
-    <td align="center"><a href="https://github.com/dpyzo0o"><img src="https://avatars1.githubusercontent.com/u/24768249?v=4" width="100px;" alt=""/><br /><sub><b>dpyzo0o</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=dpyzo0o" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/jelteliekens"><img src="https://avatars1.githubusercontent.com/u/3418474?v=4" width="100px;" alt=""/><br /><sub><b>Jelte Liekens</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=jelteliekens" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/jgettings"><img src="https://avatars0.githubusercontent.com/u/4183742?v=4" width="100px;" alt=""/><br /><sub><b>Jen Gettings</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=jgettings" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/justincy"><img src="https://avatars2.githubusercontent.com/u/1037458?v=4" width="100px;" alt=""/><br /><sub><b>Justin</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=justincy" title="Code">💻</a></td>
-    <td align="center"><a href="http://www.marceloalves.com"><img src="https://avatars1.githubusercontent.com/u/216782?v=4" width="100px;" alt=""/><br /><sub><b>Marcelo Alves</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=MarceloAlves" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/zorzysty"><img src="https://avatars0.githubusercontent.com/u/5398733?v=4" width="100px;" alt=""/><br /><sub><b>Zorza</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=zorzysty" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://tkdodo.eu"><img src="https://avatars0.githubusercontent.com/u/1021430?v=4" width="100px;" alt=""/><br /><sub><b>Dominik Dorfmeister</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Documentation">📖</a> <a href="#maintenance-tkdodo" title="Maintenance">🚧</a> <a href="#question-tkdodo" title="Question">💬</a> <a href="https://github.com/tannerlinsley/react-query/pulls?q=is%3Apr+reviewed-by%3Atkdodo" title="Reviewed Pull Requests">👀</a></td>
+    <td align="center"><a href="https://github.com/dpyzo0o"><img src="https://avatars1.githubusercontent.com/u/24768249?v=4?s=100" width="100px;" alt=""/><br /><sub><b>dpyzo0o</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=dpyzo0o" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/jelteliekens"><img src="https://avatars1.githubusercontent.com/u/3418474?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jelte Liekens</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=jelteliekens" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/jgettings"><img src="https://avatars0.githubusercontent.com/u/4183742?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Jen Gettings</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=jgettings" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/justincy"><img src="https://avatars2.githubusercontent.com/u/1037458?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Justin</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=justincy" title="Code">💻</a></td>
+    <td align="center"><a href="http://www.marceloalves.com"><img src="https://avatars1.githubusercontent.com/u/216782?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Marcelo Alves</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=MarceloAlves" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/zorzysty"><img src="https://avatars0.githubusercontent.com/u/5398733?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Zorza</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=zorzysty" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://tkdodo.eu"><img src="https://avatars0.githubusercontent.com/u/1021430?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Dominik Dorfmeister</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Code">💻</a> <a href="https://github.com/tannerlinsley/react-query/commits?author=tkdodo" title="Documentation">📖</a> <a href="#maintenance-tkdodo" title="Maintenance">🚧</a> <a href="#question-tkdodo" title="Answering Questions">💬</a> <a href="https://github.com/tannerlinsley/react-query/pulls?q=is%3Apr+reviewed-by%3Atkdodo" title="Reviewed Pull Requests">👀</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://katt.dev"><img src="https://avatars.githubusercontent.com/u/459267?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Alex Johansson</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=KATT" title="Code">💻</a></td>
+    <td align="center"><a href="http://www.eddyvinck.nl"><img src="https://avatars.githubusercontent.com/u/23434753?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Eddy</b></sub></a><br /><a href="https://github.com/tannerlinsley/react-query/commits?author=EddyVinck" title="Code">💻</a></td>
   </tr>
 </table>
 
-<!-- markdownlint-enable -->
+<!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 
 <!-- ALL-CONTRIBUTORS-LIST:END -->

diff --git a/docs/src/components/LayoutDocs.js b/docs/src/components/LayoutDocs.js
@@ -106,7 +106,7 @@ export const LayoutDocs = props => {
                       width: 200,
                     }}
                   >
-                    <div className="sticky top-24 overflow-y-auto">
+                    <div className="sticky top-24">
                       <h4 className="font-semibold uppercase text-sm mb-2 mt-2 text-gray-500">
                         On this page
                       </h4>

diff --git a/docs/src/pages/guides/migrating-to-react-query-4.md b/docs/src/pages/guides/migrating-to-react-query-4.md
@@ -94,6 +94,43 @@ For the same reason, those have also been combined:
 
 This flag defaults to `active` because `refetchActive` defaulted to `true`. This means we also need a way to tell `invalidateQueries` to not refetch at all, which is why a fourth option (`none`) is also allowed here.
 
+### Streamlined NotifyEvents
+
+Subscribing manually to the `QueryCache` has always given you a `QueryCacheNotifyEvent`, but this was not true for the `MutationCache`. We have streamlined the behavior and also adapted event names accordingly.
+
+#### QueryCacheNotifyEvent
+
+```diff
+- type: 'queryAdded'
++ type: 'added'
+- type: 'queryRemoved'
++ type: 'removed'
+- type: 'queryUpdated'
++ type: 'updated'
+```
+
+#### MutationCacheNotifyEvent
+
+The `MutationCacheNotifyEvent` uses the same types as the `QueryCacheNotifyEvent`.
+
+> Note: This is only relevant if you manually subscribe to the caches via `queryCache.subscribe` or `mutationCache.subscribe`
+
+### The `src/react` directory was renamed to `src/reactjs`
+
+Previously, react-query had a directory named `react` which imported from the `react` module. This could cause problems with some Jest configurations, resulting in errors when running tests like:
+
+```
+TypeError: Cannot read property 'createContext' of undefined
+```
+
+With the renamed directory this no longer is an issue.
+
+If you were importing anything from `'react-query/react'` directly in your project (as opposed to just `'react-query'`), then you need to update your imports:
+
+```diff
+- import { QueryClientProvider } from 'react-query/react';
++ import { QueryClientProvider } from 'react-query/reactjs';
+```
 
 ### `persistQueryClient` and its sister plugins are no longer expermental and have been renamed
 
@@ -111,4 +148,8 @@ Since these plugins are no longer experimental, there import paths have also bee
 + import { createAsyncStoragePersister } from 'react-query/createAsyncStoragePersister'
 ```
 
+## New Features 🚀
+
+### Mutation Cache Garbage Collection
 
+Mutations can now also be garbage collected automatically, just like queries. The default `cacheTime` for mutations is also set to 5 minutes.
diff --git a/docs/src/pages/guides/query-cancellation.md b/docs/src/pages/guides/query-cancellation.md
@@ -97,6 +97,19 @@ const query = useQuery('todos', ({ signal }) => {
 })
 ```
 
+## Using `graphql-request`
+
+An `AbortSignal` can be set in the `GraphQLClient` constructor.
+
+```js
+const query = useQuery('todos', ({ signal }) => {
+  const client = new GraphQLClient(endpoint, {
+    signal,
+  });
+  return client.request(query, variables)
+})
+```
+
 ## Manual Cancellation
 
 You might want to cancel a query manually. For example, if the request takes a long time to finish, you can allow the user to click a cancel button to stop the request. To do this, you just need to call `queryClient.cancelQueries(key)`, which will cancel the query and revert it back to its previous state. If `promise.cancel` is available, or you have consumed the `signal` passed to the query function, React Query will additionally also cancel the Promise.

diff --git a/docs/src/pages/reference/MutationCache.md b/docs/src/pages/reference/MutationCache.md
@@ -60,16 +60,16 @@ const mutations = mutationCache.getAll()
 The `subscribe` method can be used to subscribe to the mutation cache as a whole and be informed of safe/known updates to the cache like mutation states changing or mutations being updated, added or removed.
 
 ```js
-const callback = mutation => {
-  console.log(mutation)
+const callback = event => {
+  console.log(event.type, event.mutation)
 }
 
 const unsubscribe = mutationCache.subscribe(callback)
 ```
 
 **Options**
 
-- `callback: (mutation?: Mutation) => void`
+- `callback: (mutation?: MutationCacheNotifyEvent) => void`
   - This function will be called with the mutation cache any time it is updated.
 
 **Returns**

diff --git a/docs/src/pages/reference/useMutation.md b/docs/src/pages/reference/useMutation.md
@@ -17,12 +17,14 @@ const {
   reset,
   status,
 } = useMutation(mutationFn, {
+  cacheTime,
   mutationKey,
   onError,
   onMutate,
   onSettled,
   onSuccess,
   useErrorBoundary,
+  meta
 })
 
 mutate(variables, {
@@ -38,6 +40,9 @@ mutate(variables, {
   - **Required**
   - A function that performs an asynchronous task and returns a promise.
   - `variables` is an object that `mutate` will pass to your `mutationFn`
+- `cacheTime: number | Infinity`
+  - The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
+  - If set to `Infinity`, will disable garbage collection
 - `mutationKey: string`
   - Optional
   - A mutation key can be set to inherit defaults set with `queryClient.setMutationDefaults` or to identify the mutation in the devtools.
@@ -71,6 +76,9 @@ mutate(variables, {
   - Set this to `true` if you want mutation errors to be thrown in the render phase and propagate to the nearest error boundary
   - Set this to `false` to disable the behavior of throwing errors to the error boundary.
   - If set to a function, it will be passed the error and should return a boolean indicating whether to show the error in an error boundary (`true`) or return the error as state (`false`)
+- `meta: Record<string, unknown>`
+  - Optional
+  - If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever the `mutation` is available (eg. `onError`, `onSuccess` functions of the `MutationCache`).
 
 **Returns**
 

diff --git a/package.json b/package.json
@@ -16,13 +16,13 @@
   "module": "es/index.js",
   "sideEffects": [
     "es/index.js",
-    "es/react/index.js",
-    "es/react/setBatchUpdatesFn.js",
-    "es/react/setLogger.js",
+    "es/reactjs/index.js",
+    "es/reactjs/setBatchUpdatesFn.js",
+    "es/reactjs/setLogger.js",
     "lib/index.js",
-    "lib/react/index.js",
-    "lib/react/setBatchUpdatesFn.js",
-    "lib/react/setLogger.js"
+    "lib/reactjs/index.js",
+    "lib/reactjs/setBatchUpdatesFn.js",
+    "lib/reactjs/setLogger.js"
   ],
   "scripts": {
     "test": "is-ci \"test:ci\" \"test:dev\"",
@@ -60,7 +60,7 @@
     "createAsyncStoragePersister",
     "broadcastQueryClient-experimental",
     "lib",
-    "react",
+    "reactjs",
     "scripts",
     "types"
   ],
@@ -81,7 +81,11 @@
     }
   },
   "typesVersions": {
-    "<4.1": { "types/*": ["types/ts3.8/*"] }
+    "<4.1": {
+      "types/*": [
+        "types/ts3.8/*"
+      ]
+    }
   },
   "devDependencies": {
     "@babel/cli": "^7.11.6",

diff --git a/react/package.json b/react/package.json
diff --git a/reactjs/package.json b/reactjs/package.json
@@ -0,0 +1,6 @@
+{
+  "internal": true,
+  "main": "../lib/reactjs/index.js",
+  "module": "../es/reactjs/index.js",
+  "types": "../types/reactjs/index.d.ts"
+}
diff --git a/src/broadcastQueryClient-experimental/index.ts b/src/broadcastQueryClient-experimental/index.ts
@@ -33,20 +33,20 @@ export function broadcastQueryClient({
     } = queryEvent
 
     if (
-      queryEvent.type === 'queryUpdated' &&
+      queryEvent.type === 'updated' &&
       queryEvent.action?.type === 'success'
     ) {
       channel.postMessage({
-        type: 'queryUpdated',
+        type: 'updated',
         queryHash,
         queryKey,
         state,
       })
     }
 
-    if (queryEvent.type === 'queryRemoved') {
+    if (queryEvent.type === 'removed') {
       channel.postMessage({
-        type: 'queryRemoved',
+        type: 'removed',
         queryHash,
         queryKey,
       })
@@ -61,7 +61,7 @@ export function broadcastQueryClient({
     tx(() => {
       const { type, queryHash, queryKey, state } = action
 
-      if (type === 'queryUpdated') {
+      if (type === 'updated') {
         const query = queryCache.get(queryHash)
 
         if (query) {
@@ -77,7 +77,7 @@ export function broadcastQueryClient({
           },
           state
         )
-      } else if (type === 'queryRemoved') {
+      } else if (type === 'removed') {
         const query = queryCache.get(queryHash)
 
         if (query) {