Keyset Pagination That Cannot Skip or Duplicate

Opaque keyset cursors over a caller-declared sort, with the page condition produced as structured data.

THE SILENT FAILURE. Almost every paginated API uses LIMIT and OFFSET. Insert or delete a row between page one and page two and OFFSET shifts: the reader SKIPS a record it never saw, or sees the same one twice. Nothing errors. A nightly export paging through a busy table quietly omits records, the count still looks about right, and it is discovered months later by a reconciliation that does not add up. Sorting by a non-unique column has the same effect with no writes at all, because the database may order ties differently between queries.

It REFUSES a sort that cannot be proven total -- a cursor over a non-unique ordering is the bug, so accepting one silently is unacceptable. Cursors are tamper-evident: a cursor encodes the sort it was issued for, and decoding it under a DIFFERENT sort is refused rather than silently reinterpreted, because a cursor read under the wrong ordering returns a plausible, wrong page.

It returns the WHERE-clause tuple comparison as structured data for the caller to bind as parameters. It does not build SQL strings, which would push an injection surface into your app. Mixed-direction sorts and null ordering are handled explicitly, both places hand-rolled tuple comparisons are usually wrong.

An independent verifier built a from-scratch brute-force oracle and ran 30,000 pivot-versus-dataset comparisons against it across randomised mixed-direction sorts: zero mismatches.

VERIFIED: 81 tests. Every mutation was observed FAILING before the source was restored -- a test never seen to fail is a decoration. Independently reviewed by a verifier whose job was to find what is wrong, not to agree.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function buildPageCondition( sort: Sort, cursor: DecodedCursor, options?: BuildPageConditionOptions, ): WhereExpression;
  export function buildPageConditionFromRow( sort: Sort, row: Record<string, unknown>, options?: BuildPageConditionOptions, ): WhereExpression;
  export function encodeCursor(sort: Sort, row: Record<string, unknown>, options?: EncodeCursorOptions): string;
  export function decodeCursor(sort: Sort, cursor: string, options?: DecodeCursorOptions): DecodedCursor;
  export function toBase64Url(input: string): string;
  export function fromBase64Url(input: string): string;
  export function canonicalizeSortColumns(columns: readonly NormalizedSortColumn[]): string;
  export function computeSortFingerprint(columns: readonly NormalizedSortColumn[]): string;
  export function signPayload(secret: string, canonical: string): string;
  export function verifySignature(secret: string, canonical: string, signatureHex: string): boolean;
  export function defineSort(columns: readonly SortColumnInput[]): Sort;
  export function assertValidSort(value: unknown): asserts value is Sort;

  export type SortColumn = NormalizedSortColumn;
  export type SortDirection = "asc" | "desc";
  export type ColumnType = "string" | "number" | "boolean" | "date";
  export type NullsOrder = "first" | "last";
  export type CursorValue = string | number | boolean | null | Date;
  export type CompareOp = "gt" | "lt" | "eq" | "isNull" | "isNotNull";