Documentation
¶
Overview ¶
Package list reads what a list route was asked for: a page (limit and offset, capped), a search, a time range, a sort among the allowed keys and equality filters, from the query string, validated, so a handler passes them to its query and nothing it did not allow reaches SQL.
p, err := list.Read(req, list.Options{
Sorts: []string{"createdAt", "title"}, // the first is the default
Desc: true, // newest first unless asked
Filters: []string{"status"},
})
if err != nil {
return out, err // 422 with the field at fault
}
rows, err := q.ListPosts(ctx, queries.ListPostsParams{
Q: p.Search(), Since: p.Since, Until: p.Until, Status: p.Filter("status"),
Sort: p.Sort, Desc: p.Desc, Lim: p.Limit, Off: p.Offset,
})
The query string: limit, offset, q, since and until (an instant, "2026-10-06T00:00:00Z", or a day, "2026-10-06", read as midnight UTC; pages send instants from the visitor's zone), sort (one of Sorts), order ("asc" or "desc"), and one parameter per filter.
Index ¶
Constants ¶
const ( HighlightStart = "\x02" HighlightStop = "\x03" )
HighlightStart and HighlightStop mark the matched words in the headline the generated highlight queries return (ts_headline's StartSel and StopSel): control characters, never markup, so the text of a row stays text.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// Limit is the page size when the query names none (50); MaxLimit
// caps what it may ask for (200).
Limit, MaxLimit int
// Sorts are the keys the list may be sorted by; the first is the
// default. Empty: no sort parameter is accepted.
Sorts []string
// Desc is the default order.
Desc bool
// Filters are the query parameters taken as equality filters.
Filters []string
// MaxSearch bounds the search text (200 characters).
MaxSearch int
}
Options say what a list route accepts.
type Page ¶
type Page[T any] struct { Items []T `json:"items"` Total int `json:"total"` Limit int `json:"limit"` Offset int `json:"offset"` }
Page is a page of a list: the items, the total that match, and the page asked for, so a pager knows where it is.
type Params ¶
type Params struct {
Limit, Offset int32
// Q is the search, trimmed; "" for none.
Q string
// Since and Until bound the time range, Until exclusive; nil for open.
Since, Until *time.Time
// Sort is one of Options.Sorts; Desc the order.
Sort string
Desc bool
// Filters holds the filters the request set.
Filters map[string]string
}
Params are what the request asked for, validated.
func Read ¶
Read validates the list parameters of req: an unknown sort, a bad number or time, a range that ends before it starts, or a search too long is a 422 naming the parameter (validate.Errors, as for a body).
Source Files