plugin-paginate-rest.js

Octokit plugin to paginate REST API endpoint responses

Usage

Load @octokit/plugin-paginate-rest and @octokit/core (or core-compatible module) directly from cdn.pika.dev

<script type="module">
  import { Octokit } from "https://cdn.pika.dev/@octokit/core";
  import { paginateRest } from "https://cdn.pika.dev/@octokit/plugin-paginate-rest";
</script>

Install with npm install @octokit/core @octokit/plugin-paginate-rest. Optionally replace @octokit/core with a core-compatible module

const { Octokit } = require("@octokit/core");
const { paginateRest } = require("@octokit/plugin-paginate-rest");

const MyOctokit = Octokit.plugin(paginateRest);
const octokit = new MyOctokit({ auth: "secret123" });

// See https://developer.github.com/v3/issues/#list-issues-for-a-repository
const issues = await octokit.paginate("GET /repos/:owner/:repo/issues", {
  owner: "octocat",
  repo: "hello-world",
  since: "2010-10-01",
  per_page: 100
});

octokit.paginate(route, parameters, mapFunction) or octokit.paginate(options, mapFunction)

The paginateRest plugin adds a new octokit.paginate() method which accepts the same parameters as octokit.request. Only “List ...” endpoints such as List issues for a repository are supporting pagination. Their response includes a Link header. For other endpoints, octokit.paginate() behaves the same as octokit.request().

The per_page parameter is usually defaulting to 30, and can be set to up to 100, which helps retrieving a big amount of data without hitting the rate limits too soon.

An optional mapFunction can be passed to map each page response to a new value, usually an array with only the data you need. This can help to reduce memory usage, as only the relevant data has to be kept in memory until the pagination is complete.

const issueTitles = await octokit.paginate(
  "GET /repos/:owner/:repo/issues",
  {
    owner: "octocat",
    repo: "hello-world",
    since: "2010-10-01",
    per_page: 100
  },
  response => response.data.map(issue => issue.title)
);

The mapFunction gets a 2nd argument done which can be called to end the pagination early.

const issues = await octokit.paginate(
  "GET /repos/:owner/:repo/issues",
  {
    owner: "octocat",
    repo: "hello-world",
    since: "2010-10-01",
    per_page: 100
  },
  (response, done) => {
    if (response.data.find(issues => issue.title.includes("something"))) {
      done();
    }
    return response.data;
  }
);

octokit.paginate.iterator(route, parameters) or octokit.paginate.iterator(options)

If your target runtime environments supports async iterators (such as most modern browsers and Node 10+), you can iterate through each response

const parameters = {
    owner: "octocat",
    repo: "hello-world",
    since: "2010-10-01",
    per_page: 100
  }
for await (const response of octokit.paginate.iterator("GET /repos/:owner/:repo/issues", parameters)) {
  // do whatever you want with each response, break out of the loop, etc.
  console.log(response.data.title)
}

How it works

octokit.paginate() wraps octokit.request(). As long as a rel="next" link value is present in the response's Link header, it sends another request for that URL, and so on.

Most of GitHub's paginating REST API endpoints return an array, but there are a few exceptions which return an object with a key that includes the items array.

• Search repositories (key items)
• List check runs for a specific ref (key: check_runs)
• List check suites for a specific ref (key: check_suites)
• List repositories for an installation (key: repositories)
• List installations for a user (key installations)

octokit.paginate() is working around these inconsistencies so you don't have to worry about it.

If a response is lacking the Link header, octokit.paginate() still resolves with an array, even if the response returns a single object.

Contributing

See CONTRIBUTING.md

License

MIT