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?

[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.

[TkDodo]

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.)

okay, I get that. I'm still wondering what happens if we are past that point, the mutation has already started on the backend, and it takes like 5 seconds or so to process or insert into the database. If we cancel now, what would happen?

Debouncing a mutation as you’ve suggested doesn’t work together with optimistic updates

yes, that's totally right. I see that your waiting for rollback mechanism tries to find matching mutations via the mutationFn. Would the mutationKey also be something that could be used for that?

[kripod]

okay, I get that. I'm still wondering what happens if we are past that point, the mutation has already started on the backend, and it takes like 5 seconds or so to process or insert into the database. If we cancel now, what would happen?

A mutation isn’t cancellable at that point anymore. Both the client and the server are notified about the completion of every packet. I think that even if we used an AbortController on the fetch method, calling abortController.abort() wouldn’t do anything, as it would be too late to have an effect – but I may not be right on this one.

yes, that's totally right. I see that your waiting for rollback mechanism tries to find matching mutations via the mutationFn. Would the mutationKey also be something that could be used for that?

The mutationKey could definitely be used if it had to be specified for every mutation. However, as mutationFn is the only required parameter of a mutation, we can only rely upon that for comparisons. I’m not sure about JS engine internals, but comparing function references – each of which is a single pointer to an object – should even be faster than comparing primitives like strings (which may possibly be performed on a character-by-character basis or via ropes).

[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.