feat: add plugin-paginate-graphql (#2487)

* feat: add plugin-paginate-graphql

* docs: GraphQL pagination

README.md

@@ -27,6 +27,7 @@ The `octokit` package integrates the three main Octokit libraries
       - [Media Type formats](#media-type-formats)
       - [Request error handling](#request-error-handling)
     - [GraphQL API queries](#graphql-api-queries)
+      - [Pagination](#pagination-1)
       - [Schema previews](#schema-previews)
   - [App client](#app-client)
     - [GitHub App](#github-app)
@@ -626,6 +627,40 @@ const { lastIssues } = await octokit.graphql(
 );
 ```
 
+#### Pagination
+
+GitHub's GraphQL API returns a maximum of 100 items. If you want to retrieve all items, you can use the pagination API.
+
+Example: get all issues
+
+```js
+const { allIssues } = await octokit.graphql.paginate(
+  `
+    query allIssues($owner: String!, $repo: String!, $num: Int = 10, $cursor: String) {
+      repository(owner: $owner, name: $repo) {
+        issues(first: $num, after: $cursor) {
+          edges {
+            node {
+              title
+            }
+          }
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+        }
+      }
+    }
+  `,
+  {
+    owner: "octokit",
+    repo: "graphql.js",
+  },
+);
+```
+
+Learn more about [GitHub's GraphQL Pagination](https://github.com/octokit/plugin-paginate-graphql.js#readme) usage.
+
 #### Schema previews
 
 Previews can be enabled using the `{mediaType: previews: [] }` option.

package.json

@@ -23,6 +23,7 @@
     "@octokit/app": "^14.0.0",
     "@octokit/core": "^5.0.0",
     "@octokit/oauth-app": "^6.0.0",
+    "@octokit/plugin-paginate-graphql": "^4.0.0",
     "@octokit/plugin-paginate-rest": "^8.0.0",
     "@octokit/plugin-rest-endpoint-methods": "^9.0.0",
     "@octokit/plugin-retry": "^6.0.0",

src/index.ts

@@ -1,2 +1,3 @@
 export { Octokit, RequestError } from "./octokit";
+export type { PageInfoForward, PageInfoBackward } from "./octokit";
 export { App, OAuthApp, createNodeMiddleware } from "./app";

src/octokit.ts

@@ -1,16 +1,22 @@
 import { Octokit as OctokitCore } from "@octokit/core";
 import { paginateRest } from "@octokit/plugin-paginate-rest";
+import { paginateGraphql } from "@octokit/plugin-paginate-graphql";
 import { restEndpointMethods } from "@octokit/plugin-rest-endpoint-methods";
 import { retry } from "@octokit/plugin-retry";
 import { throttling } from "@octokit/plugin-throttling";
 
 import { VERSION } from "./version";
 
 export { RequestError } from "@octokit/request-error";
+export type {
+  PageInfoForward,
+  PageInfoBackward,
+} from "@octokit/plugin-paginate-graphql";
 
 export const Octokit = OctokitCore.plugin(
   restEndpointMethods,
   paginateRest,
+  paginateGraphql,
   retry,
   throttling,
 ).defaults({