← Todas las plantillas

Orden estable, cursores opacos, sin filas perdidas ni repetidas.

Spec — Cursor pagination

Status: draft · Created: 2026-11-10

1. Context and goal

Clients walk through long, changing lists page by page and see every row exactly once, with pages that stay fast deep into the list.

2. Functional requirements (EARS)

  • FR-1: THE SYSTEM SHALL order every paginated list by the requested sort field plus the unique id as a tie-breaker, so the order is total and stable.
  • FR-2: WHEN a page of 1 to 200 rows (50 by default) is returned, THE SYSTEM SHALL include an opaque next_cursor built from the sort values and id of its last row, or null on the last page.
  • FR-3: WHEN a client sends a cursor, THE SYSTEM SHALL return the rows strictly after it with a keyset condition, never an offset, so any page of a 10-million-row list takes under 50 ms.
  • FR-4: IF rows are inserted or deleted between requests, THEN THE SYSTEM SHALL neither repeat nor skip any row that existed for the whole walk.
  • FR-5: IF a cursor is malformed, tampered with, or sent with a different sort or filter, THEN THE SYSTEM SHALL answer 400.

3. Out of scope

  • Jumping to an arbitrary page number.
  • Total counts of the list.