feat: mutation cachetime

docs

Author: TkDodo

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

@@ -93,3 +93,30 @@ 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`
+
+## 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.

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**

docs/src/pages/reference/useMutation.md

@@ -17,13 +17,14 @@ const {
   reset,
   status,
 } = useMutation(mutationFn, {
+  cacheTime,
   mutationKey,
   onError,
   onMutate,
   onSettled,
   onSuccess,
   useErrorBoundary,
-  meta,
+  meta
 })
 
 mutate(variables, {
@@ -39,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.