page · apistock docs

import "apistock.dev/page"Source on GitHub

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: pre-1.0 (ADR-0015).

Constants#

const DefaultLimit, …#

const (
	DefaultLimit = 20
	MaxLimit     = 100
	// MaxCursorLength bounds cursor size to limit abuse.
	MaxCursorLength = 512
)

Limits used when Options leaves them zero.

Variables#

var ErrInvalidLimit, …#

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#

func DecodeCursor(cursor string, position any) error

DecodeCursor decodes a cursor produced by EncodeCursor into position.

func EncodeCursor#

func EncodeCursor(position any) (string, error)

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 `query:"sort" maxLength:"200" doc:"Comma-separated sort fields; prefix a field with - for descending order" example:"-created_at"`
}

Params are the raw query parameters of a list endpoint. The struct tags make Huma document and validate them.

func (Params) Request#

func (p Params) Request(opts Options) (Request, error)

Request validates p against opts.

type Request#

type Request struct {
	Limit  int
	Cursor string
	Sort   []SortField
}

Request is a validated pagination request.

func Parse#

func Parse(q url.Values, opts Options) (Request, error)

Parse reads limit, cursor and sort from URL query values.

type Result#

type Result[T any] struct {
	Items      []T    `json:"items"`
	NextCursor string `json:"next_cursor,omitempty" doc:"Pass as cursor to get the next page; absent on the last page"`
}

Result is a page of items. NextCursor is empty on the last page.

type SortField#

type SortField struct {
	Field string
	Desc  bool
}

SortField is one validated sort key.