Debounced mutation proposal

[kripod]

Hello,

I’ve been using React Query for a while and one of the features I miss the most is mutation debouncing. After having a discussion over trpc/trpc#368, I realized there’s a way to implement a useDebouncedMutation hook in user-land, even though it’s a bit of a struggle to make:

import * as React from "react";
import {
  CancelledError,
  MutationFunction,
  useMutation,
  UseMutationOptions,
  UseMutationResult,
  useQueryClient,
} from "react-query";

export function useDebouncedMutation<
  TData = unknown,
  TError = unknown,
  TVariables = void,
  TContext = unknown,
>(
  mutationFnBase: MutationFunction<TData, TVariables>,
  {
    delayMs,
    retry: retryBase,
    onMutate: onMutateBase,
    ...restOptions
  }: UseMutationOptions<TData, TError, TVariables, TContext> & {
    delayMs: number;
  },
): UseMutationResult<TData, TError, TVariables, TContext> {
  const abortControllerRef = React.useRef<AbortController | null>(null);
  const queryClient = useQueryClient();

  const mutationFn: MutationFunction<TData, TVariables> = useEventCallback(
    async (input) => {
      abortControllerRef.current = new AbortController();
      await sleep(delayMs, { signal: abortControllerRef.current.signal });

      return mutationFnBase(input);
    },
  );

  const retry: UseMutationOptions<
    TData,
    TError,
    TVariables,
    TContext
  >["retry"] = (failureCount, error) => {
    if (error instanceof CancelledError) return false;

    if (typeof retryBase === "function") return retryBase(failureCount, error);
    if (typeof retryBase === "number") return failureCount < retryBase;
    return retryBase ?? false;
  };

  return useMutation(mutationFn, {
    retry,
    onMutate: async (...args) => {
      abortControllerRef.current?.abort();

      /* Wait for discarded mutations to roll back optimistic changes */
      await Promise.all(
        queryClient
          .getMutationCache()
          .getAll()
          .filter(
            (mutation) =>
              mutation.options.mutationFn === (mutationFn as MutationFunction),
          )
          .map((mutation) => mutation.cancel()),
      );

      return onMutateBase?.(...args) as Promise<TContext>;
    },
    ...restOptions,
  });
}

function sleep(
  ms: number,
  { signal }: { signal?: AbortSignal } = {},
): Promise<void> {
  return new Promise((resolve, reject) => {
    const timeoutId = window.setTimeout(resolve, ms);
    signal?.addEventListener("abort", () => {
      window.clearTimeout(timeoutId);
      reject(new DOMException("The operation was aborted.", "AbortError"));
    });
  });
}

function useEventCallback<T, P extends unknown[]>(
  callback: (...args: P) => T,
): (...args: P) => T {
  const ref = React.useRef(callback);
  React.useEffect(() => {
    ref.current = callback;
  });
  return React.useCallback((...args: P) => ref.current(...args), []);
}

I would love to see a delayMs (or debounceMs) parameter added into the core useMutation hook. I think it should also be possible to cancel mutations silently – without flooding the console – but unfortunately, the current mutation.cancel method doesn’t allow that. (CancelledError, which is already being utilized by queries, can take a silent argument, though.)

Also, overriding retry wouldn’t be necessary with built-in support for handling CancelledError instances within mutations.

In order to support more browsers, AbortController could be made optional (checked with typeof AbortController !== "undefined"), while keeping track of which mutations to execute, e.g. with a counter.

[TkDodo]

I think there are a couple of concepts being mixed here, let's try to separate them please:

1. Mutation cancellation

I've heard this request before, but I'm not really getting the concept. As far as I'm aware, query cancellation cancels the network request so that the browser does not need to download the rest of the data. This is optional in react-query, and possible by attaching a .cancel method on the Promise returned from the QueryFn. How cancellation takes place has to happen in user-land, because react-query is Promise based - not network based. We could also use react-query to write to AsyncStorage for LocalForage for example. Anything promise-based is legit - the network is just the most prominent thing. I'm not a backend dev, but I think you could even use it on the backend to fetch and cache data from databases like prisma or so 😮 .

How will this work with mutations? I'm not finding anything on the internet what happens physically when a request is aborted. All examples are for get requests only. I know that the request method per se doesn't matter, but let's presume the following situation:

• I have a button that makes a POST request to create a user via useMuation().mutate
• I click the button, I send the request to the backend
• the backend receives the request, opens a database transaction, starts inserting the user
• now I abort the request
• what happens? Is the backend informed of this? How will the transaction be reverted? What if the backend has already committed the transaction?

Maybe I'm just overthinking this, but I don't understand how one can physically abort a mutation that actually has a side-effect on the server ...

2. debouncing the mutation

calling the mutate function is already an imperative approach, so if we take aborting a mutation out of the equation, I think it would be just (using lodash.debounce):

const { mutate } = useMutation()
const debouncedMutate = debounce(mutate, 250)

<button onClick={() => debouncedMutate()}>

would it not?

[freeman1995]

u need to wrap it with useMemo..

[kripod]

Thank you for responding so quickly!

