wagmi-extended 2.0.1 → 2.1.0

package/README.md

@@ -74,102 +74,187 @@ Each hook is documented with detailed JSDoc comments (including usage examples)
 
 ## Hooks explanations and examples
 
-### useERC20ApproveX Hook
+### useContractWriteX Hook
 
-The `useERC20ApproveX` hook simplifies ERC20 token approvals by checking the allowance and handling the transaction to approve transfers.
+The `useContractWriteX` hook wraps Wagmi’s `useWriteContract` with extra features:
 
-Example:
+- **Receipt waiting**: always waits for the transaction receipt before resolving.
+- **Logging control**: disable console logging if you wish.
+- **Query invalidation**: automatically invalidates queries after receipt, either by explicit keys or by predicate.
 
-```bash
-import { useERC20ApproveX } from "wagmi-extended";
+#### Original `writeContractAsync`
 
-function ApproveButton(amountToApprove: number) {
-  const tokenAddress = "0xTokenAddress";      // Replace with your token address
-  const spenderAddress = "0xSpenderAddress";  // Replace with the spender address
+```ts
+const { writeContractAsync, isPending, errorMessage } = useContractWriteX({
+  queriesToInvalidate: [["userBalance"], ["userActivity"]],
+  onSuccess: (txHash) => console.log("✅", txHash),
+  onError: (err) => console.error("❌", err),
+});
 
