Pagination

Page contract

interface PaginatedResult<T> {
  data: T[];
  nextCursor?: string;
  hasMore: boolean;
}

Collection methods return a page object. Item responses remain direct JSON objects, and successful deletes may return no body.

Manual pagination

const page = await pbj.wallets.getActivity(address, { limit: 50 });

if (page.hasMore && page.nextCursor) {
  const next = await pbj.wallets.getActivity(address, {
    cursor: page.nextCursor,
    limit: 50,
  });
  console.log(next.data);
}

Lazy async iteration

import { paginate } from "pbjspace";

for await (const task of paginate(
  (options) => pbj.tasks.list({
    ...options,
    projectId: project.id,
    status: "todo",
  }),
  { limit: 100, signal: controller.signal },
)) {
  console.log(task.id, task.title);
}

The iterator fetches only when the consumer requests another item. Breaking the loop prevents later pages from being requested.

Pagination safety

• Missing continuation cursors are rejected when hasMore is true.
• Repeated cursors are detected to prevent infinite loops.
• Each resource request gets its own deadline.
• Cancellation is checked between yielded items and during requests.
• The iterator stores only the current page and previously seen cursors.