wagmi-extended 0.5.0 → 1.0.0

package/dist/index.cjs.js

@@ -2,23 +2,11 @@
 
 var wagmi = require('wagmi');
 var actions = require('wagmi/actions');
-var reactQuery = require('@tanstack/react-query');
 var react = require('react');
 var viem = require('viem');
-
-/**
- * Hook to invalidate multiple queries in the React Query cache.
- *
- * @returns An object with the invalidateMany function.
- */
-function useInvalidateQueries() {
-    const queryClient = reactQuery.useQueryClient();
-    const invalidateMany = async (queries) => {
-        const promises = queries.map((queryKey) => queryClient.invalidateQueries({ queryKey }));
-        await Promise.all(promises);
-    };
-    return { invalidateMany };
-}
+var reactQuery = require('@tanstack/react-query');
+var actions$1 = require('viem/actions');
+var query = require('wagmi/query');
 
 /**
  * Default error mapping that contains a set of error identifiers mapped to user-friendly error messages.
@@ -85,7 +73,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;
@@ -103,12 +91,26 @@ const getParsedError = (error) => {
     return message;
 };
 
+/**
+ * Hook to invalidate multiple queries in the React Query cache.
+ *
+ * @returns An object with the invalidateMany function.
+ */
+function useInvalidateQueries() {
+    const queryClient = reactQuery.useQueryClient();
+    const invalidateMany = async (queries) => {
+        const promises = queries.map((queryKey) => queryClient.invalidateQueries({ queryKey }));
+        await Promise.all(promises);
+    };
+    return { invalidateMany };
+}
+
 /**
  * Custom hook to handle transaction mutations.
  *
  * @returns {Function} A shared `onSettled` callback for transaction mutations.
  */
-function useHandleTransactionMutation({ settings, }) {
+function useHandleTransactionMutationX({ settings, }) {
     const wagmiConfig = wagmi.useConfig();
     const { invalidateMany } = useInvalidateQueries();
     const [isPending, setIsPending] = react.useState(false);
@@ -147,7 +149,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 +178,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 +191,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 } = wagmi.useWriteContract({
@@ -213,7 +255,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 +266,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 } = wagmi.useSendTransaction({
@@ -243,10 +313,369 @@ function useSendTransactionExtended(settings) {
     };
 }
 
+const queryConfig = {
+    metadataQueryConfig: {
+        staleTime: Infinity,
+    },
+    sensitiveDataQueryConfig: {
+        staleTime: 60000,
+    },
+};
+
+const fetchAllowance = async (asset, spender, userAddress, config) => {
+    const allowance = await actions$1.readContract(config, {
+        address: asset,
+        abi: viem.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 = wagmi.useConfig();
+    const { address: userAddress } = wagmi.useAccount();
+    const { data, ...rest } = reactQuery.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] = react.useState(false);
+    const [justApproved, setJustApproved] = react.useState(false);
+    const { data: allowance, queryKey: allowanceKQ } = useFetchAssetAllowanceX({
+        asset: tokenAddress,
+        spender: spenderAddress,
+    });
+    const { writeContractAsync: approveTokenAsync, isPending } = useContractWriteX({
+        queriesToInvalidate: [allowanceKQ],
+    });
+    react.useEffect(() => {
+        if (amount == null) {
+            setIsApproved(false);
+        }
+        else if (allowance && allowance >= amount) {
+            setIsApproved(true);
+        }
+        else {
+            setIsApproved(false);
+        }
+    }, [allowance, amount]);
+    const approveAsync = async () => {
+        const amountToApprove = approveMax ? viem.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: viem.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 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 === viem.zeroAddress)
+        return EthTokenData.decimals;
+    const decimals = await queryClient.fetchQuery({
+        ...query.readContractQueryOptions(wagmiConfig, {
+            address: token,
+            abi: viem.erc20Abi,
+            functionName: "decimals",
+        }),
+        ...queryConfig.metadataQueryConfig,
+    });
+    return decimals;
+}
+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 === viem.zeroAddress)
+        return EthTokenData.symbol;
+    const symbol = await queryClient.fetchQuery({
+        ...query.readContractQueryOptions(wagmiConfig, {
+            address: token,
+            abi: viem.erc20Abi,
+            functionName: "symbol",
+        }),
+        ...queryConfig.metadataQueryConfig,
+    });
+    return symbol;
+}
+async function fetchNameX(token, queryClient, wagmiConfig) {
+    if (token === viem.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({
+        ...query.readContractQueryOptions(wagmiConfig, {
+            address: token,
+            abi: viem.erc20Abi,
+            functionName: "name",
+        }),
+        ...queryConfig.metadataQueryConfig,
+    });
+    return name;
+}
+/**
+ * Fetches the token metadata (symbol, decimals) for the given token address.
+ * Internally calls:
+ *  - `fetchSymbol(token)`   to retrieve the token symbol,
+ *  - `fetchDecimals(token)` to retrieve the token decimals
+ *  - `fetchName(token)`     to retrieve the token name
+ *
+ * @param token - The address of the token.
+ * @returns A `Token` object containing the symbol, decimals.
+ * @throws Will throw an error if symbol or decimals cannot be fetched.
+ */
+async function fetchTokenX(token, queryClient, wagmiConfig) {
+    const [symbol, decimals, name] = await Promise.all([
+        fetchSymbolX(token, queryClient, wagmiConfig),
+        fetchDecimalsX(token, queryClient, wagmiConfig),
+        fetchNameX(token, queryClient, wagmiConfig),
+    ]);
+    if (!symbol || !decimals || !name) {
+        throw new Error("Failed to fetch token data");
+    }
+    return {
+        symbol,
+        decimals,
+        name,
+    };
+}
+
+/**
+ * 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,
+];
+/**
+ * Custom hook for fetching token metadata using extended Wagmi functionality.
+ *
+ * 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 useTokenX = (asset) => {
+    const queryClient = reactQuery.useQueryClient();
+    const config = wagmi.useConfig();
+    const { data, ...rest } = reactQuery.useQuery({
+        queryKey: HookFetchTokenQK(asset),
+        queryFn: () => fetchTokenX(asset, queryClient, config),
+        enabled: Boolean(asset),
+    });
+    return {
+        ...rest,
+        data,
+        queryKey: HookFetchTokenQK(asset),
+    };
+};
+
+exports.EthTokenData = EthTokenData;
+exports.HookFetchTokenQK = HookFetchTokenQK;
+exports.fetchDecimalsX = fetchDecimalsX;
+exports.fetchNameX = fetchNameX;
+exports.fetchSymbolX = fetchSymbolX;
+exports.fetchTokenX = fetchTokenX;
+exports.getDefaults = getDefaults;
 exports.getErrorMapping = getErrorMapping;
-exports.getParsedError = getParsedError;
+exports.getParsedErrorX = getParsedErrorX;
 exports.resetErrorMapping = resetErrorMapping;
+exports.setDefaults = setDefaults;
 exports.setErrorMapping = setErrorMapping;
-exports.useContractWriteExtended = useContractWriteExtended;
-exports.useSendTransactionExtended = useSendTransactionExtended;
+exports.useContractWriteX = useContractWriteX;
+exports.useERC20ApproveX = useERC20ApproveX;
+exports.useFetchAssetAllowanceX = useFetchAssetAllowanceX;
+exports.useSendTransactionX = useSendTransactionX;
+exports.useTokenX = useTokenX;
 //# sourceMappingURL=index.cjs.js.map