-  const { isApproved, isApproving, approveAsync } = useERC20ApproveX(
-    tokenAddress,
-    spenderAddress,
-    parseUnits(amountToApprove.toString(), 18),
-  );
+// will wait for the receipt, then invalidate `userBalance` & `userActivity`
+await writeContractAsync({
+  address: "0xContractAddress",
+  abi: MyContractAbi,
+  functionName: "executeFunction",
+  args: [
+    /* ... */
+  ],
+});
+```
 
-  return (
-    <button onClick={approveAsync} disabled={isApproving || isApproved}>
-      {isApproving ? "Approving..." : isApproved ? "Approved" : "Approve Token"}
-    </button>
-  );
-}
+#### New `writeContractX` method
+
+Use `writeContractX` if you need control over the simulation step:
+
+```ts
+const { writeContractX, isPending, errorMessage } = useContractWriteX({
+  onSuccess: (tx) => console.log("✔ Receipt confirmed:", tx),
+  onError: (e) => console.error("✖ Failed:", e),
+});
+
+// simulate + send:
+await writeContractX(
+  {
+    address: "0xContractAddress",
+    abi: MyContractAbi,
+    functionName: "executeFunction",
+    args: [
+      /* ... */
+    ],
+    account: myAddress,
+    chain: myChain,
+    value: 0n,
+  },
+  /* disableSimulation? */ false
+);
+
+// send immediately without simulation:
+await writeContractX(params, /* disableSimulation= */ true);
 ```
 
-### useContractWriteX hook
+- **`writeContractAsync`** = always runs the built-in dry-run, then write.
+- **`writeContractX`** = you can pass a boolean to skip the simulation step.
 
-The `useContractWriteX` hook wraps the contract-writing functionality from Wagmi with additional features like `receipt` waiting, `logging` control, and `query invalidation` after receipt is successfully fetched.
+---
 
-Example:
+### useSendTransactionX Hook
 
-```bash
-function MyTransactionComponent() {
-const { writeContractAsync, isPending, errorMessage } = useContractWriteX({
-    queriesToInvalidate: [["userBalance"], ["userActivity"]],
-    {
-      // use calbacks here in writeContractAsync or in useContractWriteX
-      onSuccess: (txHash) => console.log("Transaction successful:", txHash),
-      onError: (error) => console.error("Transaction error:", error),
-    }
-});
+The `useSendTransactionX` hook wraps Wagmi’s `useSendTransaction` with the same lifecycle features:
 
-const handleWrite = async () => {
-    try {
-      const txHash = await writeContractAsync({
-        address: "0xContractAddress",
-        abi: [], // Provide your contract ABI
-        functionName: "executeFunction",
-        args: [/* function arguments */],
-      });
-      console.log("Received txHash:", txHash);
-    } catch (err) {
-      console.error("Failed writing transaction:", err);`
-    }
-};
+- **`sendTransaction`** = Wagmi’s raw send
+- **`sendTransactionX`** = optionally simulate (contract call) or just `eth_call`, then `sendTransaction` + receipt waiting + invalidations.
 
-return (
-    <div>
-    <button onClick={handleWrite} disabled={isPending}>
-        {isPending ? "Processing..." : "Write Transaction"}
-    </button>
-    {errorMessage && <p>Error: {errorMessage}</p>}
-    </div>
+```ts
+const {
+  sendTransaction, // raw
+  sendTransactionX, // wrapped
+  isPending,
+  errorMessage,
+} = useSendTransactionX({
+  queriesToInvalidate: [["ethBalance"]],
+  onSuccess: (tx) => console.log("🎉 Tx sent & confirmed:", tx),
+  onError: (e) => console.error("🚫 Simulation or send failed:", e),
+});
+
+// simulate & send an ETH transfer:
+await sendTransactionX(
+  { to: recipient, value: 1n * 10n ** 18n, account: myAddress, chain: myChain },
+  // for contract calls, pass simulation params:
+  { abi: MyAbi, functionName: "deposit", args: [1000n], chain: myChain }
 );
-}
+
+// or just raw send (no simulationParams):
+await sendTransactionX({ to, value, account });
 ```
 
-**Important:** To ensure transaction receipts are awaited correctly, **all settings and callbacks must be passed inside the hook itself**, not inside `mutate` or `mutateAsync` calls.
+---
+
+## Transaction mutation settings
 
-Example of correct usage:
+In all “X” hooks you pass a `WriteExtendedAsyncParams` object:
 
 ```ts
-const { writeContractAsync } = useContractWriteX({
-  queriesToInvalidate: [["userBalance"]],
-  onSuccess: (txHash) => console.log("Tx success:", txHash),
-  onError: (err) => console.error("Tx error:", err),
-});
+export type WriteExtendedAsyncParams = {
+  onSuccess?: (txHash: Address) => void;
+  onError?: (e: any) => void;
+  onSettled?: () => void;
+  onSuccessAsync?: (txHash: Address) => Promise<void>;
+  onErrorAsync?: (e: any) => Promise<void>;
+  onSettledAsync?: () => Promise<void>;
+
+  /** simple list of query keys to invalidate after receipt */
+  queriesToInvalidate?: (QueryKey | undefined)[];
+
+  /** predicate-based invalidation:
+      any active query where `predicate(query)` returns true
+      will be invalidated after the tx settles. */
+  invalidatePredicate?: (query: Query<unknown, unknown>) => boolean;
+
+  disableLogging?: boolean;
+  disableWaitingForReceipt?: boolean;
+};
 ```
 
-**Avoid passing callbacks like this:**
+---
+
+### useFetchERC4626DataX Hook
+
+Fetch summary data from an ERC-4626 vault (total assets, shares, allowances, balances, etc.):
 
 ```ts
-await writeContractAsync(config, {
-  onSuccess: () => {}, // ❌ This will NOT guarantee receipt handling!
-});
+import { useFetchERC4626DataX } from "wagmi-extended";
+
+function VaultInfo({ vaultAddress, user, spender }) {
+  const { data, isLoading, error } = useFetchERC4626DataX({
+    vault,
+    user,
+    spender,
+  });
+
+  if (isLoading) return <p>Loading vault data…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <div>
+      <p>Total assets: {data.totalAssets}</p>
+      <p>Current shares: {data.shares}</p>
+      <p>Your balance: {data.userBalance}</p>
+      <p>Your allowance: {data.allowance}</p>
+    </div>
+  );
+}
 ```
 
-This design ensures that `wagmi-extended` can properly track and wait for the transaction receipt, giving your app reliable post-transaction state.
+---
 
-### useSendTransactionX Hook
+### useFetchERC20DataX Hook
+
+Fetch summary data for a generic ERC-20 token (decimals, name, symbol, balances, allowances):
+
+```ts
+import { useFetchERC20DataX } from "wagmi-extended";
 
-The `useSendTransactionX` hook wraps the transaction-sending functionality from Wagmi with additional features like `receipt` waiting, `logging` control, and `query invalidation` after receipt is successfully fetched.
+function TokenInfo({ token, user, spender }) {
+  const { data, isLoading, error } = useFetchERC20DataX({
+    address: token,
+    user,
+    spender,
+  });
 
-Very similar to useContractWriteX, see [playground](https://codesandbox.io/p/sandbox/5jr3lg) for example.
+  if (isLoading) return <p>Loading token info…</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  return (
+    <div>
+      <p>Name: {data.name}</p>
+      <p>Symbol: {data.symbol}</p>
+      <p>Decimals: {data.decimals}</p>
+      <p>Your balance: {data.balance}</p>
+      <p>Your allowance: {data.allowance}</p>
+    </div>
+  );
+}
+```
 
 ### useTokenX Hook
 

package/dist/hooks/mutations/useContractWriteX.d.ts

@@ -1,66 +1,30 @@
 import { WriteExtendedAsyncParams } from "./useHandleTransactionMutationX.js";
 import { Address } from "viem";
 /**
- * Custom hook for writing to a smart contract using Wagmi.
+ * Custom hook for writing to a smart contract using Wagmi with optional simulation.
  *
- * This hook provides functionality for writing a contract using Wagmi, handling the asynchronous nature of the operation, waiting for the transaction receipt, and error handling.
- *
- * @param {WriteExtendedAsyncParams} [settings] - Optional settings for the write operation.
- * @param {boolean} [settings.disableWaitingForReceipt] - Disables waiting for the transaction receipt.
- * @param {boolean} [settings.disableLogging] - Disables logging the result of the transaction.
- * @param {Function} [settings.onSuccess] - Callback function to be called on successful transaction.
- * @param {Function} [settings.onError] - Callback function to be called on transaction error.
- * @param {Function} [settings.onSettled] - Callback function to be called after the transaction settles (whether success or failure).
- * @param {QueryKey[]} [settings.queriesToInvalidate] - Array of query keys to invalidate after the transaction receives a receipt.
- * @returns {Object} Object containing the following properties:
- * - {boolean} isPending - Indicates whether the transaction is pending.
- * - {string|undefined} errorMessage - The error message, if an error occurred during the transaction.
- * - {Function} writeContractAsync - Function to trigger the write operation.
- *
-/**
- * Custom hook for writing a contract using Wagmi with extended functionality.
- *
- * This hook wraps Wagmi’s `useContractWriteX` with additional handling for
- * waiting for a transaction receipt, logging control, and invalidation of specified queries.
- *
- * @param {WriteExtendedAsyncParams} [settings] - Optional settings for handling the transaction.
+ * @param {WriteExtendedAsyncParams} settings - Settings for handling transaction lifecycle:
+ * @param {boolean} [settings.disableWaitingForReceipt] - Disable waiting for receipt.
+ * @param {boolean} [settings.disableLogging] - Disable logging.
+ * @param {Function} [settings.onSuccess] - Callback invoked on successful transaction receipt.
+ * @param {Function} [settings.onError] - Callback invoked on simulation or transaction error.
+ * @param {Function} [settings.onSettled] - Callback invoked after transaction settles.
+ * @param {Array<import('@tanstack/query-core').QueryKey>} [settings.queriesToInvalidate] - Query keys to invalidate after receipt.
  * @returns {Object} An object containing:
- *   - `isPending`: {boolean} indicating if the transaction is in progress.
- *   - `errorMessage`: {string|undefined} a potential error message.
- *   - `writeContractAsync`: {Function} a function to trigger the transaction.
+ *   - writeContract: Wagmi's writeContract function.
+ *   - writeContractX: Wrapped writeContract with optional simulation.
+ *   - isPending: Boolean indicating if transaction is in progress.
+ *   - errorMessage: Error message if one occurred.
  *
  * @example
- * // In your component:
- * function MyTransactionComponent() {
- *   const { writeContractAsync, isPending, errorMessage } = useContractWriteX({
- *     queriesToInvalidate: [["userBalance"], ["userActivity"]],
- *   });
- *
- *   const handleWrite = async () => {
- *     try {
- *       const txHash = await writeContractAsync({ transaction params here.. }, {
- *          // use calbacks here in writeContractAsync or in useContractWriteX
- *          onSuccess: (txHash) => console.log("Transaction successful:", txHash),
- *          onError: (error) => console.error("Transaction error:", error),
- *       });
- *       console.log("Received txHash:", txHash);
- *     } catch (err) {
- *       console.error("Failed writing transaction:", err);`
- *     }
- *   };
- *
- *   return (
- *     <div>
- *       <button onClick={handleWrite} disabled={isPending}>
- *         {isPending ? "Processing..." : "Write Transaction"}
- *       </button>
- *       {errorMessage && <p>Error: {errorMessage}</p>}
- *     </div>
- *   );
- * }
+ * const { writeContractX, isPending, errorMessage } = useContractWriteX({ onSuccess: ..., onError: ... });
+ * await writeContractX(
+ *   { abi, address, functionName, args, account, chain, value },
+ *   disable simulation? = false
+ * );
  */
 export declare function useContractWriteX(settings: WriteExtendedAsyncParams): {
-    simulateAsyncAndWriteContract: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0]) => Promise<void>;
+    writeContractX: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0], disableSimulation?: boolean) => Promise<void>;
     isPending: boolean;
     errorMessage: string | undefined;
     error: null;
