Security News
Introducing the Socket Python SDK
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
@octokit/plugin-paginate-graphql
Advanced tools
Octokit plugin to paginate GraphQL API endpoint responses
@octokit/plugin-paginate-graphql is a plugin for the Octokit library that simplifies the process of paginating through GitHub's GraphQL API responses. It allows developers to easily handle large sets of data that are returned in multiple pages by automatically fetching all pages of results.
Automatic Pagination
This feature allows you to automatically paginate through all pages of a GraphQL query. The code sample demonstrates how to fetch all issues from a GitHub repository using the paginateGraphql method.
const { Octokit } = require('@octokit/core');
const { paginateGraphql } = require('@octokit/plugin-paginate-graphql');
const MyOctokit = Octokit.plugin(paginateGraphql);
const octokit = new MyOctokit({ auth: 'your-token' });
async function fetchAllIssues() {
const query = `
query($cursor: String) {
repository(owner: "owner", name: "repo") {
issues(first: 100, after: $cursor) {
nodes {
title
number
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
`;
const issues = await octokit.paginateGraphql(query);
console.log(issues);
}
fetchAllIssues();
graphql-request is a minimal GraphQL client for Node.js and browsers. It provides a simple API to send GraphQL queries and mutations. Unlike @octokit/plugin-paginate-graphql, it does not include built-in pagination support, so developers need to handle pagination manually.
Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. It includes advanced features like caching, optimistic UI, and pagination. However, it is more complex and feature-rich compared to @octokit/plugin-paginate-graphql, which is focused specifically on GitHub's GraphQL API.
urql is a highly customizable and versatile GraphQL client for React that also supports pagination. It provides a set of hooks and utilities to manage GraphQL queries and mutations. While it offers more flexibility and customization options, it requires more setup compared to the straightforward pagination provided by @octokit/plugin-paginate-graphql.
Octokit plugin to paginate GraphQL API endpoint responses
Browsers |
Load
|
---|---|
Node |
Install with
|
const MyOctokit = Octokit.plugin(paginateGraphql);
const octokit = new MyOctokit({ auth: "secret123" });
const { repository } = await octokit.graphql.paginate(
`query paginate($cursor: String) {
repository(owner: "octokit", name: "rest.js") {
issues(first: 10, after: $cursor) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}`,
);
console.log(`Found ${repository.issues.nodes.length} issues!`);
There are two convetions this plugin relies on:
$cursor
pageInfo
object in the paginated resource (see Pagination Direction for more info on what is considered valid)octokit.graphql.paginate()
The paginateGraphql
plugin adds a new octokit.graphql.paginate()
method which accepts a query with a single $cursor
variable that is used to paginate.
The query gets passed over to the octokit.graphql()
-function. The response is then scanned for the required pageInfo
-object. If hasNextPage
is true
, it will automatically use the endCursor
to execute the next query until hasNextPage
is false
.
While iterating, it ongoingly merges all nodes
and/or edges
of all responses and returns a combined response in the end.
Warning Please note that this plugin only supports pagination of a single resource - so you can not execute queries with parallel or nested pagination. You can find more details in the chapter below.
octokit.graphql.paginate.iterator()
If your target runtime environments supports async iterators (such as most modern browsers and Node 10+), you can iterate through each response:
const pageIterator = octokit.graphql.paginate.iterator(
`query paginate($cursor: String) {
repository(owner: "octokit", name: "rest.js") {
issues(first: 10, after: $cursor) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}`,
);
for await (const response of pageIterator) {
const issues = response.repository.issues;
console.log(`${issues.length} issues found.`);
}
Just like with octokit/graphql.js, you can pass your own variables as a second parameter to the paginate
or iterator
function.
await octokit.graphql.paginate(
`
query paginate($cursor: String, $organization: String!) {
repository(owner: $organization, name: "rest.js") {
issues(first: 10, after: $cursor) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
`,
{
organization: "octokit",
},
);
You can also use this to pass a initial cursor value:
await octokit.graphql.paginate(
`
query paginate($cursor: String, $organization: String!) {
repository(owner: $organization, name: "rest.js") {
issues(first: 10, after: $cursor) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}
`,
{
organization: "octokit",
cursor: "initialValue",
},
);
You can control the pagination direction by the properties deinfed in the pageInfo
resource.
For a forward pagination, use:
pageInfo {
hasNextPage
endCursor
}
For a backwards pagination, use:
pageInfo {
hasPreviousPage
startCursor
}
If you provide all 4 properties in a pageInfo
, the plugin will default to forward pagination.
Nested pagination with GraphlQL is complicated, so the following is not supported:
await octokit.graphql.paginate((cursor) => {
const issuesCursor = cursor.create("issuesCursor");
const commentsCursor = cursor.create("issuesCursor");
return `{
repository(owner: "octokit", name: "rest.js") {
issues(first: 10, after: ${issuesCursor}) {
nodes {
title,
comments(first: 10, after: ${commentsCursor}) {
nodes: {
body
}
pageInfo {
hasNextPage
endCursor
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
}`;
});
There is a great video from GitHub Universe 2019 Advanced patterns for GitHub's GraphQL API by @ReaLoretta that goes into depth why this is so hard to achieve and patterns and ways around it.
You can type the response of the paginateGraphql()
and iterator()
functions like this:
await octokit.graphql.paginate<RepositoryIssueResponseType>((cursor) => {
return `{
repository(owner: "octokit", name: "rest.js") {
issues(first: 10, after: ${cursor.create()}) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}`;
});
You can utilize the PageInfoForward
and PageInfoBackward
-Interfaces exported from this library to construct your response-types:
import { PageInfoForward } from "@octokit/plugin-paginate-graphql";
type Issues = {
title: string;
};
type IssueResponseType = {
repository: {
issues: {
nodes: Issues[];
pageInfo: PageInfoForward;
};
};
};
// Response will be of type IssueResponseType
const response = await octokit.graphql.paginate<IssueResponseType>((cursor) => {
return `{
repository(owner: "octokit", name: "rest.js") {
issues(first: 10, after: ${cursor.create()}) {
nodes {
title
}
pageInfo {
hasNextPage
endCursor
}
}
}
}`;
});
The PageInfoBackward
contains the properties hasPreviousPage
and startCursor
and can be used accordingly when doing backwards pagination.
See CONTRIBUTING.md
FAQs
Octokit plugin to paginate GraphQL API endpoint responses
The npm package @octokit/plugin-paginate-graphql receives a total of 483,373 weekly downloads. As such, @octokit/plugin-paginate-graphql popularity was classified as popular.
We found that @octokit/plugin-paginate-graphql demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The initial version of the Socket Python SDK is now on PyPI, enabling developers to more easily interact with the Socket REST API in Python projects.
Security News
Floating dependency ranges in npm can introduce instability and security risks into your project by allowing unverified or incompatible versions to be installed automatically, leading to unpredictable behavior and potential conflicts.
Security News
A new Rust RFC proposes "Trusted Publishing" for Crates.io, introducing short-lived access tokens via OIDC to improve security and reduce risks associated with long-lived API tokens.