Page through results

Most listings come in two forms. list() returns an async iterable that fetches pages as the loop needs them. listPage() returns one page.

Iterate

Use for await when you want every item, or the first few:

let seen = 0

for await (const thread of gh.threads.list(repo, { state: 'open' })) {
  console.log(thread.title)
  if (++seen === 20) {
    break
  }
}

A break stops the requests. perPage sets the page size, and signal aborts the listing.

Fetch a page

A page has items and an optional cursor. Where the forge reports them, it also has rateLimit and warnings:

const page = await gh.threads.listPage(repo, { perPage: 50 })

for (const thread of page.items) {
  console.log(thread.title)
}

cursor is absent when the listing is exhausted. Otherwise, pass it back in the options to read the next page:

if (page.cursor) {
  const next = await gh.threads.listPage(repo, {
    perPage: 50,
    cursor: page.cursor,
  })
}

Persist the whole cursor object and hand it back unchanged. Its fields depend on the forge.

Poll for changes

GitHub notifications support conditional requests. The first page has an etag. To read the first page again, pass it back as the etag option. When nothing changed, the page has notModified: true and no items:

let etag: string | undefined

const page = await gh.notifications.listPage({ etag })

if (!page.notModified) {
  handle(page.items)
  etag = page.etag
}

For push delivery instead of polling, see Events.