@@ -79,7 +43,7 @@ export declare function useContractWriteX(settings: WriteExtendedAsyncParams): {
     writeContract: import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>;
     writeContractAsync: import("wagmi/query").WriteContractMutateAsync<import("wagmi").Config, void>;
 } | {
-    simulateAsyncAndWriteContract: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0]) => Promise<void>;
+    writeContractX: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0], disableSimulation?: boolean) => Promise<void>;
     isPending: boolean;
     errorMessage: string | undefined;
     error: null;
@@ -223,7 +187,7 @@ export declare function useContractWriteX(settings: WriteExtendedAsyncParams): {
     writeContract: import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>;
     writeContractAsync: import("wagmi/query").WriteContractMutateAsync<import("wagmi").Config, void>;
 } | {
-    simulateAsyncAndWriteContract: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0]) => Promise<void>;
+    writeContractX: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0], disableSimulation?: boolean) => Promise<void>;
     isPending: boolean;
     errorMessage: string | undefined;
     error: import("@wagmi/core").WriteContractErrorType;
@@ -367,7 +331,7 @@ export declare function useContractWriteX(settings: WriteExtendedAsyncParams): {
     writeContract: import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>;
     writeContractAsync: import("wagmi/query").WriteContractMutateAsync<import("wagmi").Config, void>;
 } | {
-    simulateAsyncAndWriteContract: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0]) => Promise<void>;
+    writeContractX: (params: Parameters<import("wagmi/query").WriteContractMutate<import("wagmi").Config, void>>[0], disableSimulation?: boolean) => Promise<void>;
     isPending: boolean;
     errorMessage: string | undefined;
     error: null;

