Skip to main content

Cursor & Keyset Pagination

HonoCube provides first-class support for both traditional offset-based pagination and high-performance cursor / keyset pagination.

While offset pagination (?page=200&limit=50) degrades significantly on large tables due to database OFFSET scans and suffers from page-drift (items shifting between pages when rows are inserted or deleted), cursor pagination provides O(1) seeking performance with rock-solid consistency.


Configuration​

Configure pagination in your resource definition:

export const ordersResource = defineResource({
name: "orders",
table: ordersTable,
pagination: {
type: "both", // "offset" | "cursor" | "both" (default: "offset")
defaultLimit: 25, // Default items per page (default: 20)
maxLimit: 100, // Upper ceiling to prevent query abuse
cursorField: "id", // Field used for cursor seeking (default: primary key)
},
});

Options​

OptionTypeDefaultDescription
type"offset" | "cursor" | "both""offset"The pagination strategy supported by the list endpoint.
defaultLimitnumber20Default number of records returned per page.
maxLimitnumber100Maximum allowable limit parameter. Values above this are capped.
cursorFieldstringPrimary keyThe column used for ordering and cursor navigation.

Cursor Pagination in Action​

When pagination.type is set to "cursor" or "both", HonoCube handles opaque cursor generation and extraction automatically.

1. Fetching the First Page​

GET /orders?limit=10

Response:

{
"success": true,
"data": [
{ "id": 105, "total": 120 },
{ "id": 104, "total": 45 },
...
],
"meta": {
"total": 5420,
"limit": 10,
"nextCursor": "ZXlKaE9pSTFNV...",
"prevCursor": null,
"hasNext": true,
"hasPrev": false
}
}

2. Seeking Forward​

Pass nextCursor as cursor (or after) in the next request:

GET /orders?limit=10&cursor=ZXlKaE9pSTFNV...

The database query uses an indexed WHERE id < :cursor ORDER BY id DESC LIMIT 10 condition—seeking directly to the next page in constant time without scanning earlier rows.

3. Seeking Backward​

Pass prevCursor as before to navigate backwards:

GET /orders?limit=10&before=ZXlKaE9pSTFNV...

Tie-Breaker Columns & Drift Protection​

When sorting by a non-unique column (such as createdAt or price), duplicate timestamps can cause missing or duplicate records between pages.

HonoCube automatically appends the primary key as a deterministic tie-breaker:

WHERE (created_at, id) < (:cursor_created_at, :cursor_id)
ORDER BY created_at DESC, id DESC

This guarantees that cursor pagination remains 100% deterministic, even with identical timestamp values across millions of rows.