Documentation
¶
Overview ¶
Package list provides stable list-query parsing and list response helpers.
Use ParseListQueryChecked when handlers need field-level validation errors for pagination, filtering, or sorting. The single-return ParseListQuery and parser helpers remain available for v2 source compatibility, but new examples should prefer the checked APIs when invalid input must produce Problem Details.
See contrib/examples/pagination for a runnable limit/offset endpoint.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CursorCodec ¶ added in v2.1.0
type CursorCodec interface {
Encode(values map[string]string, expiresAt time.Time) (string, error)
Decode(cursor string) (map[string]string, error)
}
CursorCodec encodes and decodes opaque cursor values.
func NewHMACCursorCodec ¶ added in v2.1.0
func NewHMACCursorCodec(secret []byte) CursorCodec
NewHMACCursorCodec returns a URL-safe JSON+HMAC cursor codec.
type CursorMeta ¶ added in v2.1.0
type CursorMeta struct {
Count int `json:"count"`
Limit int `json:"limit"`
Cursor string `json:"cursor,omitempty"`
NextCursor string `json:"next_cursor,omitempty"`
}
CursorMeta captures cursor pagination metadata.
type CursorQuery ¶ added in v2.1.0
type CursorQuery struct {
Limit int
Cursor string
Values map[string]string
Raw map[string][]string
}
CursorQuery captures cursor pagination input.
func ParseCursorQueryChecked ¶ added in v2.1.0
func ParseCursorQueryChecked(r *http.Request, cfg CursorQueryConfig) (CursorQuery, error)
ParseCursorQueryChecked parses cursor pagination parameters.
type CursorQueryConfig ¶ added in v2.1.0
type CursorQueryConfig struct {
DefaultLimit int
MaxLimit int
CursorParam string
LimitParam string
Codec CursorCodec
}
CursorQueryConfig configures cursor query parsing.
type CursorResponse ¶ added in v2.1.0
type CursorResponse[T any] struct { Data []T `json:"data"` Meta CursorMeta `json:"meta"` }
CursorResponse wraps list results with cursor pagination metadata.
func NewCursorResponse ¶ added in v2.1.0
func NewCursorResponse[T any](items []T, nextCursor string, query CursorQuery) CursorResponse[T]
NewCursorResponse constructs a CursorResponse with paging metadata.
type Filters ¶
Filters describes allowed filter values.
func DefaultFilterParser ¶
func DefaultFilterParser(values url.Values, cfg ListQueryConfig) Filters
DefaultFilterParser implements the toolkit's standard query syntax. It preserves the v2-compatible single-return shape; callers that need validation errors should use DefaultFilterParserChecked.
func DefaultFilterParserChecked ¶ added in v2.1.0
func DefaultFilterParserChecked(values url.Values, cfg ListQueryConfig) (Filters, fielderrors.FieldErrors)
DefaultFilterParserChecked implements the toolkit's standard query syntax and returns unsupported-filter validation errors.
type ListMeta ¶
type ListMeta struct {
Total int `json:"total"`
Count int `json:"count"`
Limit int `json:"limit"`
Offset int `json:"offset"`
Filters map[string][]string `json:"filters,omitempty"`
Search string `json:"search,omitempty"`
Sort []SortField `json:"sort,omitempty"`
}
ListMeta captures pagination metadata for responses.
type ListQuery ¶
type ListQuery struct {
Limit int
Offset int
Search string
Filters Filters
Sort []SortField
Raw url.Values
// contains filtered or unexported fields
}
ListQuery captures pagination, search, and filter inputs from a request.
func ParseListQuery ¶
func ParseListQuery(r *http.Request, cfg ListQueryConfig) ListQuery
ParseListQuery parses pagination and filters from the HTTP request according to cfg. It preserves the v2-compatible single-return shape; callers that need validation errors should use ParseListQueryChecked.
func ParseListQueryChecked ¶ added in v2.1.0
func ParseListQueryChecked(r *http.Request, cfg ListQueryConfig) (ListQuery, error)
ParseListQueryChecked parses pagination and filters from the HTTP request and returns field-level validation errors.
func (ListQuery) MissingRequired ¶
MissingRequired returns filter keys that were required but absent.
type ListQueryConfig ¶
type ListQueryConfig struct {
DefaultLimit int
MaxLimit int
AllowedFilters []string
Required []string
SearchParam string
SortParam string
AllowedSorts []string
DefaultSort []SortField
// FilterParser overrides the default filter parser when set.
FilterParser func(values url.Values, cfg ListQueryConfig) Filters
// SortParser overrides the default sort parser when set.
SortParser func(values url.Values, cfg ListQueryConfig) []SortField
}
ListQueryConfig configures parsing behaviour for list endpoints.
type ListResponse ¶
ListResponse wraps list results with metadata.
func NewListResponse ¶
func NewListResponse[T any](items []T, total int, query ListQuery) ListResponse[T]
NewListResponse constructs a ListResponse with paging metadata.
type SortField ¶
SortField describes a field and direction used for ordering results.
func DefaultSortParser ¶
func DefaultSortParser(values url.Values, cfg ListQueryConfig) []SortField
DefaultSortParser implements the toolkit's comma-delimited sort syntax. It preserves the v2-compatible single-return shape; callers that need validation errors should use DefaultSortParserChecked.
func DefaultSortParserChecked ¶ added in v2.1.0
func DefaultSortParserChecked(values url.Values, cfg ListQueryConfig) ([]SortField, fielderrors.FieldErrors)
DefaultSortParserChecked implements the toolkit's comma-delimited sort syntax and returns unsupported-sort validation errors.
Source Files