package/dist/hooks/mutations/useHandleTransactionMutationX.d.ts

@@ -11,7 +11,6 @@ export type WriteExtendedAsyncParams = {
     queriesToInvalidate?: (QueryKey | undefined)[];
     /** a predicate to decide which queries to invalidate */
     invalidatePredicate?: (query: Query<unknown, unknown>) => boolean;
-    simulationOverrideAbis?: any;
     disableLogging?: boolean;
     disableWaitingForReceipt?: boolean;
 };

package/dist/hooks/mutations/useSendTransactionX.d.ts

@@ -1,55 +1,33 @@
 import { WriteExtendedAsyncParams } from "./useHandleTransactionMutationX.js";
 import { writeContract } from "wagmi/actions";
 /**
- * Custom hook for sending a transaction using Wagmi.
+ * Custom hook for sending a transaction using Wagmi with optional simulation.
  *
- * This hook provides functionality for sending a transaction using Wagmi, handling the asynchronous nature of the operation, waiting for the transaction receipt, and error handling.
+ * @param {WriteExtendedAsyncParams} [settings] - Settings for handling transaction lifecycle:
+ * @param {boolean} [settings.disableWaitingForReceipt] - Disable waiting for receipt.
+ * @param {boolean} [settings.disableLogging] - Disable logging.
+ * @param {Function} [settings.onSuccess] - Callback on success.
+ * @param {Function} [settings.onError] - Callback on error.
+ * @param {Function} [settings.onSettled] - Callback after settlement.
+ * @param {Array<import('@tanstack/query-core').QueryKey>} [settings.queriesToInvalidate] - Query keys to invalidate after receipt.
+ * @returns {Object} An object containing:
+ *   - sendTransaction: Wagmi's sendTransaction function.
+ *   - sendTransactionX: Wrapped sendTransaction with optional simulation.
+ *   - isPending: Boolean indicating if transaction is in progress.
+ *   - errorMessage: Error message if one occurred.
  *
- * @param {WriteExtendedAsyncParams} [settings] - Optional settings for the write operation.
- * @param {boolean} [settings.disableWaitingForReceipt] - Disables waiting for the transaction receipt.
- * @param {boolean} [settings.disableLogging] - Disables logging the result of the transaction.
- * @param {Function} [settings.onSuccess] - Callback function to be called on successful transaction.
- * @param {Function} [settings.onError] - Callback function to be called on transaction error.
- * @param {Function} [settings.onSettled] - Callback function to be called after the transaction settles (whether success or failure).
- * @param {QueryKey[]} [settings.queriesToInvalidate] - Array of query keys to invalidate after the transaction receives a receipt.
- * @returns {Object} Object containing the following properties:
- * - {boolean} isPending - Indicates whether the transaction is pending.
- * - {string|undefined} errorMessage - The error message, if an error occurred during the transaction.
- * - {Function} sendTransactionAsync - Function to trigger the send transaction mutation.
-
  * @example
- * // In your component:
- * function MyTransactionComponent() {
- *   const { sendTransactionAsync, isPending, errorMessage } = useSendTransactionX({
- *     // use calbacks here in useContractWriteX or in writeContractAsync
- *     onSuccess: (txHash) => console.log("Transaction successful:", txHash),
- *     onError: (error) => console.error("Transaction error:", error),
- *     queriesToInvalidate: [["userBalance"], ["userActivity"]],
- *   });
- *
- *   const handleSend = async () => {
- *     try {
- *       const txHash = await sendTransactionAsync({ transaction params here.. });
- *       console.log("Received txHash:", txHash);
- *     } catch (err) {
- *       console.error("Failed sending transaction:", err);`
- *     }
- *   };
- *
- *   return (
- *     <div>
- *       <button onClick={handleSend} disabled={isPending}>
- *         {isPending ? "Processing..." : "Send Transaction"}
- *       </button>
- *       {errorMessage && <p>Error: {errorMessage}</p>}
- *     </div>
- *   );
- * }
+ * const { sendTransactionX, isPending, errorMessage } = useSendTransactionX({ onSuccess: ..., onError: ... });
+ * await sendTransactionX(
+ *   { to, value, data, account, chain },
+ *   { abi, functionName, args, chain }
+ * );
  */
 export declare function useSendTransactionX(settings?: WriteExtendedAsyncParams): {
     isPending: boolean;
     errorMessage: string | undefined;
-    simulateAsyncAndSendTransaction: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams: Parameters<typeof writeContract>[1]) => Promise<void>;
+    sendTransaction: import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>;
+    sendTransactionX: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams?: Parameters<typeof writeContract>[1]) => Promise<void>;
     error: null;
     status: "idle";
     data: undefined;
