Docs: update mutate options description

[SirMoustache]

Hey, in useMutation options docs description for onSuccess, onError and onSettled says

If a promise is returned, it will be awaited and resolved before proceeding

So in this example, the mutation will wait for the promise in onSuccess to be resolved before changing mutation status and data

{
  const { data, isLoading } = useMutation(
    () => {
      /**Some async stuff */
    },
    {
      onSuccess: () => {
        /** Will wait to be resolved before changing the mutation status */
        return delay(5000);
      },
    }
  );
}

It also says in mutate options

Remaining options extend the same options described above in the useMutation hook.

But if used like this the promise will not be awaited

  const { data, isLoading, mutate } = useMutation(() => {
    /**Some async stuff */
  });

  mutate(undefined, {
    onSuccess: () => {
      /** Will NOT wait to be resolved before changing the mutation status */
      return delay(5000);
    },
  });

As I understand, this is intended behavior, so I want to update the docs to clarify this.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 0c58012:

Sandbox	Source
@tanstack/query-example-react-basic	Configuration
@tanstack/query-example-react-basic-typescript	Configuration

[TkDodo]

yeah it's intended, but I wouldn't phrase it as "if a promise is returned, it's not awaited". The signature is different, as those callbacks can only return void according to the typescript definitions.

[SirMoustache]

yeah it's intended, but I wouldn't phrase it as "if a promise is returned, it's not awaited". The signature is different, as those callbacks can only return void according to the typescript definitions.

Thank you for your reply, but are you sure about the return types?

Both MutationOptions interface and MutateOptions have same return types for onSuccess, onError and onSettled functions, so maybe replacing it to void in MutateOptions could be a good solution?

[TkDodo]

@SirMoustache you are absolutely right. I don't know why we should allow to return a Promise from the mutate callbacks, as we are not awaiting them.

so maybe replacing it to void in MutateOptions could be a good solution?

Yes, I'd say so. Would you like to add that to this PR ?

[SirMoustache]

@TkDodo I have done that, also I changed the wording in docs and explicitly provided a description for mutation callbacks

[codecov-commenter]

Codecov Report

Base: 96.36% // Head: 96.82% // Increases project coverage by +0.46% 🎉

Coverage data is based on head (0c58012) compared to base (eab6e2c).
Patch has no changes to coverable lines.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4133      +/-   ##
==========================================
+ Coverage   96.36%   96.82%   +0.46%     
==========================================
  Files          45       58      +13     
  Lines        2281     2676     +395     
  Branches      640      786     +146     
==========================================
+ Hits         2198     2591     +393     
- Misses         80       83       +3     
+ Partials        3        2       -1     

Impacted Files	Coverage Δ
src/core/infiniteQueryObserver.ts
src/react/useQuery.ts
src/devtools/Logo.tsx
src/react/Hydrate.tsx
src/devtools/styledComponents.ts
src/core/hydration.ts
src/devtools/utils.ts
src/react/useMutation.ts
src/core/mutationObserver.ts
src/react/reactBatchedUpdates.ts
... and 93 more

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.