Rules Hub
Code Ruleset
← Back to all rules
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
backend ruleP1universalStack: node
api-designpaginationresponse-shape
Return pagination metadata alongside paged results
Return useful pagination metadata for the chosen contract; exact totals are optional when cursor continuation suffices.
PR: hegnar-ws · org-mining-2026-06Created: Jun 17, 2026
Bad example
Old codetypescript
| 1 | res.json(items); // limit/offset accepted but no total returned |
Explanation (EN)
A bare page can leave the consumer unable to distinguish completion from more results.
Objašnjenje (HR)
Good example
New codetypescript
| 1 | res.json({ items, total, limit, offset }); |
Explanation (EN)
Objašnjenje (HR)
Notes (EN)
Return the continuation information required by the chosen pagination contract, including stable ordering and exhaustion semantics.
Exceptions / Tradeoffs (EN)
An exact total count is not always required or affordable. Cursor APIs may expose nextCursor/hasMore; metadata and rows need a consistent snapshot where the contract promises it.