Pagination

List endpoints return PaginatedResultAsync, which extends ResultAsync and adds two async generators.

.items() — stream every item across all pages

for await (const illust of client.illusts.search({ word: 'hatsune miku' }).items()) {
  console.log(illust.id, illust.title)
}

for await (const novel of client.users.bookmarks.novels({ userId: client.userId }).items()) {
  console.log(novel.title)
}
Copy

.pages() — access the raw page object

Use this when you need page-level metadata such as nextUrl:

for await (const page of client.illusts.search({ word: 'hatsune miku' }).pages()) {
  console.log(`page has ${page.illusts.length} illusts`)
}
Copy

Awaiting the first page directly

PaginatedResultAsync is also directly await-able and returns only the first page as a Result:

const page = await client.illusts.search({ word: 'cat' })
if (page.isOk) {
  console.log(page.value.illusts.length)
}
Copy

Resuming from a saved cursor

Use parseNextUrl to extract typed cursor parameters from next_url so you can persist a position and resume across restarts.

import { parseNextUrl } from '@book000/pixivts'

const page = await client.users.bookmarks.illusts({ userId: client.userId })
if (page.isOk && page.value.nextUrl) {
  const cursor = parseNextUrl(page.value.nextUrl)
  // cursor.maxBookmarkId is number | undefined — persist this value

  // Next run: pass the saved cursor back
  const resumed = await client.users.bookmarks.illusts({
    userId: client.userId,
    maxBookmarkId: cursor.maxBookmarkId,
  })
}
Copy

Available cursor fields

ParsedNextUrl contains only the pagination cursor fields (not the full query string). All fields are number | undefined.