view release on metacpan or  search on metacpan

docs/adr/0005-stateless-base64-pk-cursors.md  view on Meta::CPAN

  (`_apply_pagination` checks `$args->{cursor}` first; the precedence is
  documented in the helper's comment).
- Ordering defaults to ascending PK (`_apply_pagination` orders by
  `primary_columns` when no `orderBy` is given), which is what makes the
  `pk > value` seek correspond to "the next page."

## Rationale

A stateless PK cursor needs no server-side session, no storage, and no
cleanup — every request carries everything required to resume, which is the
right fit for a stateless GraphQL endpoint and for a layer that wants to add
no runtime dependency. Encoding the PK (rather than an offset) makes
`after` a keyset seek (`pk > value`) instead of a large `OFFSET`, so deep
pages stay cheap and do not skew when rows are inserted/deleted between
requests. Base64 keeps the token opaque to clients and URL/transport-safe;
the percent-escaping of `:` and `%` keeps composite-PK decoding unambiguous.

The design's correctness rests on one assumption: that the result is ordered
by the same PK the cursor encodes. That assumption is satisfied by the
default ordering, which is why cursor pagination is paired with PK ordering.