Pagination

← Back to Indexer Client

Description

This example demonstrates how to properly handle pagination across multiple indexer endpoints using limit and next parameters. It includes a generic pagination helper function and shows iteration through all pages of results.

Prerequisites

• LocalNet running (via algokit localnet start)

Run This Example

From the repository root:

cd examples
npm run example indexer_client/16-pagination.ts

Code

View source on GitHub

16-pagination.ts

/**
 * Example: Pagination
 *
 * This example demonstrates how to properly handle pagination across multiple
 * indexer endpoints using limit and next parameters. It includes a generic
 * pagination helper function and shows iteration through all pages of results.
 *
 * Prerequisites:
 * - LocalNet running (via `algokit localnet start`)
 */

import { algo } from '@algorandfoundation/algokit-utils'
import {
  createAlgorandClient,
  createIndexerClient,
  formatMicroAlgo,
  printError,
  printHeader,
  printInfo,
  printStep,
  printSuccess,
  shortenAddress,
} from '../shared/utils.js'

// ============================================================================
// Generic Pagination Helper Function
// ============================================================================

/**
 * Generic pagination options for fetch function
 */
interface PaginationOptions {
  /** Maximum items per page */
  limit?: number
  /** Token for next page */
  next?: string
}

/**
 * Generic response type for paginated endpoints
 */
interface PaginatedResponse<T> {
  /** The items returned in this page */
  items: T[]
  /** Token for fetching the next page (undefined if no more pages) */
  nextToken?: string
  /** Current round when query was performed */
  currentRound: bigint
}

/**
 * Options for the paginateAll helper
 */
interface PaginateAllOptions<T> {
  /** Page size (default: 100) */
  pageSize?: number
  /** Maximum total items to fetch (default: unlimited) */
  maxItems?: number
  /** Callback called for each page, return false to stop pagination */
  onPage?: (items: T[], pageNumber: number) => boolean | void
  /** Condition to stop early - return true to stop */
  stopWhen?: (item: T, index: number) => boolean
}

/**
 * Generic pagination helper that iterates through all pages of results.
 *
 * This function provides a reusable pattern for paginating through any
 * indexer endpoint that supports limit and next parameters.
 *
 * @param fetchPage - Function that fetches a page of results
 * @param options - Pagination options including pageSize, maxItems, callbacks
 * @returns All items collected across all pages
 *
 * @example
 * // Fetch all transactions from an account
 * const allTxns = await paginateAll(
 *   async (opts) => {
 *     const result = await indexer.searchForTransactions({ ...opts })
 *     return {
 *       items: result.transactions,
 *       nextToken: result.nextToken,
 *       currentRound: result.currentRound,
 *     }
 *   },
 *   { pageSize: 100, maxItems: 1000 }
 * )
 */
async function paginateAll<T>(
  fetchPage: (options: PaginationOptions) => Promise<PaginatedResponse<T>>,
  options: PaginateAllOptions<T> = {},
): Promise<{ items: T[]; totalPages: number; stoppedEarly: boolean }> {
  const { pageSize = 100, maxItems, onPage, stopWhen } = options

  const allItems: T[] = []
  let nextToken: string | undefined
  let pageNumber = 0
  let stoppedEarly = false

  do {
    pageNumber++

    // Fetch the next page
    const response = await fetchPage({
      limit: pageSize,
      next: nextToken,
    })

    // Process items and check for early termination
    for (const item of response.items) {
      // Check stop condition
      if (stopWhen && stopWhen(item, allItems.length)) {
        stoppedEarly = true
        break
      }

      allItems.push(item)

      // Check max items limit
      if (maxItems && allItems.length >= maxItems) {
        stoppedEarly = true
        break
      }
    }

    // Call page callback if provided
    if (onPage) {
      const continueIteration = onPage(response.items, pageNumber)
      if (continueIteration === false) {
        stoppedEarly = true
        break
      }
    }

    // Check if we should stop
    if (stoppedEarly) {
      break
    }

    nextToken = response.nextToken
  } while (nextToken)

  return { items: allItems, totalPages: pageNumber, stoppedEarly }
}

