How to use Paginator Functions in the AWS SDK for JavaScript

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.

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:

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

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:

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.

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!