@@ -67,7 +45,8 @@ export declare function useSendTransactionX(settings?: WriteExtendedAsyncParams)
 } | {
     isPending: boolean;
     errorMessage: string | undefined;
-    simulateAsyncAndSendTransaction: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams: Parameters<typeof writeContract>[1]) => Promise<void>;
+    sendTransaction: import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>;
+    sendTransactionX: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams?: Parameters<typeof writeContract>[1]) => Promise<void>;
     error: null;
     status: "pending";
     data: undefined;
@@ -85,7 +64,8 @@ export declare function useSendTransactionX(settings?: WriteExtendedAsyncParams)
 } | {
     isPending: boolean;
     errorMessage: string | undefined;
-    simulateAsyncAndSendTransaction: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams: Parameters<typeof writeContract>[1]) => Promise<void>;
+    sendTransaction: import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>;
+    sendTransactionX: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams?: Parameters<typeof writeContract>[1]) => Promise<void>;
     error: import("wagmi/actions").SendTransactionErrorType;
     status: "error";
     data: undefined;
@@ -103,7 +83,8 @@ export declare function useSendTransactionX(settings?: WriteExtendedAsyncParams)
 } | {
     isPending: boolean;
     errorMessage: string | undefined;
-    simulateAsyncAndSendTransaction: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams: Parameters<typeof writeContract>[1]) => Promise<void>;
+    sendTransaction: import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>;
+    sendTransactionX: (params: Parameters<import("wagmi/query").SendTransactionMutate<import("wagmi").Config, void>>[0], simulationParams?: Parameters<typeof writeContract>[1]) => Promise<void>;
     error: null;
     status: "success";
     data: `0x${string}`;