Nourishing Pizza Microservice

    @octokit/plugin-paginate-graphql
    TypeScript icon, indicating that this package has built-in type declarations

    2.0.1 • Public • Published

    plugin-paginate-graphql.js

    Octokit plugin to paginate GraphQL API endpoint responses

    @latest Build Status

    Usage

    Browsers

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

    <script type="module">
      import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
      import { paginateGraphql } from "https://cdn.skypack.dev/@octokit/plugin-paginate-graphql";
    </script>
    Node

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

    const { Octokit } = require("@octokit/core");
    const { paginateGraphql } = require("@octokit/plugin-paginate-graphql");
    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:

    1. The name of the cursor variable must be $cursor
    2. You must include a valid 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.`);
    }

    Variables

    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",
      }
    );

    Pagination Direction

    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.

    Unsupported: Nested 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.

    TypeScript Support

    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.

    Contributing

    See CONTRIBUTING.md

    License

    MIT

    Install

    npm i @octokit/plugin-paginate-graphql

    DownloadsWeekly Downloads

    653

    Version

    2.0.1

    License

    MIT

    Unpacked Size

    57.6 kB

    Total Files

    23

    Last publish

    Collaborators

    • kfcampbell
    • nickfloyd
    • gr2m
    • octokitbot