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.

[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

[bmelnychuk]

Hey @TkDodo, any updates here? we are also very interested in this

[jbojcic1]

I have the similar use case and this would be very beneficial

[jbojcic1]

not really. I am referring to the ability to be able to set the scope dynamically either by allowing to pass it to mutate fn like suggested above or if that is not intuitive as mentioned above maybe by allowing to define it as a function that takes mutate params as args so I can build the scope id from params

[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!:)

[Kass86]

Can we use it now? @TkDodo

[TkDodo]

sure: https://tanstack.com/query/latest/docs/framework/react/guides/mutations#mutation-scopes

[boosja]

This version broke our app.

When the app goes online after being offline all mutations run in parallel. This breaks our app since we require serial execution after being offline.

I guess I can add the same scope to every mutation we have in our app, but this feature is still a breaking change in the library.

• Version 5.29.2 runs the mutations in serial when going online.
• Version 5.31.0 runs them in parallel as described above.

The feature itself is a very nice addition! An option to use scope in the mutate call is a great proposal IMO.

[TkDodo]

I'm aware that we changed the behaviour, but I would rather see it as a bugfix because the same mutations used to run in parallel when you are online, but in serial when you came online after having been offline. So clicking the same button twice behaved differently. Now, this bug is fixed because it will behave the same no matter if you are online when the mutation is triggered or if you are coming back from being offline. It's all dependent on the mutation scope.

The documentation also never said that they run in serial, just that they will be executed in the same order:

If mutations fail because the device is offline, they will be retried in the same order when the device reconnects.

The fix is indeed to add the same scope for all mutations, or even to set the same scope globally for all mutations.

[boosja]

I see. Thanks for responding.

Is it possible to have them run in parallel while online, but serially after being offline?

[TkDodo]

I don't think so