github.com/jfrog/frogbot@v1.1.1-0.20231221090046-821a26f50338/action/node_modules/@octokit/plugin-paginate-rest/README.md (about)

     1  # plugin-paginate-rest.js
     2  
     3  > Octokit plugin to paginate REST API endpoint responses
     4  
     5  [![@latest](https://img.shields.io/npm/v/@octokit/plugin-paginate-rest.svg)](https://www.npmjs.com/package/@octokit/plugin-paginate-rest)
     6  [![Build Status](https://github.com/octokit/plugin-paginate-rest.js/workflows/Test/badge.svg)](https://github.com/octokit/plugin-paginate-rest.js/actions?workflow=Test)
     7  
     8  ## Usage
     9  
    10  <table>
    11  <tbody valign=top align=left>
    12  <tr><th>
    13  Browsers
    14  </th><td width=100%>
    15  
    16  Load `@octokit/plugin-paginate-rest` and [`@octokit/core`](https://github.com/octokit/core.js) (or core-compatible module) directly from [cdn.skypack.dev](https://cdn.skypack.dev)
    17  
    18  ```html
    19  <script type="module">
    20    import { Octokit } from "https://cdn.skypack.dev/@octokit/core";
    21    import {
    22      paginateRest,
    23      composePaginateRest,
    24    } from "https://cdn.skypack.dev/@octokit/plugin-paginate-rest";
    25  </script>
    26  ```
    27  
    28  </td></tr>
    29  <tr><th>
    30  Node
    31  </th><td>
    32  
    33  Install with `npm install @octokit/core @octokit/plugin-paginate-rest`. Optionally replace `@octokit/core` with a core-compatible module
    34  
    35  ```js
    36  const { Octokit } = require("@octokit/core");
    37  const {
    38    paginateRest,
    39    composePaginateRest,
    40  } = require("@octokit/plugin-paginate-rest");
    41  ```
    42  
    43  </td></tr>
    44  </tbody>
    45  </table>
    46  
    47  ```js
    48  const MyOctokit = Octokit.plugin(paginateRest);
    49  const octokit = new MyOctokit({ auth: "secret123" });
    50  
    51  // See https://developer.github.com/v3/issues/#list-issues-for-a-repository
    52  const issues = await octokit.paginate("GET /repos/{owner}/{repo}/issues", {
    53    owner: "octocat",
    54    repo: "hello-world",
    55    since: "2010-10-01",
    56    per_page: 100,
    57  });
    58  ```
    59  
    60  If you want to utilize the pagination methods in another plugin, use `composePaginateRest`.
    61  
    62  ```js
    63  function myPlugin(octokit, options) {
    64    return {
    65      allStars({owner, repo}) => {
    66        return composePaginateRest(
    67          octokit,
    68          "GET /repos/{owner}/{repo}/stargazers",
    69          {owner, repo }
    70        )
    71      }
    72    }
    73  }
    74  ```
    75  
    76  ## `octokit.paginate()`
    77  
    78  The `paginateRest` plugin adds a new `octokit.paginate()` method which accepts the same parameters as [`octokit.request`](https://github.com/octokit/request.js#request). Only "List ..." endpoints such as [List issues for a repository](https://developer.github.com/v3/issues/#list-issues-for-a-repository) are supporting pagination. Their [response includes a Link header](https://developer.github.com/v3/issues/#response-1). For other endpoints, `octokit.paginate()` behaves the same as `octokit.request()`.
    79  
    80  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.
    81  
    82  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.
    83  
    84  ```js
    85  const issueTitles = await octokit.paginate(
    86    "GET /repos/{owner}/{repo}/issues",
    87    {
    88      owner: "octocat",
    89      repo: "hello-world",
    90      since: "2010-10-01",
    91      per_page: 100,
    92    },
    93    (response) => response.data.map((issue) => issue.title)
    94  );
    95  ```
    96  
    97  The `mapFunction` gets a 2nd argument `done` which can be called to end the pagination early.
    98  
    99  ```js
   100  const issues = await octokit.paginate(
   101    "GET /repos/{owner}/{repo}/issues",
   102    {
   103      owner: "octocat",
   104      repo: "hello-world",
   105      since: "2010-10-01",
   106      per_page: 100,
   107    },
   108    (response, done) => {
   109      if (response.data.find((issues) => issue.title.includes("something"))) {
   110        done();
   111      }
   112      return response.data;
   113    }
   114  );
   115  ```
   116  
   117  Alternatively you can pass a `request` method as first argument. This is great when using in combination with [`@octokit/plugin-rest-endpoint-methods`](https://github.com/octokit/plugin-rest-endpoint-methods.js/):
   118  
   119  ```js
   120  const issues = await octokit.paginate(octokit.rest.issues.listForRepo, {
   121    owner: "octocat",
   122    repo: "hello-world",
   123    since: "2010-10-01",
   124    per_page: 100,
   125  });
   126  ```
   127  
   128  ## `octokit.paginate.iterator()`
   129  
   130  If your target runtime environments supports async iterators (such as most modern browsers and Node 10+), you can iterate through each response
   131  
   132  ```js
   133  const parameters = {
   134    owner: "octocat",
   135    repo: "hello-world",
   136    since: "2010-10-01",
   137    per_page: 100,
   138  };
   139  for await (const response of octokit.paginate.iterator(
   140    "GET /repos/{owner}/{repo}/issues",
   141    parameters
   142  )) {
   143    // do whatever you want with each response, break out of the loop, etc.
   144    const issues = response.data;
   145    console.log("%d issues found", issues.length);
   146  }
   147  ```
   148  
   149  Alternatively you can pass a `request` method as first argument. This is great when using in combination with [`@octokit/plugin-rest-endpoint-methods`](https://github.com/octokit/plugin-rest-endpoint-methods.js/):
   150  
   151  ```js
   152  const parameters = {
   153    owner: "octocat",
   154    repo: "hello-world",
   155    since: "2010-10-01",
   156    per_page: 100,
   157  };
   158  for await (const response of octokit.paginate.iterator(
   159    octokit.rest.issues.listForRepo,
   160    parameters
   161  )) {
   162    // do whatever you want with each response, break out of the loop, etc.
   163    const issues = response.data;
   164    console.log("%d issues found", issues.length);
   165  }
   166  ```
   167  
   168  ## `composePaginateRest` and `composePaginateRest.iterator`
   169  
   170  The `compose*` methods work just like their `octokit.*` counterparts described above, with the differenct that both methods require an `octokit` instance to be passed as first argument
   171  
   172  ## How it works
   173  
   174  `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.
   175  
   176  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. For example:
   177  
   178  - [Search repositories](https://developer.github.com/v3/search/#example) (key `items`)
   179  - [List check runs for a specific ref](https://developer.github.com/v3/checks/runs/#response-3) (key: `check_runs`)
   180  - [List check suites for a specific ref](https://developer.github.com/v3/checks/suites/#response-1) (key: `check_suites`)
   181  - [List repositories](https://developer.github.com/v3/apps/installations/#list-repositories) for an installation (key: `repositories`)
   182  - [List installations for a user](https://developer.github.com/v3/apps/installations/#response-1) (key `installations`)
   183  
   184  `octokit.paginate()` is working around these inconsistencies so you don't have to worry about it.
   185  
   186  If a response is lacking the `Link` header, `octokit.paginate()` still resolves with an array, even if the response returns a single object.
   187  
   188  ## Types
   189  
   190  The plugin also exposes some types and runtime type guards for TypeScript projects.
   191  
   192  <table>
   193  <tbody valign=top align=left>
   194  <tr><th>
   195  Types
   196  </th><td>
   197  
   198  ```typescript
   199  import {
   200    PaginateInterface,
   201    PaginatingEndpoints,
   202  } from "@octokit/plugin-paginate-rest";
   203  ```
   204  
   205  </td></tr>
   206  <tr><th>
   207  Guards
   208  </th><td>
   209  
   210  ```typescript
   211  import { isPaginatingEndpoint } from "@octokit/plugin-paginate-rest";
   212  ```
   213  
   214  </td></tr>
   215  </tbody>
   216  </table>
   217  
   218  ### PaginateInterface
   219  
   220  An `interface` that declares all the overloads of the `.paginate` method.
   221  
   222  ### PaginatingEndpoints
   223  
   224  An `interface` which describes all API endpoints supported by the plugin. Some overloads of `.paginate()` method and `composePaginateRest()` function depend on `PaginatingEndpoints`, using the `keyof PaginatingEndpoints` as a type for one of its arguments.
   225  
   226  ```typescript
   227  import { Octokit } from "@octokit/core";
   228  import {
   229    PaginatingEndpoints,
   230    composePaginateRest,
   231  } from "@octokit/plugin-paginate-rest";
   232  
   233  type DataType<T> = "data" extends keyof T ? T["data"] : unknown;
   234  
   235  async function myPaginatePlugin<E extends keyof PaginatingEndpoints>(
   236    octokit: Octokit,
   237    endpoint: E,
   238    parameters?: PaginatingEndpoints[E]["parameters"]
   239  ): Promise<DataType<PaginatingEndpoints[E]["response"]>> {
   240    return await composePaginateRest(octokit, endpoint, parameters);
   241  }
   242  ```
   243  
   244  ### isPaginatingEndpoint
   245  
   246  A type guard, `isPaginatingEndpoint(arg)` returns `true` if `arg` is one of the keys in `PaginatingEndpoints` (is `keyof PaginatingEndpoints`).
   247  
   248  ```typescript
   249  import { Octokit } from "@octokit/core";
   250  import {
   251    isPaginatingEndpoint,
   252    composePaginateRest,
   253  } from "@octokit/plugin-paginate-rest";
   254  
   255  async function myPlugin(octokit: Octokit, arg: unknown) {
   256    if (isPaginatingEndpoint(arg)) {
   257      return await composePaginateRest(octokit, arg);
   258    }
   259    // ...
   260  }
   261  ```
   262  
   263  ## Contributing
   264  
   265  See [CONTRIBUTING.md](CONTRIBUTING.md)
   266  
   267  ## License
   268  
   269  [MIT](LICENSE)