Documentation
¶
Overview ¶
Package query provides the response envelope for paginated list endpoints: Result[T] carries the page's items plus the total count, the page/rows echoed back, and the derived TotalPages and Prev/Next page numbers. It implements rest.ResponseEncoder, so a handler returns it directly.
Usage ¶
pg, err := page.Parse(q.Get("page"), q.Get("rows"))
if err != nil {
return errs.New(errs.InvalidArgument, err)
}
items, err := core.Query(ctx, pg) // one page
total, err := core.Count(ctx) // full count
return query.NewResult(toDTOs(items), total, pg)
// -> {items,total,page,rowsPerPage,totalPages,prev?,next?}
When the items must also be localized by the translation middleware, embed Result in a type that implements translation.TranslatableList over its Items (the middleware translates in place before Encode runs).
Variants ¶
- Result[T]: plain JSON envelope {items,total,page,rowsPerPage,totalPages,prev?,next?} (offset). prev/next are page numbers, omitted when there is no previous/next page.
- CursorResult[T]: cursor (keyset) variant {items,next,prev}, paired with page.Cursor, for stable/efficient paging over large sets.
Both implement rest.ResponseEncoder. For a JSON:API list, tag the item DTO with github.com/hashicorp/jsonapi tags and return to.JSONAPI(items) instead — the jsonapi package assembles the document.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CursorResult ¶
type CursorResult[T any] struct { Items []T `json:"items"` Next string `json:"next,omitempty"` Prev string `json:"prev,omitempty"` }
CursorResult is the cursor-paginated counterpart of Result: the page's items plus opaque cursors (page.EncodeCursor) for the next and previous pages, empty when there is no such page. It implements rest.ResponseEncoder. Use it with page.Cursor when offset paging is too costly or unstable under inserts.
func NewCursorResult ¶
func NewCursorResult[T any](items []T, next, prev string) CursorResult[T]
NewCursorResult builds a cursor result. next/prev are opaque tokens from page.EncodeCursor (pass "" when there is no next/previous page).
type Result ¶
type Result[T any] struct { Items []T `json:"items"` Total int `json:"total"` Page int `json:"page"` RowsPerPage int `json:"rowsPerPage"` TotalPages int `json:"totalPages"` Prev int `json:"prev,omitempty"` Next int `json:"next,omitempty"` }
Result is the response envelope for a paginated list query. It implements the rest.ResponseEncoder interface (Encode), so a handler can return it directly. T is the item DTO type.
TotalPages is the number of pages the total spans at this page size (zero when there are no rows). Prev/Next are the adjacent page numbers, each zero (and omitted from JSON) when there is no such page — so a client can render previous/next links without recomputing the page math.
Source Files