wagmi-extended 0.8.0 → 1.0.0

package/dist/index.esm.js

@@ -1,7 +1,7 @@
 import { useConfig, useWriteContract, useSendTransaction, useAccount } from 'wagmi';
 import { waitForTransactionReceipt } from 'wagmi/actions';
 import { useState, useEffect } from 'react';
-import { ContractFunctionRevertedError, zeroAddress, erc20Abi } from 'viem';
+import { ContractFunctionRevertedError, erc20Abi, maxUint256, zeroAddress } from 'viem';
 import { useQueryClient, useQuery } from '@tanstack/react-query';
 import { readContract } from 'viem/actions';
 import { readContractQueryOptions } from 'wagmi/query';
@@ -71,7 +71,7 @@ const getErrorMapping = () => currentErrorMapping;
  * const message = getParsedError(someError);
  * console.log(message); // Outputs a custom error message or a default error message.
  */
-const getParsedError = (error) => {
+const getParsedErrorX = (error) => {
     var _a, _b, _c, _d;
     const defaultMessage = "An unknown error occurred. Please contact support.";
     let message = defaultMessage;
@@ -108,7 +108,7 @@ function useInvalidateQueries() {
  *
  * @returns {Function} A shared `onSettled` callback for transaction mutations.
  */
-function useHandleTransactionMutation({ settings, }) {
+function useHandleTransactionMutationX({ settings, }) {
     const wagmiConfig = useConfig();
     const { invalidateMany } = useInvalidateQueries();
     const [isPending, setIsPending] = useState(false);
@@ -147,7 +147,7 @@ function useHandleTransactionMutation({ settings, }) {
             return txHash;
         }
         catch (error) {
-            const parsedError = getParsedError(error);
+            const parsedError = getParsedErrorX(error);
             if (!(settings === null || settings === void 0 ? void 0 : settings.disableLogging)) {
                 // 1. log error
                 console.error(`ContractWriteExtended Operation failed with error(parsed): ${parsedError}`, { error }, { args });
@@ -176,7 +176,7 @@ function useHandleTransactionMutation({ settings, }) {
 /**
  * Custom hook for writing to a smart contract using Wagmi.
  *
- * 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.
+ * 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.
@@ -189,9 +189,49 @@ function useHandleTransactionMutation({ settings, }) {
  * - {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.
+ * @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.
+ *
+ * @example
+ * // In your component:
+ * function MyTransactionComponent() {
+ *   const { writeContractAsync, isPending, errorMessage } = useContractWriteX({
+ *     onSuccess: (txHash) => console.log("Transaction successful:", txHash),
+ *     onError: (error) => console.error("Transaction error:", error),
+ *     queriesToInvalidate: [["userBalance"], ["userActivity"]],
+ *   });
+ *
+ *   const handleWrite = async () => {
+ *     try {
+ *       const txHash = await writeContractAsync({ transaction params here.. });
+ *       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>
+ *   );
+ * }
  */
-function useContractWriteExtended(settings) {
-    const { isPending, errorMessage, onMutate, onSettled } = useHandleTransactionMutation({
+function useContractWriteX(settings) {
+    const { isPending, errorMessage, onMutate, onSettled } = useHandleTransactionMutationX({
         settings,
     });
     const { writeContractAsync, ...rest } = useWriteContract({
@@ -213,7 +253,7 @@ function useContractWriteExtended(settings) {
  *
  * 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 {SeamlessWriteAsyncParams} [settings] - Optional settings for the write operation.
+ * @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.
@@ -224,9 +264,37 @@ function useContractWriteExtended(settings) {
  * - {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({
+ *     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>
+ *   );
+ * }
  */
-function useSendTransactionExtended(settings) {
-    const { isPending, errorMessage, onMutate, onSettled } = useHandleTransactionMutation({
+function useSendTransactionX(settings) {
+    const { isPending, errorMessage, onMutate, onSettled } = useHandleTransactionMutationX({
         settings,
     });
     const { sendTransactionAsync, ...rest } = useSendTransaction({
@@ -252,12 +320,210 @@ const queryConfig = {
     },
 };
 
+const fetchAllowance = async (asset, spender, userAddress, config) => {
+    const allowance = await readContract(config, {
+        address: asset,
+        abi: erc20Abi,
+        functionName: "allowance",
+        args: [userAddress, spender],
+    });
+    if (allowance == null) {
+        throw new Error("Failed to fetch token data or allowance");
+    }
+    return allowance;
+};
+
+const HookFetchAssetAllowanceQK = (asset, spender, userAddress) => ["HookFetchAllowance", asset, spender, userAddress];
+/**
+ * Custom hook for fetching asset allowance.
+ *
+ * @param {Address} asset - The address of the ERC20 token contract.
+ * @param {Address} spender - The address of the spender to check allowance for.
+ *
+ *
+ * @example
+ * // In your component:
+ * function AllowanceDisplay() {
+ *   const { data: allowance, isLoading, error } = useFetchAssetAllowanceX({
+ *     asset: "0xTokenAddressExample",
+ *     spender: "0xSpenderAddressExample",
+ *   });
+ *
+ *   if (isLoading) return <div>Loading allowance...</div>;
+ *   if (error) return <div>Error loading allowance</div>;
+ *
+ *   return (
+ *     <div>
+ *       Current Allowance: {allowance}
+ *     </div>
+ *   );
+ * }
+ */
+const useFetchAssetAllowanceX = ({ asset, spender, }) => {
+    const config = useConfig();
+    const { address: userAddress } = useAccount();
+    const { data, ...rest } = useQuery({
+        queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress),
+        queryFn: () => fetchAllowance(asset, spender, userAddress, config),
+        enabled: Boolean(asset) && Boolean(spender) && Boolean(userAddress),
+        ...queryConfig.sensitiveDataQueryConfig,
+    });
+    return {
+        ...rest,
+        data,
+        queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress),
+    };
+};
+
+/**
+ * Custom hook for approving ERC20 token transfers.
+ *
+ * This hook provides functionality for approving ERC20 token transfers, checking the current allowance, and handling the approval transaction using Wagmi.
+ *
+ * @param {Address} tokenAddress - The address of the ERC20 token contract (the transfer from).
+ * @param {Address} spenderAddress - The address of the spender to approve the transfer to.
+ * @param {bigint} [amount=BigInt(0)] - The amount to approve for transfer. Defaults to undefined.
+ * @param {boolean} [approveMax=false] - Indicates whether to approve the maximum amount or a specific amount.
+ * @returns {Object} Object containing the following properties:
+ * - {boolean} isApproved - Indicates whether the spender is already approved to transfer the specified amount of tokens.
+ * - {boolean} isApproving - Indicates whether an approval transaction is currently pending.
+ * - {Function} approveAsync - Function to trigger the approval transaction.
+ *
+ * @example
+ * // In your component:
+ * function ApproveTokenButton(amountToApprove) {
+ *   const tokenAddress = "0xTokenAddressExample";
+ *   const spenderAddress = "0xSpenderAddressExample";
+ *
+ *   const { isApproved, isApproving, justApproved, approveAsync } = useERC20ApproveX(
+ *     tokenAddress,
+ *     spenderAddress,
+ *     parseUnits(amountToApprove.toString(), 18),
+ *   );
+ *
+ *   return (
+ *     <button onClick={approveAsync} disabled={isApproving || isApproved}>
+ *       {isApproving ? "Approving..." : isApproved ? "Approved" : "Approve Token"}
+ *     </button>
+ *   );
+ * }
+ */
+const useERC20ApproveX = (tokenAddress, spenderAddress, amount, approveMax) => {
+    const [isApproved, setIsApproved] = useState(false);
+    const [justApproved, setJustApproved] = useState(false);
+    const { data: allowance, queryKey: allowanceKQ } = useFetchAssetAllowanceX({
+        asset: tokenAddress,
+        spender: spenderAddress,
+    });
+    const { writeContractAsync: approveTokenAsync, isPending } = useContractWriteX({
+        queriesToInvalidate: [allowanceKQ],
+    });
+    useEffect(() => {
+        if (amount == null) {
+            setIsApproved(false);
+        }
+        else if (allowance && allowance >= amount) {
+            setIsApproved(true);
+        }
+        else {
+            setIsApproved(false);
+        }
+    }, [allowance, amount]);
+    const approveAsync = async () => {
+        const amountToApprove = approveMax ? maxUint256 : amount;
+        try {
+            if (!spenderAddress) {
+                throw new Error("spenderAddress is undefined!");
+            }
+            if (!tokenAddress) {
+                throw new Error("tokenAddress is undefined!");
+            }
+            if (amountToApprove == null) {
+                throw new Error("amountToApprove is undefined!");
+            }
+            await approveTokenAsync({
+                address: tokenAddress,
+                abi: erc20Abi,
+                functionName: "approve",
+                args: [spenderAddress, amountToApprove],
+            }, {
+                onSuccess: () => {
+                    setJustApproved(true);
+                },
+            });
+        }
+        catch (e) {
+            console.error("Error approving token:", e);
+            throw e;
+        }
+    };
+    return {
+        isApproved,
+        isApproving: isPending,
+        justApproved,
+        approveAsync,
+    };
+};
+
+// You can adjust the type for wagmiConfig to match your needs.
+let defaultQueryClient = null;
+let defaultWagmiConfig = null;
+/**
+ * Sets the default configuration values.
+ *
+ * @param queryClient - The default QueryClient instance.
+ * @param wagmiConfig - The default Wagmi configuration.
+ * @example
+ * //In your application initialization (e.g., index.tsx or App.tsx):
+ * import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+ * import { wagmiConfig } from "/path/to/wagmi-config";
+ * import { setDefaults } from "wagmi-extended";
+ *
+ * const queryClient = new QueryClient();
+ *
+ * //Set defaults for the extended library functions.
+ * setDefaults(queryClient, wagmiConfig);
+ *
+ * //Now helper functions like fetchTokenX can use these defaults if no explicit parameters are provided.
+ */
+function setDefaults(queryClient, wagmiConfig) {
+    defaultQueryClient = queryClient;
+    defaultWagmiConfig = wagmiConfig;
+}
+/**
+ * Retrieves the currently set default configurations.
+ *
+ * @throws Will throw an error if defaults are not initialized.
+ * @returns An object containing the default queryClient and wagmiConfig.
+ *
+ * @example
+ * // Usage in a helper function:
+ * import { getDefaults } from "wagmi-extended";
+ *
+ * function exampleFunction() {
+ *   const { queryClient, wagmiConfig } = getDefaults();
+ *   // Use queryClient and wagmiConfig as needed...
+ * }
+ */
+function getDefaults() {
+    if (!defaultQueryClient || !defaultWagmiConfig) {
+        throw new Error("Default configuration not set. Please call setDefaults() first.");
+    }
+    return { queryClient: defaultQueryClient, wagmiConfig: defaultWagmiConfig };
+}
+
 const EthTokenData = {
     symbol: "ETH",
     decimals: 18,
     name: "Ethereum",
 };
-async function fetchDecimals(token, queryClient, wagmiConfig) {
+async function fetchDecimalsX(token, queryClient, wagmiConfig) {
+    if (!queryClient || !wagmiConfig) {
+        ({ queryClient, wagmiConfig } = getDefaults());
+    }
+    if (!queryClient || !wagmiConfig) {
+        throw new Error("Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()");
+    }
     if (token === zeroAddress)
         return EthTokenData.decimals;
     const decimals = await queryClient.fetchQuery({
@@ -270,7 +536,13 @@ async function fetchDecimals(token, queryClient, wagmiConfig) {
     });
     return decimals;
 }
-async function fetchSymbol(token, queryClient, wagmiConfig) {
+async function fetchSymbolX(token, queryClient, wagmiConfig) {
+    if (!queryClient || !wagmiConfig) {
+        ({ queryClient, wagmiConfig } = getDefaults());
+    }
+    if (!queryClient || !wagmiConfig) {
+        throw new Error("Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()");
+    }
     if (token === zeroAddress)
         return EthTokenData.symbol;
     const symbol = await queryClient.fetchQuery({
@@ -283,9 +555,15 @@ async function fetchSymbol(token, queryClient, wagmiConfig) {
     });
     return symbol;
 }
-async function fetchName(token, queryClient, wagmiConfig) {
+async function fetchNameX(token, queryClient, wagmiConfig) {
     if (token === zeroAddress)
         return EthTokenData.name;
+    if (!queryClient || !wagmiConfig) {
+        ({ queryClient, wagmiConfig } = getDefaults());
+    }
+    if (!queryClient || !wagmiConfig) {
+        throw new Error("Could not find queryClient or wagmiConfig, either pass them as arguments or set them using setDefaults()");
+    }
     const name = await queryClient.fetchQuery({
         ...readContractQueryOptions(wagmiConfig, {
             address: token,
@@ -307,13 +585,13 @@ async function fetchName(token, queryClient, wagmiConfig) {
  * @returns A `Token` object containing the symbol, decimals.
  * @throws Will throw an error if symbol or decimals cannot be fetched.
  */
-async function fetchToken(token, queryClient, wagmiConfig) {
+async function fetchTokenX(token, queryClient, wagmiConfig) {
     const [symbol, decimals, name] = await Promise.all([
-        fetchSymbol(token, queryClient, wagmiConfig),
-        fetchDecimals(token, queryClient, wagmiConfig),
-        fetchName(token, queryClient, wagmiConfig),
+        fetchSymbolX(token, queryClient, wagmiConfig),
+        fetchDecimalsX(token, queryClient, wagmiConfig),
+        fetchNameX(token, queryClient, wagmiConfig),
     ]);
-    if (!symbol || !decimals) {
+    if (!symbol || !decimals || !name) {
         throw new Error("Failed to fetch token data");
     }
     return {
@@ -323,138 +601,63 @@ async function fetchToken(token, queryClient, wagmiConfig) {
     };
 }
 
-const fetchAllowance = async (asset, spender, userAddress, queryClient, config) => {
-    const [tokenData, allowance] = await Promise.all([
-        fetchToken(asset, queryClient, config),
-        readContract(config, {
-            address: asset,
-            abi: erc20Abi,
-            functionName: "allowance",
-            args: [userAddress, spender],
-        }),
-    ]);
-    if (!tokenData || allowance == null) {
-        throw new Error("Failed to fetch token data or allowance");
-    }
-    return {
-        bigIntValue: allowance,
-        decimals: tokenData.decimals,
-        symbol: tokenData.symbol,
-    };
-};
-const HookFetchAssetAllowanceQK = (asset, spender, userAddress, config, queryClient) => [
-    "hookFetchAllowance",
+/**
+ * Returns a query key for fetching token data.
+ *
+ * @param {Address | undefined} asset - The token address.
+ * @returns {Array} A unique query key for the token fetch.
+ *
+ * @example
+ * const queryKey = HookFetchTokenQK("0x123...");
+ */
+const HookFetchTokenQK = (asset) => [
+    "HookTokenWagmiExtended",
     asset,
-    spender,
-    userAddress,
-    config,
-    queryClient,
 ];
 /**
- * Custom hook for fetching asset allowance.
+ * Custom hook for fetching token metadata using extended Wagmi functionality.
  *
- * @param {Address} asset - The address of the ERC20 token contract.
- * @param {Address} spender - The address of the spender to check allowance for.
+ * This hook leverages React Query for data fetching and caching.
+ * It retrieves token metadata (such as symbol, decimals, name, etc.) for a given token address.
+ *
+ * @param {Address} [asset] - The token address.
+ * @returns {Object} An object with the following properties:
+ *   - `data`: The token data (or undefined if not loaded).
+ *   - `isLoading`: Boolean indicating if the data is loading.
+ *   - `error`: Any error encountered during the fetch.
+ *   - `queryKey`: The unique key used for the query.
+ *
+ * @example
+ * // In your component:
+ * function MyTokenComponent() {
+ *   const { data, isLoading, error, queryKey } = useTokenX("0x123456...");
+ *
+ *   if (isLoading) return <div>Loading token data...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return (
+ *     <div>
+ *       <p>Token Symbol: {data.symbol}</p>
+ *       <p>Decimals: {data.decimals}</p>
+ *       <p>Name: {data.name}</p>
+ *     </div>
+ *   );
+ * }
  */
-const useFetchAssetAllowance = ({ asset, spender, }) => {
-    const config = useConfig();
+const useTokenX = (asset) => {
     const queryClient = useQueryClient();
-    const { address: userAddress } = useAccount();
+    const config = useConfig();
     const { data, ...rest } = useQuery({
-        queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress, config, queryClient),
-        queryFn: () => fetchAllowance(asset, spender, userAddress, queryClient, config),
-        enabled: !!asset && !!spender && !!userAddress,
-        ...queryConfig.sensitiveDataQueryConfig,
+        queryKey: HookFetchTokenQK(asset),
+        queryFn: () => fetchTokenX(asset, queryClient, config),
+        enabled: Boolean(asset),
     });
     return {
         ...rest,
         data,
-        queryKey: HookFetchAssetAllowanceQK(asset, spender, userAddress, config, queryClient),
-    };
-};
-
-/**
- * Helper function to determine human readable state of approve.
- *
- * @param {boolean} isApproved - Indicates if the approval is already done.
- * @param {boolean} justApproved - Indicates if the user has just approved.
- * @return {string} - The appropriate button text.
- */
-function getApproveState(isApproved, justApproved) {
-    if (isApproved) {
-        return justApproved ? "Approve Confirmed" : "Approved";
-    }
-    return "Approve";
-}
-/**
- * Custom hook for approving ERC20 token transfers.
- *
- * This hook provides functionality for approving ERC20 token transfers, checking the current allowance, and handling the approval transaction using Wagmi.
- *
- * @param {Address} tokenAddress - The address of the ERC20 token contract.
- * @param {Address} spenderAddress - The address of the spender to approve the transfer to.
- * @param {bigint} [amount=BigInt(0)] - The amount of tokens to approve for transfer. Defaults to 0.
- * @returns {Object} Object containing the following properties:
- * - {boolean} isApproved - Indicates whether the spender is already approved to transfer the specified amount of tokens.
- * - {boolean} isApproving - Indicates whether an approval transaction is currently pending.
- * - {Function} approveAsync - Function to trigger the approval transaction.
- */
-const useERC20Approve = (tokenAddress, spenderAddress, amount) => {
-    const [isApproved, setIsApproved] = useState(false);
-    const [justApproved, setJustApproved] = useState(false);
-    const { data: allowance, queryKey } = useFetchAssetAllowance({
-        asset: tokenAddress,
-        spender: spenderAddress,
-    });
-    const { writeContractAsync: approveTokenAsync, isPending } = useContractWriteExtended({
-        queriesToInvalidate: [queryKey],
-    });
-    useEffect(() => {
-        if (amount == null) {
-            setIsApproved(false);
-        }
-        else if (allowance && allowance.bigIntValue >= amount) {
-            setIsApproved(true);
-        }
-        else {
-            setIsApproved(false);
-        }
-    }, [allowance, amount]);
-    const approveAsync = async () => {
-        const amountToApprove = amount;
-        if (!spenderAddress) {
-            throw new Error("spenderAddress is undefined!");
-        }
-        if (!tokenAddress) {
-            throw new Error("tokenAddress is undefined!");
-        }
-        if (amountToApprove == null) {
-            throw new Error("amountToApprove is undefined!");
-        }
-        try {
-            await approveTokenAsync({
-                address: tokenAddress,
-                abi: erc20Abi,
-                functionName: "approve",
-                args: [spenderAddress, amountToApprove],
-            }, {
-                onSuccess: () => {
-                    setJustApproved(true);
-                },
-            });
-        }
-        catch (e) {
-            console.error("Error approving token:", e);
-            throw e;
-        }
-    };
-    return {
-        isApproved,
-        isApproving: isPending,
-        justApproved,
-        approveAsync,
+        queryKey: HookFetchTokenQK(asset),
     };
 };
 
-export { getApproveState, getErrorMapping, getParsedError, resetErrorMapping, setErrorMapping, useContractWriteExtended, useERC20Approve, useSendTransactionExtended };
+export { EthTokenData, HookFetchTokenQK, fetchDecimalsX, fetchNameX, fetchSymbolX, fetchTokenX, getDefaults, getErrorMapping, getParsedErrorX, resetErrorMapping, setDefaults, setErrorMapping, useContractWriteX, useERC20ApproveX, useFetchAssetAllowanceX, useSendTransactionX, useTokenX };
 //# sourceMappingURL=index.esm.js.map