Documentation
¶
Overview ¶
Package page provides cursor pagination and sorting for list endpoints: bounded limits, opaque cursors and allowlisted sort fields.
Embed Params in a Huma input struct, or call Parse with URL query values, then convert to a validated Request against the endpoint's Options.
Cursors are opaque but not signed. They must only encode positions (for example the last item's sort key and ID); repositories still apply authorisation and tenant filters to every query.
Stability: stable (ADR-0015, ADR-0054).
Index ¶
Constants ¶
const ( DefaultLimit = 20 MaxLimit = 100 // MaxCursorLength bounds cursor size to limit abuse. MaxCursorLength = 512 )
Limits used when Options leaves them zero.
Variables ¶
var ( ErrInvalidLimit = errors.New("page: invalid limit") ErrInvalidCursor = errors.New("page: invalid cursor") ErrInvalidSort = errors.New("page: invalid sort") )
Errors returned for invalid pagination input.
Functions ¶
func DecodeCursor ¶
DecodeCursor decodes a cursor produced by EncodeCursor into position.
func EncodeCursor ¶
EncodeCursor returns an opaque cursor for position, which must be JSON-encodable.
Types ¶
type Options ¶
type Options struct {
DefaultLimit int // zero means DefaultLimit
MaxLimit int // zero means MaxLimit
// SortFields is the allowlist of sortable fields. Empty means sorting is not allowed.
SortFields []string
// DefaultSort applies when the request has no sort.
DefaultSort []SortField
}
Options configure what a list endpoint accepts.
type Params ¶
type Params struct {
Limit int `query:"limit" minimum:"0" maximum:"100" doc:"Maximum number of items to return (default 20, max 100)"`
Cursor string `query:"cursor" maxLength:"512" doc:"Opaque cursor from a previous response's next_cursor"`
Sort string `` /* 128-byte string literal not displayed */
}
Params are the raw query parameters of a list endpoint. The struct tags make Huma document and validate them.
Source Files