refactor(react, vue): dedicated spendable balances function (#793)

Author: tien

.changeset/evil-pears-judge.md

@@ -0,0 +1,6 @@
+---
+"@reactive-dot/react": minor
+"@reactive-dot/vue": minor
+---
+
+Added dedicated `useSpendableBalances` hook/composable.

apps/docs/react/guides/number-utility.md

@@ -80,16 +80,16 @@ const amountFromPlanck = useNativeTokenAmountFromPlanck();
 
 ## Spendable balance
 
-The [`useSpendableBalance`](/api/react/function/useSpendableBalance) hook can be used to get the [spendable balance](https://wiki.polkadot.network/docs/learn-account-balances) of an account(s).
+The [`useSpendableBalance`](/api/react/function/useSpendableBalance) & [`useSpendableBalances`](/api/react/function/useSpendableBalances) hooks can be used to get the [spendable balance](https://wiki.polkadot.network/docs/learn-account-balances) of an account(s).
 
 ```ts
-import { useSpendableBalance } from "@reactive-dot/react";
+import { useSpendableBalance, useSpendableBalances } from "@reactive-dot/react";
 
 const spendableBalance = useSpendableBalance(ACCOUNT_ADDRESS);
 
 console.log(spendableBalance.toLocaleString("en-NZ")); // DOT 10.00
 
-const spendableBalances = useSpendableBalance([
+const spendableBalances = useSpendableBalances([
   ACCOUNT_ADDRESS_1,
   ACCOUNT_ADDRESS_2,
   ACCOUNT_ADDRESS_3,

apps/docs/vue/guides/number-utility.md

@@ -69,17 +69,17 @@ console.log(nativeToken.value.amountFromNumber(1).toLocaleString("en-NZ")); // D
 
 ## Spendable balance
 
-The [`useSpendableBalance`](/api/vue/function/useSpendableBalance) composable can be used to get the [spendable balance](https://wiki.polkadot.network/docs/learn-account-balances) of an account(s).
+The [`useSpendableBalance`](/api/react/function/useSpendableBalance) & [`useSpendableBalances`](/api/react/function/useSpendableBalances) composable can be used to get the [spendable balance](https://wiki.polkadot.network/docs/learn-account-balances) of an account(s).
 
 ```vue
 <script setup lang="ts">
-import { useSpendableBalance } from "@reactive-dot/vue";
+import { useSpendableBalance, useSpendableBalances } from "@reactive-dot/vue";
 
 const { data: spendableBalance } = await useSpendableBalance(ACCOUNT_ADDRESS);
 
 console.log(spendableBalance.toLocaleString("en-NZ")); // DOT 10.00
 
-const { data: spendableBalances } = await useSpendableBalance([
+const { data: spendableBalances } = await useSpendableBalances([
   ACCOUNT_ADDRESS_1,
   ACCOUNT_ADDRESS_2,
   ACCOUNT_ADDRESS_3,

packages/react/src/hooks/use-balance.test.ts

@@ -1,5 +1,5 @@
 import { DenominatedNumber } from "../../../utils/build/denominated-number.js";
-import { useSpendableBalance } from "./use-balance.js";
+import { useSpendableBalance, useSpendableBalances } from "./use-balance.js";
 import { useNativeTokenAmountFromPlanck } from "./use-native-token-amount.js";
 import { useLazyLoadQuery } from "./use-query.js";
 import { idle, Query } from "@reactive-dot/core";
@@ -77,7 +77,7 @@ it("should return spendable balance for single address", () => {
 
 it("should return spendable balances array for multiple addresses", () => {
   const { result } = renderHook(() =>
-    useSpendableBalance([
+    useSpendableBalances([
       "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
       "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
     ]),
@@ -93,7 +93,7 @@ it("should return spendable balances array for multiple addresses", () => {
 
 it("should return spendable balances array for an array of one address", () => {
   const { result } = renderHook(() =>
-    useSpendableBalance(["5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"]),
+    useSpendableBalances(["5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"]),
   );
 
   expect(result.current).toEqual(

packages/react/src/hooks/use-balance.ts

@@ -38,6 +38,7 @@ export function useSpendableBalance(
 /**
  * Hook for getting accounts’ spendable balances.
  *
+ * @deprecated Use {@link useSpendableBalances} instead.
  * @param addresses  - The account-addresses
  * @param options - Additional options
  * @returns The accounts’ spendable balances
@@ -89,3 +90,17 @@ export function useSpendableBalance(
 
   return Array.isArray(addressOrAddresses) ? balances : balances[0]!;
 }
+
+/**
+ * Hook for getting accounts’ spendable balances.
+ *
+ * @param addresses  - The account-addresses
+ * @param options - Additional options
+ * @returns The accounts’ spendable balances
+ */
+export function useSpendableBalances(
+  addresses: SS58String[],
+  options?: Options,
+) {
+  return useSpendableBalance(addresses, options);
+}

packages/react/src/index.test.ts

@@ -11,6 +11,7 @@ it("should match inline snapshot", () =>
       "SignerProvider",
       "useAccounts",
       "useSpendableBalance",
+      "useSpendableBalances",
       "useBlock",
       "useChainId",
       "useChainIds",

packages/react/src/index.ts

@@ -6,7 +6,10 @@ export { ReactiveDotProvider } from "./contexts/provider.js";
 export { QueryOptionsProvider } from "./contexts/query-options.js";
 export { SignerProvider } from "./contexts/signer.js";
 export { useAccounts } from "./hooks/use-accounts.js";
-export { useSpendableBalance } from "./hooks/use-balance.js";
+export {
+  useSpendableBalance,
+  useSpendableBalances,
+} from "./hooks/use-balance.js";
 export { useBlock } from "./hooks/use-block.js";
 export { useChainId, useChainIds } from "./hooks/use-chain-id.js";
 export { useChainSpecData } from "./hooks/use-chain-spec-data.js";

packages/vue/src/composables/use-balance.test.ts

@@ -1,7 +1,7 @@
 import { DenominatedNumber } from "../../../utils/build/denominated-number.js";
 import { chainIdKey } from "../keys.js";
 import { withSetup } from "../test-utils.js";
-import { useSpendableBalance } from "./use-balance.js";
+import { useSpendableBalance, useSpendableBalances } from "./use-balance.js";
 import { useNativeTokenPromise } from "./use-native-token.js";
 import { useQueryObservable } from "./use-query.js";
 import { Query } from "@reactive-dot/core";
@@ -82,7 +82,7 @@ it("should return spendable balance for single address", async () => {
 it("should return spendable balances array for multiple addresses", async () => {
   const { result } = withSetup(
     () =>
-      useSpendableBalance([
+      useSpendableBalances([
         "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
         "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty",
       ]),
@@ -100,7 +100,9 @@ it("should return spendable balances array for multiple addresses", async () =>
 it("should return spendable balances array for an array of one address", async () => {
   const { result } = withSetup(
     () =>
-      useSpendableBalance(["5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY"]),
+      useSpendableBalances([
+        "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY",
+      ]),
     { [chainIdKey]: "test-chain-id" },
   );
 

packages/vue/src/composables/use-balance.ts

@@ -45,6 +45,7 @@ export function useSpendableBalance(
 /**
  * Composable for getting accounts’ spendable balances.
  *
+ * @deprecated Use {@link useSpendableBalances} instead.
  * @param addresses  - The account-addresses
  * @param options - Additional options
  * @returns The accounts’ spendable balances
@@ -121,3 +122,17 @@ export function useSpendableBalance(
     ),
   );
 }
+
+/**
+ * Composable for getting accounts’ spendable balances.
+ *
+ * @param addresses  - The account-addresses
+ * @param options - Additional options
+ * @returns The accounts’ spendable balances
+ */
+export function useSpendableBalances(
+  addresses: MaybeRefOrGetter<SS58String[]>,
+  options?: Options,
+) {
+  return useSpendableBalance(addresses, options);
+}

packages/vue/src/index.test.ts

@@ -6,6 +6,7 @@ it("should match inline snapshot", () =>
     [
       "useAccounts",
       "useSpendableBalance",
+      "useSpendableBalances",
       "useBlock",
       "useChainId",
       "useChainIds",