Using createPersister for mutations

[davidjbng]

Allow persisting mutation state through createMutationPersister.

Idea

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      persister: experimental_createQueryPersister({ 
	    // ... 
	  }),
    },
    mutations: {
	  // 👇 new persister option
      persister: experimental_createMutationPersister({ 
	    // ... 
	  }),
    },
  },
})

Usage

• Mutations need a mutationKey to be persisted
• Persisted mutations can be accessed through useMutationState

useMutation({
   mutationKey: ['key']
   // ...
})

const persistedMutations = useMutationState({
   filters: {
      mutationKey: ['key']
   }
})

Resuming Mutations

Pending Mutations could be resumed automatically when a mutation with a matching key mounts.

Use cases

• When you are doing optimistic ui with mutation.variables. You want to persist failed mutation so the user can retry them at any point even after reloading the app.

[TkDodo]

It's a good idea but we have to think this through. One problem is that with mutations, they are never "picked up" when a useMutation mounts, because every call to useMutation yields a new mutation. Even if we get that to work, it also would be weird if mutations don't resume when the app mounts, because with this approach, they would only resume when the component that triggered the mutation is rendered...

@DamianOsipiuk fyi

[TkDodo]

yes this would be the proposed api. Since the whole thing is experimental - feel free to hack away :)

[DamianOsipiuk]

I believe we could make this work with a couple of prerequisites.

• every mutation that would need to be persisted, would need to have mutationKey to properly match it to the usage place
• persist only mutations that were not successful, or maybe only paused ones?
• we would need an iterator over the storage entries in case we would like to restore all of them at once. And some kind of unique prefix for mutations. There is already resumePausedMutations function which we could hook up.

[davidjbng]

After looking through the implementation of createPersister it seems like mutation persister should be its own function createMutationPersister. This leads to the question should createPersister be renamed to createQueryPersister?

The api would look more like this

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      persister: experimental_createQueryPersister({ 
	    // ... 
	  }),
    },
    mutations: {
      persister: experimental_createMutationPersister({ 
	    // ... 
	  }),
    },
  },
})

Why separate createMutationPersister?

• The persister function for mutations will most likely have a different interface. A separate function makes this way easier to type
• The implementation details will be different to createPersister (e.g. mutations cannot be stale, prob some other logic)

[DamianOsipiuk]

Yeah, i also think a different function would be more appropriate for this

[TkDodo]

persist only mutations that were not successful, or maybe only paused ones?

yes, we only persist paused mutations per default in the PersistProvider, too:

query/packages/query-core/src/hydration.ts

Lines 68 to 70 in 497804e

	export function defaultShouldDehydrateMutation(mutation: Mutation) {
	return mutation.state.isPaused
	}

we would need an iterator over the storage entries in case we would like to restore all of them at once.

this would also be great for the retries we discussed, in case of storage being full ...