Test Pagination at Its Boundaries

1. Write the boundary cases as a table with expected page counts.

const cases = [
  { name: 'empty', rows: 0, limit: 10, pages: 0 },
  { name: 'exact page', rows: 10, limit: 10, pages: 1 },
  { name: 'one over', rows: 11, limit: 10, pages: 2 },
];

Expected output: Each case names the boundary and asserts page count, not just the status code of the first page.

2. Seed rows that share a sort timestamp so ties are exercised.

await seedEvents([
  { id: 1, createdAt: '2026-10-01T00:00:00Z' },
  { id: 2, createdAt: '2026-10-01T00:00:00Z' },
  { id: 3, createdAt: '2026-10-01T00:00:00Z' },
  { id: 4, createdAt: '2026-10-02T00:00:00Z' },
]);

Expected output: Three rows tie on created_at; ordering by created_at alone would repeat or skip a row at the page edge.

3. Walk every page, assert no duplicates, and require the final cursor to be null.

const seen = new Set();
let cursor = null;
let pages = 0;
do {
  const qs = cursor ? `?limit=4&cursor=${encodeURIComponent(cursor)}` : '?limit=4';
  const res = await request(`/api/events${qs}`);
  for (const row of res.body.data) {
    assert.ok(!seen.has(row.id), `duplicate ${row.id}`);
    seen.add(row.id);
  }
  cursor = res.body.nextCursor;
  pages += 1;
} while (cursor && pages < 10);
assert.equal(seen.size, 11);
assert.equal(cursor, null);

Expected output: All 11 ids appear exactly once across three pages, and the last response has nextCursor null.

4. Reject a malformed cursor with a stable error code instead of an empty page.

const res = await request('/api/events?cursor=not-a-cursor');
assert.equal(res.status, 400);
assert.equal(res.body.error, 'invalid_cursor');

Expected output: A tampered or truncated cursor returns 400 with error=invalid_cursor, not 200 with zero rows.

5. Pin the clamping rules for zero, huge, and negative limits.

assert.equal((await request('/api/events?limit=0')).body.meta.limit, 1);
assert.equal((await request('/api/events?limit=1000')).body.meta.limit, 100);
assert.equal((await request('/api/events?limit=-5')).status, 400);

Expected output: Zero clamps to 1, one thousand clamps to 100, and a negative limit is rejected with 400.

Problem

Rows are duplicated at page boundaries

Solution

The sort key is not unique. Order by (created_at, id) and encode both values in the cursor so ties have a stable position.

Problem

The last page still returns a next cursor

Solution

Fetch limit + 1 rows to detect whether more exist, and return null when only the requested page was found.

Problem

Cursors break after rows are deleted

Solution

Keyset pagination survives deletes; offset pagination shifts rows. Use keyset for anything that clients sync.

Problem

Old cursors become invalid after a deploy

Solution

Version the cursor payload and accept the previous format during the rollout window.