# collections.paginate

Page numbers are 1-based, because every pagination UI, every query string and
every API contract in the wild is 1-based. Page 0 is therefore a caller bug and
raises.

A page past the end is NOT an error. It returns an empty items list with the
real totals, because a client asking for page 9 of a collection that shrank to 2
pages between requests is a race, not a mistake, and it should render an empty
page rather than a 500.

perPage of 0 or less is an error. There is no honest page of zero items: an
unbounded page would silently return the whole collection, which is exactly the
outage pagination exists to prevent. Ask for the whole list explicitly instead.

totalPages is 0 for an empty collection, not 1. Zero items really is zero pages,
and it makes `page <= totalPages` the single correct test for whether a page
exists.

hasPrev is `page > 1`, not `total > 0`: on page 9 of a 2-page collection there
genuinely are earlier pages to go back to.