@azure/core-paging

What is @azure/core-paging?

@azure/core-paging is a library that provides utilities for handling paginated responses from Azure services. It simplifies the process of iterating over paginated data, making it easier to work with large sets of data that are returned in multiple pages.

What are @azure/core-paging's main functionalities?

Iterating over paginated results

This feature allows you to iterate over paginated results using an asynchronous iterator. The code sample demonstrates how to use the PagedAsyncIterableIterator to loop through items returned by a client's listItems method.

const { PagedAsyncIterableIterator } = require('@azure/core-paging');

async function iteratePages(client) {
  const pagedIterator = client.listItems();
  for await (const item of pagedIterator) {
    console.log(item);
  }
}

Handling paginated responses

This feature allows you to handle paginated responses page by page. The code sample demonstrates how to use the byPage method to iterate through each page of results and process the items within each page.

const { PagedAsyncIterableIterator } = require('@azure/core-paging');

async function handlePages(client) {
  const pagedIterator = client.listItems();
  let pageCount = 0;
  for await (const page of pagedIterator.byPage()) {
    console.log(`Page ${++pageCount}:`);
    for (const item of page) {
      console.log(item);
    }
  }
}

Other packages similar to @azure/core-paging

axios

Axios is a popular HTTP client for making requests to APIs. While it does not provide built-in support for pagination, it can be used in conjunction with custom logic to handle paginated responses. Compared to @azure/core-paging, axios requires more manual handling of pagination.

node-fetch

Node-fetch is a lightweight module that brings window.fetch to Node.js. Similar to axios, it does not have built-in pagination support but can be used with custom logic to manage paginated data. It is more low-level compared to @azure/core-paging, which offers higher-level utilities for pagination.

request-promise

Request-promise is a simplified HTTP request client for Node.js with Promise support. Like axios and node-fetch, it does not include pagination utilities out of the box. Users need to implement their own pagination handling, making it less convenient than @azure/core-paging for working with paginated data.

README

Azure Core Paging client library for JavaScript

This library provides core types for paging async iterable iterators.

Getting started

Installation

If using this as part of another project in the azure-sdk-for-js repo, then run rush install after cloning the repo.

Otherwise, use npm to install this package in your application as follows

npm install @azure/core-paging

Key concepts

You can find an explanation of how this repository's code works by going to our architecture overview.

Examples

Example of building with the types:

  public listSecrets(
    options?: ListSecretsOptions
  ): PagedAsyncIterableIterator<SecretAttributes> {
    const iter = this.listSecretsAll(options);
    return {
      async next() {
        const item = (await iter.next()).value;
        return item ? { done: false, value: item } : { done: true, value: undefined };
      },
      [Symbol.asyncIterator](https://github.com/Azure/azure-sdk-for-js/tree/fbf67bc724f73158ed5b0bd2b82961e8087bd1cc/sdk/core/core-paging) { return this; },
      byPage: (settings: PageSettings = {}) => this.listSecretsPage(settings, options),
    };
  }

And using the types:

  for await (let page of client.listSecrets().byPage({ pageSize: 2 })) {
    for (const secret of page) {
      console.log("secret: ", secret);
    }
  }

Next steps

Try out this package in your application when dealing with async iterable iterators and provide feedback!

Troubleshooting

Log an issue at https://github.com/Azure/azure-sdk-for-js/issues

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.