refactor(react,vue): rename mutate functions to mutate/mutateAsync (#4878)

* chore: tweaks

* chore: up

* chore: changeset

* chore: react

* chore: vue

* chore: tweaks

* chore: audit

* chore: up

* docs: up

Author: tmm

.changeset/eager-jobs-rhyme.md

@@ -0,0 +1,26 @@
+---
+"wagmi": minor
+"@wagmi/vue": patch
+---
+
+Deprecated custom mutate function names and renamed to `mutate`/`mutateAsync` to reduce destructure key renaming fatigue and align with TanStack Query terminology.
+
+**Before**
+
+Had to destructure hook result and often rename keys when using multiple of the same hook. Could decide not to destructure, but syntax becomes awkward for mutate functions (e.g. `connect.connect` or `connect.connectAsync`).
+
+```ts
+const { connect, isPending: connectIsPending } = useConnect()
+const { writeContract: transfer, error: transferError, isPending: transferIsPending } = useWriteContract()
+const { writeContract: approve, error: approveError } = useWriteContract()
+```
+
+**After**
+
+Allows you to name the hook result whatever you want and not worry about also renaming properties.
+
+```ts
+const connect = useConnect() // connect.isPending
+const transfer = useWriteContract() // transfer.mutate, transfer.error, transfer.isPending
+const approve = useWriteContract() // approve.mutate, approve.error
+```

packages/react/src/hooks/codegen/createUseWriteContract.ts

@@ -63,6 +63,81 @@ export type CreateUseWriteContractReturnType<
     wagmi_UseWriteContractReturnType<config, context>,
     'writeContract' | 'writeContractAsync'
   > & {
+    mutate: <
+      const abi2 extends abi,
+      name extends functionName extends ContractFunctionName<
+        abi,
+        stateMutability
+      >
+        ? functionName
+        : ContractFunctionName<abi, stateMutability>,
+      args extends ContractFunctionArgs<abi2, stateMutability, name>,
+      chainId extends config['chains'][number]['id'],
+    >(
+      variables: Variables<
+        abi2,
+        functionName,
+        name,
+        args,
+        config,
+        chainId,
+        address
+      >,
+      options?:
+        | MutateOptions<
+            WriteContractData,
+            WriteContractErrorType,
+            WriteContractVariables<
+              abi2,
+              name,
+              args,
+              config,
+              chainId,
+              // use `functionName` to make sure it's not union of all possible function names
+              name
+            >,
+            context
+          >
+        | undefined,
+    ) => void
+    mutateAsync: <
+      const abi2 extends abi,
+      name extends functionName extends ContractFunctionName<
+        abi,
+        stateMutability
+      >
+        ? functionName
+        : ContractFunctionName<abi, stateMutability>,
+      args extends ContractFunctionArgs<abi2, stateMutability, name>,
+      chainId extends config['chains'][number]['id'],
+    >(
+      variables: Variables<
+        abi2,
+        functionName,
+        name,
+        args,
+        config,
+        chainId,
+        address
+      >,
+      options?:
+        | MutateOptions<
+            WriteContractData,
+            WriteContractErrorType,
+            WriteContractVariables<
+              abi2,
+              name,
+              args,
+              config,
+              chainId,
+              // use `functionName` to make sure it's not union of all possible function names
+              name
+            >,
+            context
+          >
+        | undefined,
+    ) => Promise<WriteContractData>
+    /** @deprecated use `mutate` instead */
     writeContract: <
       const abi2 extends abi,
       name extends functionName extends ContractFunctionName<
@@ -100,6 +175,7 @@ export type CreateUseWriteContractReturnType<
           >
         | undefined,
     ) => void
+    /** @deprecated use `mutateAsync` instead */
     writeContractAsync: <
       const abi2 extends abi,
       name extends functionName extends ContractFunctionName<
@@ -158,76 +234,78 @@ export function createUseWriteContract<
       const result = useWriteContract(parameters)
       const configChainId = useChainId({ config })
       type Args = Parameters<wagmi_UseWriteContractReturnType['writeContract']>
-      return {
-        ...(result as any),
-        writeContract: useCallback(
-          (...args: Args) => {
-            const chainId = (() => {
-              if (args[0].chainId) return args[0].chainId
-              return configChainId
-            })()
-            const variables = {
-              ...(args[0] as any),
-              address: chainId ? props.address?.[chainId] : undefined,
-              ...(props.functionName
-                ? { functionName: props.functionName }
-                : {}),
-              abi: props.abi,
-            }
-            result.writeContract(variables, args[1] as any)
-          },
-          [props, configChainId, result.writeContract],
-        ),
-        writeContractAsync: useCallback(
-          (...args: Args) => {
-            const chainId = (() => {
-              if (args[0].chainId) return args[0].chainId
-              return configChainId
-            })()
-            const variables = {
-              ...(args[0] as any),
-              address: chainId ? props.address?.[chainId] : undefined,
-              ...(props.functionName
-                ? { functionName: props.functionName }
-                : {}),
-              abi: props.abi,
-            }
-            return result.writeContractAsync(variables, args[1] as any)
-          },
-          [props, configChainId, result.writeContractAsync],
-        ),
-      }
-    }
-
-  return (parameters) => {
-    const result = useWriteContract(parameters)
-    type Args = Parameters<wagmi_UseWriteContractReturnType['writeContract']>
-    return {
-      ...(result as any),
-      writeContract: useCallback(
+      const mutate = useCallback(
         (...args: Args) => {
+          const chainId = (() => {
+            if (args[0].chainId) return args[0].chainId
+            return configChainId
+          })()
           const variables = {
             ...(args[0] as any),
-            ...(props.address ? { address: props.address } : {}),
+            address: chainId ? props.address?.[chainId] : undefined,
             ...(props.functionName ? { functionName: props.functionName } : {}),
             abi: props.abi,
           }
           result.writeContract(variables, args[1] as any)
         },
-        [props, result.writeContract],
-      ),
-      writeContractAsync: useCallback(
+        [props, configChainId, result.writeContract],
+      )
+      const mutateAsync = useCallback(
         (...args: Args) => {
+          const chainId = (() => {
+            if (args[0].chainId) return args[0].chainId
+            return configChainId
+          })()
           const variables = {
             ...(args[0] as any),
-            ...(props.address ? { address: props.address } : {}),
+            address: chainId ? props.address?.[chainId] : undefined,
             ...(props.functionName ? { functionName: props.functionName } : {}),
             abi: props.abi,
           }
           return result.writeContractAsync(variables, args[1] as any)
         },
-        [props, result.writeContractAsync],
-      ),
+        [props, configChainId, result.writeContractAsync],
+      )
+      return {
+        ...(result as any),
+        mutate,
+        mutateAsync,
+        writeContract: mutate,
+        writeContractAsync: mutateAsync,
+      }
+    }
+
+  return (parameters) => {
+    const result = useWriteContract(parameters)
+    type Args = Parameters<wagmi_UseWriteContractReturnType['writeContract']>
+    const mutate = useCallback(
+      (...args: Args) => {
+        const variables = {
+          ...(args[0] as any),
+          ...(props.address ? { address: props.address } : {}),
+          ...(props.functionName ? { functionName: props.functionName } : {}),
+          abi: props.abi,
+        }
+        result.mutate(variables, args[1] as any)
+      },
+      [props, result.mutate],
+    )
+    const mutateAsync = useCallback(
+      (...args: Args) => {
+        const variables = {
+          ...(args[0] as any),
+          ...(props.address ? { address: props.address } : {}),
+          ...(props.functionName ? { functionName: props.functionName } : {}),
+          abi: props.abi,
+        }
+        return result.mutateAsync(variables, args[1] as any)
+      },
+      [props, result.mutateAsync],
+    )
+    return {
+      ...(result as any),
+      writeContract: mutate,
+      writeContractAsync: mutateAsync,
     }
   }
 }

packages/react/src/hooks/useCallsStatus.test.ts

@@ -14,7 +14,7 @@ test('default', async () => {
 
   const { result } = await renderHook(() => useSendCalls())
 
-  result.current.sendCalls({
+  result.current.mutate({
     calls: [
       {
         data: '0xdeadbeef',