As for cancelling a mutation: HTTP requests are currently performed over the TCP/IP protocol, which guarantees that a packet either arrives in its entirety or gets dropped. If a mutation with a large payload is executed (e.g. with an image weighing ~5MB), we could save some bandwidth by canceling the upload procedure early. The server doesn’t perform any business logic on dropped transfers. (The same thing applies to accidental disconnects.)

Debouncing a mutation as you’ve suggested doesn’t work together with optimistic updates. In your example, React Query’s onMutate callback would only be invoked after nothing is being done for at least 250ms. That’s why I came up with the idea to integrate mutation debouncing into the core, so that optimistic updates are still performed in real time, while the actual fetch (or other async procedure) calls would be delayed.

However, when a debounce happens (e.g. mutate gets called twice in <250ms), then the first call’s optimistic update shall be discarded. That’s why awaiting for the cancellation of first mutation matters – we have to roll back the discarded mutation’s effects and only then may we call onMutate optimistically for the second time.

[Wykks]

Humm but removing pause mutation implies that the first mutation is sent. This solution look more like a "throttle" (but only the first mutation is sent) than a "debounce". But the last mutation is the relevant one, not the first.

I can solve the issue, by doing some work in the component : instead of using onMutate, I can just use setQueryData directly in the component, and then debounce the mutate call.
But I don't think it's a good idea to do this work inside the component, and it would defeat the purpose of onMutate.

[Wykks]

Oh I see, I could set all the mutation is a paused state, and then after a timer, remove all the mutation except the last one, and unpause it. Assuming onMutate run even if the mutation is paused, that could work.

Although, I have no idea if a mutation can be created in a paused state.

[TkDodo]

Assuming onMutate run even if the mutation is paused

it does.

I have no idea if a mutation can be created in a paused state.

It can, that’s what scope does.

But the last mutation is the relevant one, not the first.

I understand that, I don’t think we’re talking about the same thing though. Let’s say you click the button 3 times. If they are in the same scope, what happens is that we:

• create the first mutation, in pending state
• the second mutation is in paused state
• the third one is also in paused state

if the first mutation settles, the next mutation in the queue would transition to pending state (second mutation)

so really all you have to do is, when third mutation starts (onMutate), you would remove all mutations from the cache that are in the same scope and that are in paused state, because that would leave you with:

• first mutation, pending state
• third mutation, paused state

then if fourth mutation comes in, it would do the same, resulting in

• first mutation, pending state
• fourth mutation, paused state

and so on

[Wykks]

I see, thanks!
Although, this approach have a (small) issue: the first mutation will always be sent. That's good enough 👍

And it can be even better for some kind of input, for example a checkbox, checked only once by the user, and not having to wait for the useless debounce in this case to send the request.

Thanks again for your time!

[TkDodo]

if you want, you can look into contributing this as a scope feature:

scope: {
  id: string,
  max: number
}

if max is reached, we would automatically remove paused mutations from the beginning. In your case, max would simply be 1.

[kazemmdev]

Hey everyone,

I needed to implement debouncing for the mutate in my code, and here’s the solution I came up with. If you also need to debounce the mutate function, you can use lodash’s debounce with both the trailing and leading options as shown below:

import { useMutation, useQueryClient } from "@tanstack/react-query"

import { fetchClient } from "@/lib/fetch"
import debounce from "lodash.debounce"

export const useSaveMutation = () => {
  const queryClient = useQueryClient()

  const saveArticlesFn = debounce(async (data: any) => {
    const response = await fetchClient({
      url: `articles/${data.uuid}`,
      method:  "put" ,
      body: data
    })
    return response?.data
  }, 4000, { leading: true, trailing: true })

  return useMutation({
    mutationFn: saveArticlesFn,
    onSuccess: async data => {
      await queryClient.invalidateQueries({
        queryKey: useArticleKeys.filtered(params)
      })
    },
    onMutate: async (data: any) => {
      console.log(data)
      queryClient.setQueryData(
        useArticleKeys.detail(data?.uuid),
        (prev: any) => ({ ...prev, ...data })
      )
    },
    onError: (error, variables) => {
      console.error(error)
      queryClient.setQueryData(
        useArticleKeys.detail(slug as string),
        prev => prev
      )
    }
  })
}

[czabaj]

Beware that debounce function is statefull - each time you call it, you create a new denounced instance - therefore each time your component with this hook re-renders, it creates a new instance of debounced function, which has no clue about the previous - so if your React component re-renders frequently, it will bypass the debounce - you need to store the instance in useState - useMemo would occasionally not work as well, as it is only a performance optimization and does not guarantee stable reference.

Also, you are loosing track of the previous data as you update the cache without reading the current value, - in case of an error, you are calling setQueryData(key, prev => prev) and that is a no-op, the update function is an identity function prev => prev so no update is made, you don't have an access to previous data anymore - look at the optimistic updates on how to store the previous data in the context.

Another point worth mentioning is that this would not reflect correctly the state of the requests - the debounce has to have leading: true so it will return to you a Promise created on a first invocation, on subsequent invocations, this will return to the useMutation hook the memorized first Promise, but on the trailing edge, it will fire another async request, which will be "swallowed" - you will not have any reference to Promise from the trailing invocation and therefor your request might be in fly, but your useMutation will not have a clue about it - I guess this point makes that solution practically useless, as the async logic invoked on the trailing edge of the debounce will not call onSuccess nor onError callbacks.