async function main() {
  printHeader('Pagination Example')

  // Create clients
  const indexer = createIndexerClient()
  const algorand = createAlgorandClient()

  // =========================================================================
  // Step 1: Get a funded account and create some test data
  // =========================================================================
  printStep(1, 'Setting up test data for pagination')

  let senderAddress: string
  let senderAccount: Awaited<ReturnType<typeof algorand.account.kmd.getLocalNetDispenserAccount>>

  try {
    senderAccount = await algorand.account.kmd.getLocalNetDispenserAccount()
    algorand.setSignerFromAccount(senderAccount)
    senderAddress = senderAccount.addr.toString()
    printSuccess(`Using dispenser account: ${shortenAddress(senderAddress)}`)

    // Create several random accounts and send them funds to generate transactions
    printInfo('Creating test transactions for pagination demo...')
    const receiverAccounts: string[] = []

    for (let i = 0; i < 5; i++) {
      const receiver = algorand.account.random()
      receiverAccounts.push(receiver.addr.toString())

      await algorand.send.payment({
        sender: senderAccount.addr,
        receiver: receiver.addr,
        amount: algo(1),
      })
    }

    printSuccess(`Created ${receiverAccounts.length} payment transactions`)

    // Create a test asset
    printInfo('Creating test asset...')
    const assetResult = await algorand.send.assetCreate({
      sender: senderAccount.addr,
      total: 1_000_000n,
      decimals: 0,
      assetName: 'PaginationTestToken',
      unitName: 'PAGE',
    })
    printSuccess(`Created asset: PaginationTestToken (ID: ${assetResult.assetId})`)

    // Wait for indexer to catch up
    printInfo('Waiting for indexer to index transactions...')
    await new Promise((resolve) => setTimeout(resolve, 3000))
    printInfo('')
  } catch (error) {
    printError(`Failed to set up test data: ${error instanceof Error ? error.message : String(error)}`)
    printInfo('')
    printInfo('Make sure LocalNet is running: algokit localnet start')
    printInfo('If issues persist, try: algokit localnet reset')
    return
  }

  // =========================================================================
  // Step 2: Demonstrate pagination with searchForTransactions()
  // =========================================================================
  printStep(2, 'Paginating through searchForTransactions()')

  try {
    printInfo('Using the generic paginateAll helper to iterate through all transactions...')
    printInfo('Settings: pageSize=2 (small for demo purposes)')
    printInfo('')

    const transactionResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForTransactions({
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.transactions,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 2, // Small page size to demonstrate pagination
        maxItems: 10, // Limit to 10 for demo
        onPage: (items, pageNumber) => {
          printInfo(`  Page ${pageNumber}: Retrieved ${items.length} transaction(s)`)
        },
      },
    )

    printSuccess(`Total transactions fetched: ${transactionResult.items.length}`)
    printInfo(`Total pages fetched: ${transactionResult.totalPages}`)
    printInfo(`Stopped early (hit maxItems): ${transactionResult.stoppedEarly}`)
    printInfo('')

    // Display first few transactions
    if (transactionResult.items.length > 0) {
      printInfo('First 3 transactions:')
      for (const tx of transactionResult.items.slice(0, 3)) {
        printInfo(`  - ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}: ${tx.txType}`)
      }
    }
  } catch (error) {
    printError(`searchForTransactions pagination failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 3: Demonstrate pagination with searchForAccounts()
  // =========================================================================
  printStep(3, 'Paginating through searchForAccounts()')

  try {
    printInfo('Fetching all accounts with balance > 0 using pagination...')
    printInfo('Settings: pageSize=3')
    printInfo('')

    const accountResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForAccounts({
          currencyGreaterThan: 0n,
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.accounts,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 3,
        maxItems: 15,
        onPage: (items, pageNumber) => {
          printInfo(`  Page ${pageNumber}: Retrieved ${items.length} account(s)`)
        },
      },
    )

    printSuccess(`Total accounts fetched: ${accountResult.items.length}`)
    printInfo(`Total pages fetched: ${accountResult.totalPages}`)
    printInfo('')

    // Display accounts with their balances
    if (accountResult.items.length > 0) {
      printInfo('Accounts found:')
      for (const account of accountResult.items.slice(0, 5)) {
        printInfo(`  - ${shortenAddress(account.address)}: ${formatMicroAlgo(account.amount)}`)
      }
      if (accountResult.items.length > 5) {
        printInfo(`  ... and ${accountResult.items.length - 5} more`)
      }
    }
  } catch (error) {
    printError(`searchForAccounts pagination failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 4: Demonstrate pagination with searchForAssets()
  // =========================================================================
  printStep(4, 'Paginating through searchForAssets()')

  try {
    printInfo('Fetching all assets using pagination...')
    printInfo('Settings: pageSize=2')
    printInfo('')

    const assetResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForAssets({
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.assets,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 2,
        maxItems: 10,
        onPage: (items, pageNumber) => {
          printInfo(`  Page ${pageNumber}: Retrieved ${items.length} asset(s)`)
        },
      },
    )

    printSuccess(`Total assets fetched: ${assetResult.items.length}`)
    printInfo(`Total pages fetched: ${assetResult.totalPages}`)
    printInfo('')

    // Display assets
    if (assetResult.items.length > 0) {
      printInfo('Assets found:')
      for (const asset of assetResult.items.slice(0, 5)) {
        const name = asset.params.name ?? 'Unnamed'
        const unitName = asset.params.unitName ?? 'N/A'
        printInfo(`  - ID ${asset.id}: ${name} (${unitName})`)
      }
      if (assetResult.items.length > 5) {
        printInfo(`  ... and ${assetResult.items.length - 5} more`)
      }
    } else {
      printInfo('No assets found on LocalNet')
    }
  } catch (error) {
    printError(`searchForAssets pagination failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 5: Display total count of items across all pages
  // =========================================================================
  printStep(5, 'Counting total items across all pages')

  try {
    printInfo('Counting all transactions without fetching full data...')
    printInfo('')

    let totalTransactions = 0
    let pageCount = 0
    let nextToken: string | undefined

    // Simple counting loop using limit and next
    do {
      pageCount++
      const result = await indexer.searchForTransactions({
        limit: 100, // Use larger page size for counting
        next: nextToken,
      })

      totalTransactions += result.transactions.length
      nextToken = result.nextToken

      // Safety limit for demo
      if (pageCount >= 10) {
        printInfo('  (stopping after 10 pages for demo purposes)')
        break
      }
    } while (nextToken)

    printSuccess(`Total transactions counted: ${totalTransactions}`)
    printInfo(`Pages scanned: ${pageCount}`)
    printInfo('')

    // Also count accounts
    printInfo('Counting all accounts...')
    let totalAccounts = 0
    pageCount = 0
    nextToken = undefined

    do {
      pageCount++
      const result = await indexer.searchForAccounts({
        currencyGreaterThan: 0n,
        limit: 100,
        next: nextToken,
      })

      totalAccounts += result.accounts.length
      nextToken = result.nextToken

      if (pageCount >= 10) break
    } while (nextToken)

    printSuccess(`Total accounts with balance > 0: ${totalAccounts}`)
    printInfo(`Pages scanned: ${pageCount}`)
  } catch (error) {
    printError(`Counting failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 6: Demonstrate early termination when a condition is met
  // =========================================================================
  printStep(6, 'Demonstrating early termination')

  try {
    printInfo('Searching for transactions until we find a payment transaction...')
    printInfo('')

    const earlyTermResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForTransactions({
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.transactions,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 5,
        stopWhen: (tx, index) => {
          // Stop when we find a payment transaction
          if (tx.txType === 'pay') {
            printInfo(`  Found payment transaction at index ${index}: ${tx.id ? shortenAddress(tx.id, 8, 6) : 'N/A'}`)
            return true
          }
          return false
        },
        onPage: (items, pageNumber) => {
          printInfo(`  Page ${pageNumber}: Checking ${items.length} transaction(s)...`)
        },
      },
    )

    printSuccess(`Stopped early: ${earlyTermResult.stoppedEarly}`)
    printInfo(`Total transactions before stopping: ${earlyTermResult.items.length}`)
    printInfo(`Pages checked: ${earlyTermResult.totalPages}`)
    printInfo('')

    // Another example: stop after finding an account with specific balance
    printInfo('Searching for an account with balance > 1000 ALGO...')

    const accountSearchResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForAccounts({
          currencyGreaterThan: 0n,
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.accounts,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 5,
        stopWhen: (account) => {
          // Stop when we find an account with > 1000 ALGO (1,000,000,000 microAlgos)
          if (account.amount > 1_000_000_000_000n) {
            printInfo(
              `  Found whale account: ${shortenAddress(account.address)} with ${formatMicroAlgo(account.amount)}`,
            )
            return true
          }
          return false
        },
      },
    )

    if (accountSearchResult.stoppedEarly) {
      printSuccess('Found an account with > 1000 ALGO!')
    } else {
      printInfo('No account found with > 1000 ALGO (searched all accounts)')
    }
  } catch (error) {
    printError(`Early termination demo failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 7: Handle the case where there are no results
  // =========================================================================
  printStep(7, 'Handling empty results')

  try {
    printInfo('Searching for assets with a name that does not exist...')
    printInfo('')

    const emptyResult = await paginateAll(
      async (opts) => {
        const result = await indexer.searchForAssets({
          name: 'ThisAssetNameShouldNotExist12345',
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.assets,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      {
        pageSize: 10,
        onPage: (items, pageNumber) => {
          printInfo(`  Page ${pageNumber}: Retrieved ${items.length} item(s)`)
        },
      },
    )

    if (emptyResult.items.length === 0) {
      printSuccess('Correctly handled empty results (no assets found)')
      printInfo(`Total pages: ${emptyResult.totalPages}`)
      printInfo('Note: Empty results return an empty array, not an error')
    } else {
      printInfo(`Unexpectedly found ${emptyResult.items.length} asset(s)`)
    }
    printInfo('')

    // Also demonstrate with accounts
    printInfo('Searching for accounts with impossibly high balance...')
    const emptyAccountResult = await paginateAll(
      async (opts) => {
        // Search for accounts with balance > max supply (would never exist)
        const result = await indexer.searchForAccounts({
          currencyGreaterThan: 10_000_000_000_000_000n, // > 10 billion ALGO
          limit: opts.limit,
          next: opts.next,
        })
        return {
          items: result.accounts,
          nextToken: result.nextToken,
          currentRound: result.currentRound,
        }
      },
      { pageSize: 10 },
    )

    if (emptyAccountResult.items.length === 0) {
      printSuccess('Correctly handled empty results (no accounts with such high balance)')
    } else {
      printInfo(`Found ${emptyAccountResult.items.length} account(s)`)
    }
  } catch (error) {
    printError(`Empty results handling failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Step 8: Manual pagination without helper
  // =========================================================================
  printStep(8, 'Manual pagination pattern (without helper)')

  try {
    printInfo('Sometimes you may want to control pagination manually...')
    printInfo('')

    // Manual pagination loop
    let allTransactions: Awaited<ReturnType<typeof indexer.searchForTransactions>>['transactions'] = []
    let nextToken: string | undefined
    let pageNum = 0

    do {
      pageNum++
      const page = await indexer.searchForTransactions({
        limit: 3,
        next: nextToken,
      })

      allTransactions = allTransactions.concat(page.transactions)
      nextToken = page.nextToken

      printInfo(`  Page ${pageNum}: ${page.transactions.length} transactions (total: ${allTransactions.length})`)

      // Limit for demo
      if (pageNum >= 3) {
        printInfo('  (stopping after 3 pages for demo)')
        break
      }
    } while (nextToken)

    printSuccess(`Manual pagination complete: ${allTransactions.length} transactions in ${pageNum} pages`)
    printInfo('')

    printInfo('Key pagination fields:')
    printInfo('  - limit: Maximum items per page (request parameter)')
    printInfo('  - nextToken: Token from response to fetch next page')
    printInfo('  - When nextToken is undefined/missing, no more pages exist')
  } catch (error) {
    printError(`Manual pagination failed: ${error instanceof Error ? error.message : String(error)}`)
  }

  // =========================================================================
  // Summary
  // =========================================================================
  printHeader('Summary')
  printInfo('This example demonstrated pagination patterns for indexer endpoints:')
  printInfo('')
  printInfo('Pagination basics:')
  printInfo('  - Use `limit` parameter to control page size')
  printInfo('  - Use `next` parameter with `nextToken` from response to get next page')
  printInfo('  - When `nextToken` is undefined, there are no more pages')
  printInfo('')
  printInfo('Generic pagination helper (paginateAll):')
  printInfo('  - Reusable across all paginated endpoints')
  printInfo('  - Supports pageSize, maxItems limits')
  printInfo('  - Supports onPage callback for progress tracking')
  printInfo('  - Supports stopWhen condition for early termination')
  printInfo('')
  printInfo('Endpoints demonstrated:')
  printInfo('  - searchForTransactions() - paginate through transactions')
  printInfo('  - searchForAccounts() - paginate through accounts')
  printInfo('  - searchForAssets() - paginate through assets')
  printInfo('')
  printInfo('Best practices:')
  printInfo('  - Use larger page sizes (50-100) for production to reduce API calls')
  printInfo('  - Implement maxItems limit to prevent unbounded queries')
  printInfo('  - Use early termination when searching for specific items')
  printInfo('  - Handle empty results gracefully (empty array, not error)')
}

main().catch((error) => {
  console.error('Fatal error:', error)
  process.exit(1)
})

---

Other examples in Indexer Client

• Indexer Health Check
• Account Lookup
• Account Assets
• Account Applications
• Account Transactions
• Transaction Lookup
• Transaction Search
• Asset Lookup
• Asset Balances
• Asset Transactions
• Application Lookup
• Application Logs Lookup
• Application Boxes Lookup
• Block Lookup
• Block Headers Search
• Pagination