logo
Menu
How to use Paginator Functions in the AWS SDK for JavaScript

How to use Paginator Functions in the AWS SDK for JavaScript

Paginator functions, a new mechanism in the AWS SDK for JavaScript, automatically manage paginated results returned by the AWS API. In this short post, you will learn how to use them with just a few lines of code.

Dennis Traub
Amazon Employee
Published Feb 16, 2024
Last Modified Mar 20, 2024
In this short post, I will quickly explain pagination, and how some AWS APIs use it to break down large lists of results. I'll show what the necessary handling logic used to look like on the client side, before we'll dive into new JavaScript SDK feature called paginator functions, and how you can use them to reduce your calling code to just a few lines, without having to take care of all the underlying complexities.

First, let's understand pagination

When interacting with AWS APIs that return multiple items in a list, such as lambda:listFunctions or ec2:DescribeInstanceTypes, you'll often encounter paginated results once the number of items grows beyond a certain size.
This design pattern allows the API to return a manageable subset of results at a time, along with information for fetching additional subsets. This mechanism is known as pagination.
If the first request doesn't return all available results, the API indicates the availability of more pages by including a nextToken in the response. If a nextToken is present, you can request the next page by passing this token as an argument in your subsequent request.
Here's an example, using the Bedrock Agents API:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import { BedrockAgentClient, ListAgentsCommand } from '@aws-sdk/client-bedrock-agent';

const client = new BedrockAgentClient({ region: 'us-east-1' });

// Initialize token for the first page retrieval
let nextToken = null;

const agentSummaries = [];

do {
// Prepare the command with the current token and send it to the client
const command = new ListAgentsCommand({ nextToken });
const responsePage = await client.send(command);

// Collect agent summaries from the current page
agentSummaries.push(...(responsePage.agentSummaries || []));

// Update the token for the next iteration or end loop if null
nextToken = responsePage.nextToken;
} while (nextToken);

console.log(agentSummaries);
Managing this manually can be cumbersome and error-prone, especially with complex logic for ending the iteration.
Furthermore, while developing your application, you may not even know whether it will grow to a point where the API will automatically start paginating. For this reason you will have to implement the pagination logic every single time to avoid the risk of running into an error that will be hard to troubleshoot months, or maybe even years down the line

How to streamline pagination with Paginator Functions

This is where paginator functions come into play. They have been introduced with the AWS SDK for JavaScript v3, where many service clients now expose paginateOperationName functions. These functions handle all the pagination details by automatically sending subsequent requests, and returning the results as if they were a single, continuous stream.
With this, you can iterate over the items across all pages without the need to implement the logic to request each subsequent page. Using paginator functions in you JavaScript code simplifies and streamlines the process of working with large datasets, significantly improving your code's readability and maintainability.
Here the example from above, but with a paginator function:
1
2
3
4
5
6
7
8
9
10
11
12
import { BedrockAgentClient, paginateListAgents } from '@aws-sdk/client-bedrock-agent';

const client = new BedrockAgentClient({ region });

const agentSummaries = [];

// Calling the paginator function automatically retrieves one page after the other.
for await (const page of paginateListAgents({ client }, {})) {
agentSummaries.push(...page.agentSummaries);
}

console.log(agentSummaries);
As you can see, paginator functions significantly simplify your code. By abstracting the pagination logic, you can focus your application's functionality instead of having to understand and manage the implementation details of the AWS API, which ultimately leads to cleaner and more maintainable code, while reducing the risk of surprising errors at a later point in time.

Learn more

To learn more about using JavaScript and AWS, feel free to explore the AWS Developer Center and check out the SDK documentation.
We're also working on a growing repository of code examples in the AWS Code Library and on GitHub.
Feel free to give me a 👍 if learned something new. I'm already working on another post, showing how to mock paginator functions in your unit tests. Stay tuned!
 

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.