RFC: Scoped Mutations

[TkDodo]

tl;dr: mutations will get a new, opt-in scoping feature. Putting mutations in the same scope will run them in serial rather than in parallel.

The Problem

All our mutations run in parallel, which is generally a good thing. We can't know what our mutations do or which relation they have to each other.

This is a good default behaviour, however, there are sometimes situations, especially when offline mutations are involved, where we'd want to fire mutations in serial. As an example, firing to /PATCH requests to the same resource might result in a ConcurrentModificationException.

Also, queuing some mutations that alter the same entity might make the in-between update unnecessary. For example, let's say we're moving a card on a kanban board from column A to B, followed by an immediate move from B to C. In that case, the first mutation is likely unnecessary and should be aborted and / or discarded.

The proposed solution

As a solution, we'd want to introduce scoping of mutations. Mutations with the same scope would be treated as being in the same queue. This is an opt-in feature. When not given a dedicated scope, mutations get their own unique scope where no other mutation can be in. This will result in the mutation running immediately and in parallel with all other mutations.

There will be no fuzzy matching of scopes - a scope has to fully match an existing one to be treated as "the same".

Technical implementation

We currently store all mutations as an Array<Mutation> in the MutationCache:

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

Line 85 in 4f168d7

#mutations: Array<Mutation<any, any, any, any>>

The idea is to change this structure into:

#mutations: Map<string, Array<Mutation<any, any, any, any>>>

where the key of the Map is the scope's id. This will create Mutation Arrays that live "next to each other". When a mutation wants to run, it has to check if its scope allows it. If there is already a running mutation in the scope, we will not run the mutation, but put it into paused state instead (status: 'pending', isPaused: true). Note that paused was, up until now, only used to pause because there was no network connection. However, there is no limitation as to why we pause them - they can be paused for other reasons, too.

When a mutation finishes (either successfully or erroneously), it has to kick of the next mutation in its scope. This makes sure that mutations that were previously paused will then run once their time has come.

API

Mutations will get a new, optional property:

scope?: {
  id: string
}

If set, mutations in the same scope will be guaranteed to run in serial. The object notation enables to later allow for different scope behaviours. For example, a scope could be implemented to abort previously running mutations when a new mutation is added, and kick of the last mutation immediately. It could also get a takeLatest kind of behaviour where mutations still run serially, but in-between mutations get discarded. In the first iteration, scopes will only get the default behaviour of queuing up mutations and starting the next one in the scope when they are finished.

Resuming Paused Mutations

While being offline, mutations will still get paused - unless the networkMode is set to ignore that. It is therefore not recommended to mix mutations with different networkMode settings in the same scope. As a an example, adding a mutation that should always run into a scope where we already have paused mutations (because of being offline) will result in this mutation also being queued up until being online again, because it depends on the previous mutations to finish before it can start.

When resuming paused mutations after having been offline for some time, only the first mutation of each scope will be continued. The other ones need to wait until their predecessor has finished.

This should fix a couple of bugs around resumePausedMutations, especially:

• race condition in offline -> online state transition with dependent mutations #4896
• All mutations get stuck in paused state if one of them fails #6825
• a not yet reported issue where adding more mutations while paused mutations are being resumed will lead to out-of-order updates (I found this while developing the trellix clone)

Note that we tried to fix #4896 but that fix actually introduced #6825. It also makes all mutations run in serial now, which isn't the same as when those mutations were executed while being online. This proposal tries to fix this holistically - mutations should behave the same no matter if they were added while being offline or not.

[hrastnik]

This sounds good. Only thing I'd suggest is changing the name from scope to queueId

[gotnoklu]

I like this idea of scoping mutations to run them in a queue. However, I agree with @hrastnik on the naming since relating the ID to a queue clearly gives some insight on what's going on.

[lunelson]

I'm personally not bothered by the term scope; but FWIW as I read it, the common aspect between the different potential behaviours of the 'scope', and the fundamental difference from the current behaviour, is that they are all some form of serial pattern, so the property could also be called series?

[zilahir]

i do agree with @TkDodo's way of thinking. I'd actually prefer the scope but naming is just naming :). Alltogetehr,t his is a great proposal!

[hrastnik]

In my opinion the term queue would describe the basic functionality that would be most commonly used. The users would have an intuitive understanding of what the feature does. Then, for advanced use cases, the users will look-up answers like "how do remove request from middle of queue in tanstack query" or similar.

The name should serve the purpose that when the users read it, they intuitively grasp the concept.

[TkDodo]

People could possibly mix a general term as scope with query keys

mutationKey also exists, I hope the distinction is clear, as our keys are arrays and they follow the naming queryKey and mutationKey.

[gotnoklu]

@TkDodo, I get it. I for one am excited about scoped mutations! Great stuff you've got going...

[tometo-dev]

I like the idea. A few questions:
When do we define the scope of the mutations? passed as options to the useMutation call or specifically during the mutate call? or both?
Allowing the prior adds a direct dependency among the mutations, while allowing the later has the flexibility of running the same mutations either parallelly or serially depending on the usecase. This could potentially eliminate the use of some of the onSuccess callbacks.

[TkDodo]

The way I see it, it would be an argumentative to useMutation. But I think technically, we could also allow it when passed to mutate

[fweinaug]

@TkDodo allowing it to be passed to mutate would be a great addition. our use-case is calling the mutation in bulk with different ids which is currently tricky.

[TkDodo]

it's technically possible but it would be somewhat inconsistent. consider:

const { mutate } = useMutation({ mutationFn, onSuccess, scope: { id: '1' } })

mutate(variables, { scope: { id: '2'}, onSuccess: console.log })

with this API, scope would be overwritten to '2', but for the other options on mutate (onSuccess, onError, onSettled), that's not the case, because the callbacks run additionally to the ones on useMutation if the component is still mounted.

so introducing something that's not intuitive is what I'd like to avoid ...

[GoldenChrysus]

I'm very interested in this as well as scoping is a great idea and something I could consider as a reason to switch from SWR to TanStack Query. But the current implementation where the scope is defined on useMutation makes it completely unusable to me.

Use case:
I have multiple tables where nearly every cell for every row is editable. I don't have full control over the table's individual row components, so I can't do something like have useMutation for every row. I would have one useMutation for the entire table. It would be nice if mutation operations for a given row/column were sequential while allowing users to freely mutate other, unrelated records simultaneously if they wish. So I would need several independent scopes on the single mutation. It seems like the only thing I could do currently is scope the entire table so every operation on the table is sequential, but that seems less than ideal when you start building up a decent queue of operations when in reality many of the operations are unrelated to one another and could safely run in parallel.

[TkDodo]

I'll think about it

[DamianOsipiuk]

@TkDodo Two things I would like to clarify.

1. I assume scope would be also available on defaultOptions to basically get serial mutations by default?
2. To make it work properly with persisters, we would need some kind of order property for stored mutations. Then when restoring them on app load, we would be able to properly queue them when same scope is assigned to many of them.

[TkDodo]

1. yes
2. the order is determined by the order in the array. When dehydrating, we call getAll(), which transforms the nested structure to a flat list, but the order is preserved. Then, when hydrating, we go through the list one by one, so the order should be the same.

[momme-rtf]

@TkDodo We would be quite interested in this enhancement. Do you already know if and when we can expect it to be implemented?

[ReangeloJ]

It was just released!

https://x.com/tkdodo/status/1782299195279393182?s=46&t=ylVAbPFr-Qat5giLV4s9qg

[TkDodo]

yes, it's shipped in https://github.com/TanStack/query/releases/tag/v5.31.0

[momme-rtf]

Awesome thanks!:)