Documentation
¶
Overview ¶
Package query provides the response envelopes for list and single-object endpoints. Every envelope shares the house shape — an "error_code" and a "data" object — so clients parse one structure across all endpoints:
list: {"error_code":"ok","data":{"items":[...],"pagination":{"total_pages":..,"current_page":..,"limit":..,"total_items":..}}}
single: {"error_code":"ok","data":{...}}
Result[T] (list) and ResultItem[T]/CursorResult[T] all implement rest.ResponseEncoder, so a handler returns them 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)
// -> {error_code, data:{items, pagination}}
one, err := core.QueryByID(ctx, id)
return query.NewResultItem(toDTO(one)) // -> {error_code, data:{...}}
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]: offset list envelope {error_code, data:{items, pagination}}, where pagination is {total_pages, current_page, limit, total_items}.
- ResultItem[T]: single-object envelope {error_code, data:{...}}.
- CursorResult[T]: cursor (keyset) list envelope {error_code, data:{items, next?, prev?}}, paired with page.Cursor, for stable/efficient paging over large sets. next/prev are opaque tokens, omitted when there is no such page.
- ResultJSONAPI[T]: JSON:API list document (application/vnd.api+json) with the pagination under meta.pagination {page, size, total_pages, total_results}. T is a pointer to a github.com/hashicorp/jsonapi-tagged DTO. Use this for a paginated JSON:API list; for a single JSON:API resource without pagination, use to.JSONAPI instead.
All implement rest.ResponseEncoder.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type CursorData ¶ added in v0.6.0
type CursorData[T any] struct { Items []T `json:"items"` Next string `json:"next,omitempty"` Prev string `json:"prev,omitempty"` }
CursorData is the payload of a cursor-paginated list envelope: the page's items plus opaque next/prev cursors (empty when there is no such page).
type CursorResult ¶
type CursorResult[T any] struct { ErrorCode string `json:"error_code"` Data CursorData[T] `json:"data"` }
CursorResult is the cursor-paginated counterpart of Result: the same {error_code, data} envelope, with data carrying the items and opaque cursors (page.EncodeCursor) for the next and previous pages. 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 envelope. next/prev are opaque tokens from page.EncodeCursor (pass "" when there is no next/previous page).
type Data ¶ added in v0.6.0
type Data[T any] struct { Items []T `json:"items"` Pagination Pagination `json:"pagination"` }
Data is the payload of a paginated list envelope: the page's items and their pagination metadata.
type Pagination ¶ added in v0.6.0
type Pagination struct {
TotalPages int `json:"total_pages"`
CurrentPage int `json:"current_page"`
Limit int `json:"limit"`
TotalItems int `json:"total_items"`
}
Pagination is the offset-paging metadata embedded in a list envelope.
type PaginationJSONAPI ¶ added in v0.6.0
type PaginationJSONAPI struct {
Page int `json:"page"`
Size int `json:"size"`
TotalPages int `json:"total_pages"`
TotalResults int `json:"total_results"`
}
PaginationJSONAPI is the pagination metadata carried in a JSON:API document's top-level meta object (meta.pagination). Its keys intentionally differ from the plain Pagination envelope — this is the JSON:API convention (page/size).
type Result ¶
Result is the response envelope for a paginated list query: an error_code and a data object holding the items and their pagination. It implements the rest.ResponseEncoder interface (Encode), so a handler can return it directly. T is the item DTO type. The shape mirrors the house convention:
{"error_code":"ok","data":{"items":[...],"pagination":{"total_pages":..,"current_page":..,"limit":..,"total_items":..}}}
type ResultItem ¶ added in v0.6.0
ResultItem is the response envelope for a single-object query: an error_code and the object as data. It implements rest.ResponseEncoder (Encode). The shape is {"error_code":"ok","data":{...}}.
func NewResultItem ¶ added in v0.6.0
func NewResultItem[T any](data T) ResultItem[T]
NewResultItem wraps a single object in a data envelope with an ok error_code. Return it from get/create/update handlers so every endpoint shares the {error_code, data} shape.
type ResultJSONAPI ¶ added in v0.6.0
ResultJSONAPI is the JSON:API counterpart of Result: it renders the page's items as a JSON:API document (application/vnd.api+json) with the pagination in the top-level meta. It implements the rest.ResponseEncoder interface (Encode).
T must be a pointer to a struct tagged with github.com/hashicorp/jsonapi tags (`jsonapi:"primary,<type>"`, `jsonapi:"attr,<name>"`, ...); the jsonapi package assembles the document from those tags. For a single JSON:API resource without pagination, use to.JSONAPI instead.
func NewResultJSONAPI ¶ added in v0.6.0
func NewResultJSONAPI[T any](items []T, total int, pg page.Page) ResultJSONAPI[T]
NewResultJSONAPI builds a JSON:API list result from the page's items, the total row count, and the page request that produced them. The pagination lands in meta.pagination. When the total spans no pages (empty result), page and size report zero.
Source Files