feat: add hydration support for mutations

Author: boschni

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

@@ -368,6 +368,10 @@ const mutation = useMutation(addTodo, {
 
 If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.
 
+#### Persist mutations
+
+Mutations can now be persisted to storage and resumed at a later point. More information can be found in the mutations documentation.
+
 #### QueryObserver
 
 A `QueryObserver` can be used to create and/or watch a query:

docs/src/pages/guides/mutations.md

@@ -205,3 +205,52 @@ const mutation = useMutation(addTodo, {
 ```
 
 If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.
+
+## Persist mutations
+
+Mutations can be persisted to storage if needed and resumed at a later point. This can be done with the hydration functions:
+
+```js
+const queryClient = new QueryClient()
+
+// Define the "addTodo" mutation
+queryClient.setMutationDefaults('addTodo', {
+  mutationFn: addTodo,
+  onMutate: variables => {
+    // Cancel current queries for the todos list
+    await queryClient.cancelQueries('todos')
+
+    // Create optimistic todo
+    const optimisticTodo = { id: uuid(), title: variables.title }
+
+    // Add optimistic todo to todos list
+    queryClient.setQueryData('todos', old => [...old, optimisticTodo])
+
+    // Return context with the optimistic todo
+    return { optimisticTodo }
+  },
+  onSuccess: (result, variables, context) => {
+    // Replace optimistic todo in the todos list with the result
+    queryClient.setQueryData('todos', old => old.map(todo => todo.id === context.optimisticTodo.id ? result : todo))
+  },
+  onError: (error, variables, context) => {
+    // Remove optimistic todo from the todos list
+    queryClient.setQueryData('todos', old => old.filter(todo => todo.id !== context.optimisticTodo.id))
+  },
+  retry: 3,
+})
+
+// Start mutation in some component:
+const mutation = useMutation('addTodo')
+mutation.mutate({ title: 'title' })
+
+// If the mutation has been paused because the device is for example offline,
+// Then the paused mutation can be dehydrated when the application quits:
+const state = dehydrate(queryClient)
+
+// The mutation can then be hydrated again when the application is started:
+hydrate(queryClient, state)
+
+// Resume the paused mutations:
+queryClient.resumePausedMutations()
+```

docs/src/pages/reference/hydration/dehydrate.md

@@ -20,10 +20,22 @@ const dehydratedState = dehydrate(queryClient, {
   - The `queryClient` that should be dehydrated
 - `options: DehydrateOptions`
   - Optional
+  - `dehydrateMutations: boolean`
+    - Optional
+    - Whether or not to dehydrate mutations.
+  - `dehydrateQueries: boolean`
+    - Optional
+    - Whether or not to dehydrate queries.
+  - `shouldDehydrateMutation: (mutation: Mutation) => boolean`
+    - Optional
+    - This function is called for each mutation in the cache
+    - Return `true` to include this mutation in dehydration, or `false` otherwise
+    - The default version only includes paused mutations
   - `shouldDehydrateQuery: (query: Query) => boolean`
+    - Optional
     - This function is called for each query in the cache
     - Return `true` to include this query in dehydration, or `false` otherwise
-    - Default version only includes successful queries, do `shouldDehydrateQuery: () => true` to include all queries
+    - The default version only includes successful queries, do `shouldDehydrateQuery: () => true` to include all queries
 
 **Returns**
 

docs/src/pages/reference/hydration/hydrate.md

@@ -21,5 +21,7 @@ hydrate(queryClient, dehydratedState, options)
   - The state to hydrate into the client
 - `options: HydrateOptions`
   - Optional
-  - `defaultOptions: QueryOptions`
-    - The default query options to use for the hydrated queries.
+  - `defaultOptions: DefaultOptions`
+    - Optional
+    - `mutations: MutationOptions` The default mutation options to use for the hydrated mutations.
+    - `queries: QueryOptions` The default query options to use for the hydrated queries.

src/core/mutation.ts

@@ -4,6 +4,7 @@ import type { MutationObserver } from './mutationObserver'
 import { getLogger } from './logger'
 import { notifyManager } from './notifyManager'
 import { Retryer } from './retryer'
+import { noop } from './utils'
 
 // TYPES
 
@@ -15,7 +16,12 @@ interface MutationConfig<TData, TError, TVariables, TContext> {
   state?: MutationState<TData, TError, TVariables, TContext>
 }
 
-export interface MutationState<TData, TError, TVariables, TContext> {
+export interface MutationState<
+  TData = unknown,
+  TError = unknown,
+  TVariables = void,
+  TContext = unknown
+> {
   context: TContext | undefined
   data: TData | undefined
   error: TError | null
@@ -108,6 +114,14 @@ export class Mutation<
     this.observers = this.observers.filter(x => x !== observer)
   }
 
+  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

@@ -48,6 +48,7 @@ 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(mutation)
   }
 
@@ -72,14 +73,14 @@ export class MutationCache extends Subscribable<MutationCacheListener> {
   }
 
   onFocus(): void {
-    this.continueMutations()
+    this.resumePausedMutations()
   }
 
   onOnline(): void {
-    this.continueMutations()
+    this.resumePausedMutations()
   }
 
-  continueMutations(): Promise<void> {
+  resumePausedMutations(): Promise<void> {
     const pausedMutations = this.mutations.filter(x => x.state.isPaused)
     return notifyManager.batch(() =>
       pausedMutations.reduce(

src/core/queryClient.ts

@@ -261,6 +261,17 @@ export class QueryClient {
       .catch(noop)
   }
 
+  cancelMutations(): Promise<void> {
+    const promises = notifyManager.batch(() =>
+      this.mutationCache.getAll().map(mutation => mutation.cancel())
+    )
+    return Promise.all(promises).then(noop).catch(noop)
+  }
+
+  resumePausedMutations(): Promise<void> {
+    return this.getMutationCache().resumePausedMutations()
+  }
+
   executeMutation<
     TData = unknown,
     TError = unknown,

src/core/tests/mutations.test.tsx

@@ -259,7 +259,7 @@ describe('mutations', () => {
       variables: 'todo',
     })
 
-    await queryClient.getMutationCache().continueMutations()
+    await queryClient.resumePausedMutations()
 
     expect(mutation.state).toEqual({
       context: 'todo',

src/hydration/hydration.ts

@@ -1,15 +1,32 @@
 import type { QueryClient } from '../core/queryClient'
-import { Query, QueryState } from '../core/query'
-import type { QueryKey, QueryOptions } from '../core/types'
+import type { Query, QueryState } from '../core/query'
+import type {
+  MutationKey,
+  MutationOptions,
+  QueryKey,
+  QueryOptions,
+} from '../core/types'
+import type { Mutation, MutationState } from '../core/mutation'
 
 // TYPES
 
 export interface DehydrateOptions {
+  dehydrateMutations?: boolean
+  dehydrateQueries?: boolean
+  shouldDehydrateMutation?: ShouldDehydrateMutationFunction
   shouldDehydrateQuery?: ShouldDehydrateQueryFunction
 }
 
 export interface HydrateOptions {
-  defaultOptions?: QueryOptions
+  defaultOptions?: {
+    queries?: QueryOptions
+    mutations?: MutationOptions
+  }
+}
+
+interface DehydratedMutation {
+  mutationKey?: MutationKey
+  state: MutationState
 }
 
 interface DehydratedQuery {
@@ -20,11 +37,14 @@ interface DehydratedQuery {
 }
 
 export interface DehydratedState {
+  mutations: DehydratedMutation[]
   queries: DehydratedQuery[]
 }
 
 export type ShouldDehydrateQueryFunction = (query: Query) => boolean
 
+export type ShouldDehydrateMutationFunction = (mutation: Mutation) => boolean
+
 // FUNCTIONS
 
 function serializePositiveNumber(value: number): number {
@@ -35,6 +55,13 @@ function deserializePositiveNumber(value: number): number {
   return value === -1 ? Infinity : value
 }
 
+function dehydrateMutation(mutation: Mutation): DehydratedMutation {
+  return {
+    mutationKey: mutation.options.mutationKey,
+    state: mutation.state,
+  }
+}
+
 // Most config is not dehydrated but instead meant to configure again when
 // consuming the de/rehydrated data, typically with useQuery on the client.
 // Sometimes it might make sense to prefetch data on the server and include
@@ -48,7 +75,11 @@ function dehydrateQuery(query: Query): DehydratedQuery {
   }
 }
 
-function defaultShouldDehydrate(query: Query) {
+function defaultShouldDehydrateMutation(mutation: Mutation) {
+  return mutation.state.isPaused
+}
+
+function defaultShouldDehydrateQuery(query: Query) {
   return query.state.status === 'success'
 }
 
@@ -58,21 +89,38 @@ export function dehydrate(
 ): DehydratedState {
   options = options || {}
 
-  const shouldDehydrateQuery =
-    options.shouldDehydrateQuery || defaultShouldDehydrate
-
+  const mutations: DehydratedMutation[] = []
   const queries: DehydratedQuery[] = []
 
-  client
-    .getQueryCache()
-    .getAll()
-    .forEach(query => {
-      if (shouldDehydrateQuery(query)) {
-        queries.push(dehydrateQuery(query))
-      }
-    })
+  if (options?.dehydrateMutations !== false) {
+    const shouldDehydrateMutation =
+      options.shouldDehydrateMutation || defaultShouldDehydrateMutation
+
+    client
+      .getMutationCache()
+      .getAll()
+      .forEach(mutation => {
+        if (shouldDehydrateMutation(mutation)) {
+          mutations.push(dehydrateMutation(mutation))
+        }
+      })
+  }
+
+  if (options?.dehydrateQueries !== false) {
+    const shouldDehydrateQuery =
+      options.shouldDehydrateQuery || defaultShouldDehydrateQuery
+
+    client
+      .getQueryCache()
+      .getAll()
+      .forEach(query => {
+        if (shouldDehydrateQuery(query)) {
+          queries.push(dehydrateQuery(query))
+        }
+      })
+  }
 
-  return { queries }
+  return { mutations, queries }
 }
 
 export function hydrate(
@@ -84,9 +132,23 @@ export function hydrate(
     return
   }
 
+  const mutationCache = client.getMutationCache()
   const queryCache = client.getQueryCache()
+
+  const mutations = (dehydratedState as DehydratedState).mutations || []
   const queries = (dehydratedState as DehydratedState).queries || []
 
+  mutations.forEach(dehydratedMutation => {
+    mutationCache.build(
+      client,
+      {
+        ...options?.defaultOptions?.mutations,
+        mutationKey: dehydratedMutation.mutationKey,
+      },
+      dehydratedMutation.state
+    )
+  })
+
   queries.forEach(dehydratedQuery => {
     const query = queryCache.get(dehydratedQuery.queryHash)
 
@@ -102,7 +164,7 @@ export function hydrate(
     queryCache.build(
       client,
       {
-        ...options?.defaultOptions,
+        ...options?.defaultOptions?.queries,
         queryKey: dehydratedQuery.queryKey,
         queryHash: dehydratedQuery.queryHash,
         cacheTime: deserializePositiveNumber(dehydratedQuery.cacheTime),