feat!: implement pagination for Account methods

.changeset/three-shoes-drum.md

@@ -0,0 +1,5 @@
+---
+"@fuel-ts/account": minor
+---
+
+feat!: implement pagination for `Account` methods

apps/docs-snippets/src/guide/introduction/getting-started.test.ts

@@ -42,7 +42,7 @@ describe('Getting started', () => {
     const wallet = Wallet.fromPrivateKey(PRIVATE_KEY, provider);
 
     // Perform a balance check.
-    const balances = await wallet.getBalances();
+    const { balances } = await wallet.getBalances();
     // [{ assetId: '0x..', amount: bn(..) }, ..]
     // #endregion connecting-to-the-testnet
 

apps/docs-snippets/src/guide/provider/pagination.test.ts

@@ -0,0 +1,106 @@
+import type { GqlPageInfo } from '@fuel-ts/account/dist/providers/__generated__/operations';
+import type { CursorPaginationArgs } from 'fuels';
+import { FUEL_NETWORK_URL, Provider, Wallet } from 'fuels';
+
+/**
+ * @group node
+ */
+describe('querying the chain', () => {
+  it('pagination snippet test 1', () => {
+    // #region pagination-1
+    const paginationArgs: CursorPaginationArgs = {
+      after: 'cursor',
+      first: 10,
+      before: 'cursor',
+      last: 10,
+    };
+    // #endregion pagination-1
+
+    // #region pagination-2
+    const pageInfo: GqlPageInfo = {
+      endCursor: 'cursor',
+      hasNextPage: true,
+      startCursor: 'cursor',
+      hasPreviousPage: true,
+    };
+    // #endregion pagination-2
+
+    expect(paginationArgs).toBeDefined();
+    expect(pageInfo).toBeDefined();
+  });
+
+  it('pagination snippet test 2', async () => {
+    // #region pagination-3
+    // #import { Provider, CursorPaginationArgs, FUEL_NETWORK_URL, Wallet };
+
+    const provider = await Provider.create(FUEL_NETWORK_URL);
+    const baseAssetId = provider.getBaseAssetId();
+    const myWallet = Wallet.generate({ provider });
+
+    let paginationArgs: CursorPaginationArgs = {
+      first: 10, // It will return only the first 10 coins
+    };
+
+    const { coins, pageInfo } = await provider.getCoins(
+      myWallet.address,
+      baseAssetId,
+      paginationArgs
+    );
+
+    if (pageInfo.hasNextPage) {
+      paginationArgs = {
+        after: pageInfo.endCursor,
+        first: 10,
+      };
+      // The coins array will include the next 10 coins after the last one in the previous array
+      await provider.getCoins(myWallet.address, baseAssetId, paginationArgs);
+    }
+    // #endregion pagination-3
+
+    // #region pagination-4
+    if (pageInfo.hasPreviousPage) {
+      paginationArgs = {
+        before: pageInfo.startCursor,
+        last: 10,
+      };
+
+      // It will includes the previous 10 coins before the first one in the previous array
+      await provider.getCoins(myWallet.address, baseAssetId, paginationArgs);
+    }
+    // #endregion pagination-4
+
+    expect(paginationArgs).toBeDefined();
+    expect(coins).toBeDefined();
+    expect(pageInfo).toBeDefined();
+  });
+
+  it('pagination snippet test 3', () => {
+    // #region pagination-5
+    const paginationArgs = { after: 'cursor', first: 10 };
+    // #endregion pagination-5
+
+    expect(paginationArgs).toBeDefined();
+  });
+  it('pagination snippet test 4', () => {
+    // #region pagination-6
+    const paginationArgs = { before: 'cursor', last: 10 };
+    // #endregion pagination-6
+
+    expect(paginationArgs).toBeDefined();
+  });
+
+  it('pagination snippet test 5', async () => {
+    // #region pagination-7
+    // #import { Provider, FUEL_NETWORK_URL, Wallet };
+
+    const provider = await Provider.create(FUEL_NETWORK_URL);
+    const myWallet = Wallet.generate({ provider });
+
+    // It will return the first 100 coins of the base asset
+    const { coins, pageInfo } = await provider.getCoins(myWallet.address);
+    // #endregion pagination-7
+
+    expect(coins).toBeDefined();
+    expect(pageInfo).toBeDefined();
+  });
+});

apps/docs-snippets/src/guide/provider/provider.test.ts

@@ -34,7 +34,7 @@ describe('Provider', () => {
     const wallet = WalletUnlocked.generate({ provider });
 
     // Get the balances of the wallet (this will be empty until we have assets)
-    const balances = await wallet.getBalances();
+    const { balances } = await wallet.getBalances();
     // []
     // #endregion provider-definition
 

apps/docs-snippets/src/guide/provider/querying-the-chain.test.ts

@@ -1,13 +1,14 @@
-import { FUEL_NETWORK_URL, Provider, ScriptTransactionRequest, bn } from 'fuels';
+import { FUEL_NETWORK_URL, Provider, ScriptTransactionRequest } from 'fuels';
 import { generateTestWallet } from 'fuels/test-utils';
 
 /**
  * @group node
  */
 describe('querying the chain', () => {
   it('query coins', async () => {
-    // #region wallet-query
+    // #region get-coins-1
     // #import { Provider, FUEL_NETWORK_URL, generateTestWallet };
+
     const provider = await Provider.create(FUEL_NETWORK_URL);
     const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
     const baseAssetId = provider.getBaseAssetId();
@@ -17,40 +18,33 @@ describe('querying the chain', () => {
       [100, assetIdA],
     ]);
 
-    // get single coin
-    const coin = await wallet.getCoins(baseAssetId);
-    // [{ amount: bn(42), assetId: baseAssetId }]
+    // fetches up to 100 coins from baseAssetId
+    const { coins, pageInfo } = await provider.getCoins(wallet.address, baseAssetId);
+    // [
+    //   { amount: bn(42), assetId: baseAssetId },
+    //   ...
+    // ]
 
-    // get all coins
-    const coins = await wallet.getCoins();
+    // fetches up to 100 coins from all assets
+    await provider.getCoins(wallet.address);
     // [
     //   { amount: bn(42), assetId: baseAssetId }
     //   { amount: bn(100), assetId: assetIdA }
+    //   ...
     // ]
-    // #endregion wallet-query
-
-    expect(coin.length).toEqual(1);
-    expect(coin).toEqual([
-      expect.objectContaining({
-        assetId: baseAssetId,
-        amount: bn(42),
-      }),
-    ]);
-    expect(coins).toEqual([
-      expect.objectContaining({
-        assetId: baseAssetId,
-        amount: bn(42),
-      }),
-      expect.objectContaining({
-        assetId: assetIdA,
-        amount: bn(100),
-      }),
-    ]);
+    // #endregion get-coins-1
+
+    // #region get-coins-2
+    await wallet.getCoins(baseAssetId);
+    // #endregion get-coins-2
+
+    expect(coins).toBeDefined();
+    expect(pageInfo).toBeDefined();
   });
 
-  it('get balances', async () => {
-    // #region wallet-get-balances
-    // #import { Provider, FUEL_NETWORK_URL, generateTestWallet };
+  it('get spendable resources', async () => {
+    // #region get-spendable-resources-1
+    // #import { Provider, FUEL_NETWORK_URL, generateTestWallet, ScriptTransactionRequest };
 
     const provider = await Provider.create(FUEL_NETWORK_URL);
     const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
@@ -61,21 +55,38 @@ describe('querying the chain', () => {
       [100, assetIdA],
     ]);
 
-    const walletBalances = await wallet.getBalances();
-    // [
-    //   { amount: bn(42), assetId: baseAssetId }
-    //   { amount: bn(100), assetId: assetIdA }
-    // ]
-    // #endregion wallet-get-balances
+    const quantities: CoinQuantityLike[] = [
+      { amount: 32, assetId: baseAssetId, max: 42 },
+      { amount: 50, assetId: assetIdA },
+    ];
 
-    expect(walletBalances).toEqual([
-      { assetId: assetIdA, amount: bn(100) },
-      { assetId: baseAssetId, amount: bn(42) },
-    ]);
+    const utxoId = '0x00000000000000000000000000000000000000000000000000000000000000010001';
+    const messageNonce = '0x381de90750098776c71544527fd253412908dec3d07ce9a7367bd1ba975908a0';
+    const excludedIds: ExcludeResourcesOption = {
+      utxos: [utxoId],
+      messages: [messageNonce],
+    };
+
+    const spendableResources = await provider.getResourcesToSpend(
+      wallet.address,
+      quantities,
+      excludedIds
+    );
+
+    const tx = new ScriptTransactionRequest();
+    tx.addResources(spendableResources);
+    // #endregion get-spendable-resources-1
+
+    // #region get-spendable-resources-2
+    await wallet.getResourcesToSpend(spendableResources, excludedIds);
+    // #endregion get-spendable-resources-2
+
+    expect(spendableResources).toBeDefined();
   });
-  it('get spendable resources', async () => {
-    // #region wallet-get-spendable-resources
-    // #import { Provider, FUEL_NETWORK_URL, generateTestWallet, ScriptTransactionRequest };
+
+  it('get balances', async () => {
+    // #region get-balances-1
+    // #import { Provider, FUEL_NETWORK_URL, generateTestWallet };
 
     const provider = await Provider.create(FUEL_NETWORK_URL);
     const assetIdA = '0x0101010101010101010101010101010101010101010101010101010101010101';
@@ -86,43 +97,47 @@ describe('querying the chain', () => {
       [100, assetIdA],
     ]);
 
-    const spendableResources = await wallet.getResourcesToSpend([
-      { amount: 32, assetId: baseAssetId, max: 42 },
-      { amount: 50, assetId: assetIdA },
-    ]);
+    const { balances } = await provider.getBalances(wallet.address);
+    // [
+    //   { amount: bn(42), assetId: baseAssetId } // total amount of baseAssetId
+    //   { amount: bn(100), assetId: assetIdA } // total amount of assetIdA
+    // ]
+    // #endregion get-balances-1
 
-    const tx = new ScriptTransactionRequest();
-    tx.addResources(spendableResources);
-    // #endregion wallet-get-spendable-resources
+    // #region get-balances-2
+    await wallet.getBalances();
+    // #endregion get-balances-2
 
-    expect(spendableResources[0].amount).toEqual(bn(42));
-    expect(spendableResources[1].amount).toEqual(bn(100));
+    expect(balances).toBeDefined();
   });
 
   it('can getBlocks', async () => {
     // #region Provider-get-blocks
     // #import { Provider, FUEL_NETWORK_URL };
+
     const provider = await Provider.create(FUEL_NETWORK_URL);
+
     // Force-producing some blocks to make sure that 10 blocks exist
     await provider.produceBlocks(10);
-    const blocks = await provider.getBlocks({
+
+    const { blocks } = await provider.getBlocks({
       last: 10,
     });
     // #endregion Provider-get-blocks
     expect(blocks.length).toBe(10);
   });
 
   it('can getMessageByNonce', async () => {
-    // #region getMessageByNonce
+    // #region get-message-by-nonce-1
     // #import { FUEL_NETWORK_URL, Provider };
 
     const provider = await Provider.create(FUEL_NETWORK_URL);
 
     const nonce = '0x381de90750098776c71544527fd253412908dec3d07ce9a7367bd1ba975908a0';
     const message = await provider.getMessageByNonce(nonce);
+    // #endregion get-message-by-nonce-1
 
     expect(message).toBeDefined();
     expect(message?.nonce).toEqual(nonce);
-    // #endregion getMessageByNonce
   });
 });

apps/docs-snippets/src/guide/testing/launching-a-test-node.test.ts

@@ -190,7 +190,7 @@ describe('launching a test node', () => {
       wallets: [wallet],
     } = launched;
 
-    const coins = await wallet.getCoins(assets[0].value);
+    const { coins } = await wallet.getCoins(assets[0].value);
     // #endregion asset-ids
     expect(coins[0].assetId).toEqual(assets[0].value);
   });
@@ -211,7 +211,9 @@ describe('launching a test node', () => {
       wallets: [wallet],
     } = launched;
 
-    const [message] = await wallet.getMessages();
+    const {
+      messages: [message],
+    } = await wallet.getMessages();
     // message.nonce === testMessage.nonce
     // #endregion test-messages
 
@@ -242,7 +244,9 @@ describe('launching a test node', () => {
 
     recipient.provider = provider;
 
-    const [message] = await recipient.getMessages();
+    const {
+      messages: [message],
+    } = await recipient.getMessages();
     // message.nonce === testMessage.nonce
     // #endregion test-messages-chain
 

apps/docs-snippets/src/guide/wallets/checking-balances-and-coins.test.ts

@@ -1,4 +1,4 @@
-import type { BigNumberish, CoinQuantity, WalletUnlocked } from 'fuels';
+import type { BigNumberish, WalletUnlocked } from 'fuels';
 import { Provider, Wallet, FUEL_NETWORK_URL } from 'fuels';
 
 /**
@@ -30,7 +30,7 @@ describe(__filename, () => {
     // #region wallet-check-balances
     // #context import { CoinQuantity } from 'fuels';
 
-    const balances: CoinQuantity[] = await myWallet.getBalances();
+    const { balances } = await myWallet.getBalances();
     // #endregion wallet-check-balances
 
     expect(balances).toEqual([]);

apps/docs-snippets/src/guide/wallets/test-wallets.test.ts

@@ -1,4 +1,4 @@
-import type { CoinQuantity, WalletUnlocked } from 'fuels';
+import type { WalletUnlocked } from 'fuels';
 import { FUEL_NETWORK_URL, Provider, bn } from 'fuels';
 import { generateTestWallet } from 'fuels/test-utils';
 
@@ -31,9 +31,9 @@ describe(__filename, () => {
     const walletC = await generateTestWallet(provider);
 
     // retrieve balances of wallets
-    const walletABalances: CoinQuantity[] = await walletA.getBalances();
-    const walletBBalances = await walletB.getBalances();
-    const walletCBalances = await walletC.getBalances();
+    const { balances: walletABalances } = await walletA.getBalances();
+    const { balances: walletBBalances } = await walletB.getBalances();
+    const { balances: walletCBalances } = await walletC.getBalances();
 
     expect(walletABalances).toEqual([{ assetId: baseAssetId, amount: bn(42) }]);
     expect(walletBBalances).toEqual([

apps/docs/.vitepress/config.ts

@@ -131,6 +131,10 @@ export default defineConfig({
                 text: 'Provider Options',
                 link: '/guide/provider/provider-options',
               },
+              {
+                text: 'Pagination',
+                link: '/guide/provider/pagination',
+              },
               {
                 text: 'Querying the Chain',
                 link: '/guide/provider/querying-the-chain',