Create a third options argument and allow users to specify a maxPages setting

Author: jetzhou

README.md

@@ -157,9 +157,35 @@ await octokit.graphql.paginate(
 );
 ```
 
+### Options
+
+You can provide a third argument to `paginate` or `iterator` to modify the behavior of the pagination.
+
+`maxPages` will stop the iteration at the specified number of pages, useful when you don't need all the items in the response but still want to take advantage of the automatic merging.
+
+```
+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
+        }
+      }
+    }
+  }`,
+  { },
+  { maxPages: 10 },
+);
+```
+
 ### Pagination Direction
 
-You can control the pagination direction by the properties deinfed in the `pageInfo` resource.
+You can control the pagination direction by the properties defined in the `pageInfo` resource.
 
 For a forward pagination, use:
 

src/index.ts

@@ -2,6 +2,7 @@ import { Octokit } from "@octokit/core";
 import { createIterator } from "./iterator";
 import { createPaginate } from "./paginate";
 export type { PageInfoForward, PageInfoBackward } from "./page-info";
+export type { Options } from "./options";
 
 export function paginateGraphql(octokit: Octokit) {
   octokit.graphql;

src/iterator.ts

@@ -2,19 +2,28 @@ import { extractPageInfos } from "./extract-page-info";
 import { Octokit } from "@octokit/core";
 import { getCursorFrom, hasAnotherPage } from "./page-info";
 import { MissingCursorChange } from "./errors";
+import type { Options } from "./options";
 
 const createIterator = (octokit: Octokit) => {
   return <ResponseType = any>(
     query: string,
     initialParameters: Record<string, any> = {},
+    options: Options = {},
   ) => {
     let nextPageExists = true;
     let parameters = { ...initialParameters };
+    const { maxPages } = options;
+    let page = 0;
 
     return {
       [Symbol.asyncIterator]: () => ({
         async next() {
           if (!nextPageExists) return { done: true, value: {} as ResponseType };
+          if (maxPages && page >= maxPages) {
+            return { done: true, value: {} as ResponseType };
+          }
+
+          page += 1;
 
           const response = await octokit.graphql<ResponseType>(
             query,

src/options.ts

@@ -0,0 +1,3 @@
+export type Options = {
+  maxPages?: number;
+};

src/paginate.ts

@@ -1,17 +1,20 @@
 import { Octokit } from "@octokit/core";
 import { mergeResponses } from "./merge-responses";
 import { createIterator } from "./iterator";
+import type { Options } from "./options";
 
 const createPaginate = (octokit: Octokit) => {
   const iterator = createIterator(octokit);
   return async <ResponseType extends object = any>(
     query: string,
     initialParameters: Record<string, any> = {},
+    options: Options = {},
   ): Promise<ResponseType> => {
     let mergedResponse: ResponseType = {} as ResponseType;
     for await (const response of iterator<ResponseType>(
       query,
       initialParameters,
+      options,
     )) {
       mergedResponse = mergeResponses<ResponseType>(mergedResponse, response);
     }

test/paginate.test.ts

@@ -282,6 +282,45 @@ describe("pagination", () => {
     ]);
   });
 
+  it(".paginate.iterator() allows users to pass `maxPages` parameter and stops at the right place.", async (): Promise<void> => {
+    const responses = createResponsePages({ amount: 3 });
+
+    const { octokit, getCallCount, getPassedVariablesForCall } = MockOctokit({
+      responses,
+    });
+
+    const actualResponse = await octokit.graphql.paginate<TestResponseType>(
+      `
+        query paginate ($cursor: String) {
+          repository(owner: "octokit", name: "rest.js") {
+            issues(first: 10, after: $cursor) {
+              nodes {
+                title
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }`,
+      {},
+      { maxPages: 2 },
+    );
+
+    expect(actualResponse).toEqual({
+      repository: {
+        issues: {
+          nodes: [{ title: "Issue 1" }, { title: "Issue 2" }],
+          pageInfo: { hasNextPage: true, endCursor: "endCursor2" },
+        },
+      },
+    });
+    expect(getCallCount()).toBe(2);
+    expect(getPassedVariablesForCall(1)).toBeUndefined();
+    expect(getPassedVariablesForCall(2)).toEqual({ cursor: "endCursor1" });
+  });
+
   it("paginate() throws error with path and variable name if cursors do not change between calls.", async (): Promise<void> => {
     const [responsePage1, responsePage2] = createResponsePages({ amount: 2 });
     responsePage2.repository.issues.pageInfo = {