pagination

type AuthenticatedCursorEndpoint ¶

type AuthenticatedCursorEndpoint[P, F, M, A, T any] = authenticatedPageEndpoint[P, F, orm.CursorRequest[M], A, CursorResult[M, T], CursorResponse[T]]

AuthenticatedCursorEndpoint keeps cursor owner M, actor A and public DTO T distinct.

type AuthenticatedNumberedEndpoint ¶

type AuthenticatedNumberedEndpoint[P, F, A, T any] = authenticatedPageEndpoint[P, F, orm.PageRequest, A, orm.PageResult[T], NumberedResponse[T]]

AuthenticatedNumberedEndpoint supplies a concrete actor before a numbered page read.

type AuthenticatedSimpleEndpoint ¶

type AuthenticatedSimpleEndpoint[P, F, A, T any] = authenticatedPageEndpoint[P, F, orm.PageRequest, A, orm.SimplePage[T], SimpleResponse[T]]

AuthenticatedSimpleEndpoint is the count-free authenticated page contract.

type Config ¶

type Config struct {
	NumberParam, SizeParam   string
	DefaultSize, MaximumSize int
	MaximumPage              int
	Links                    LinkMode
	EdgeLinks                bool
	PageWindow               int
}

Config owns wire names, defaults and a maximum size no greater than the ORM's shared bound. Explicit names permit independent paginators without implicit bracket/nesting conventions. Values are rejected, never silently clamped. MaximumPage bounds numbered/simple offset depth so a client cannot request an arbitrarily expensive OFFSET; zero selects DefaultMaximumPage. Deeper pages fail query validation and navigation omits links beyond the bound. Use cursor pagination for unbounded traversal.

EdgeLinks adds first and, for numbered pages, last links. PageWindow lists up to that many numbered pages on each side of the current page with their links (at most MaximumPageWindow); simple pages have no count and ignore it. Both are off by default and absent from the wire when disabled.

func DefaultConfig() Config

func (c Config) Validate() error

type CursorConfig ¶

type CursorConfig struct {
	AfterParam, BeforeParam, SizeParam string
	DefaultSize, MaximumSize           int
	Links                              LinkMode
}

CursorConfig declares two exclusive directions and a bounded page size. The endpoint's ordinary total query-byte limit still applies to cursor tokens.

func DefaultCursorConfig() CursorConfig

func (c CursorConfig) Validate() error

type CursorEndpoint ¶

type CursorEndpoint[P, F, M, T any] = pageEndpoint[P, F, orm.CursorRequest[M], CursorResult[M, T], CursorResponse[T]]

CursorEndpoint preserves source owner M separately from public DTO T.

func DefineCursor[M, P, F, T any](route foundryhttp.Route[P], filters foundryhttp.Query[F], item contract.JSON[T], config CursorConfig, options ...foundryhttp.EndpointOption) CursorEndpoint[P, F, M, T]

type CursorMeta ¶

type CursorMeta struct {
	Size int `json:"per_page"`
}

CursorMeta reports page size only; cursor pagination does not count totals.

type CursorRequest ¶

type CursorRequest[P, F, M any] = pageRequest[P, F, orm.CursorRequest[M]]

CursorRequest retains the original model/projection owner in its ORM request. After and Before contain cursor positions, not credentials or authorization.

type CursorResponse ¶

type CursorResponse[T any] struct {
	Data  []T        `json:"data"`
	Meta  CursorMeta `json:"meta"`
	Links Links      `json:"links"`
}

CursorResponse contains explicit DTOs and source-owned navigation serialized through endpoint URLs. Its data is always an array; empty pages have no links.

type CursorResult ¶

type CursorResult[M, T any] struct {
	// contains filtered or unexported fields
}

CursorResult retains a source-owned navigation position alongside explicit DTO values. MapCursorPage is its constructor; the zero value is invalid. Its private metadata preserves the validated ORM result without retaining original model rows or manufacturing cursors for the DTO type.

func MapCursorPage[M, T any](ctx context.Context, page orm.CursorPage[M], mapper func(M) (T, error)) (CursorResult[M, T], error)

func (p CursorResult[M, T]) Items() []T

func (p CursorResult[M, T]) Next() value.Optional[orm.Cursor[M]]

func (p CursorResult[M, T]) Previous() value.Optional[orm.Cursor[M]]

func (p CursorResult[M, T]) Size() int

type LinkMode ¶

type LinkMode uint8

const (
	// RelativeLinks emits origin-relative URLs from the endpoint declaration.
	RelativeLinks LinkMode = iota + 1
	// PublicLinks uses the approved PublicURLs origin in the request context.
	PublicLinks
)

type Links ¶

type Links struct {
	Next     value.Nullable[string] `json:"next"`
	Previous value.Nullable[string] `json:"prev"`
	First    value.Optional[string] `json:"first,omitzero"`
	Last     value.Optional[string] `json:"last,omitzero"`
	Window   []PageLink             `json:"window,omitzero"`
}

Links contains optional next/previous URLs. A link is a navigation hint, not a guarantee that data will still exist when another request is executed. First, Last and Window are opt-in (Config.EdgeLinks, Config.PageWindow) and omitted from the wire when disabled; cursor pages never carry them. Last and Window need a count, so only numbered pages carry them. No link points beyond Config.MaximumPage.

type NumberedEndpoint ¶

type NumberedEndpoint[P, F, T any] = pageEndpoint[P, F, orm.PageRequest, orm.PageResult[T], NumberedResponse[T]]

NumberedEndpoint receives typed page input and expects an ORM page of explicit response DTOs. Handle supplies metadata and navigation before JSON encoding.

func DefineNumbered[P, F, T any](route foundryhttp.Route[P], filters foundryhttp.Query[F], item contract.JSON[T], config Config, options ...foundryhttp.EndpointOption) NumberedEndpoint[P, F, T]

type NumberedMeta ¶

type NumberedMeta struct {
	Number int   `json:"current_page"`
	Size   int   `json:"per_page"`
	Total  int64 `json:"total"`
	Pages  int64 `json:"last_page"`
}

NumberedMeta preserves the ORM's exact numbered-page metadata, including zero last_page for an empty count. Separate count/read operations are not a snapshot.

type NumberedResponse ¶

type NumberedResponse[T any] struct {
	Data  []T          `json:"data"`
	Meta  NumberedMeta `json:"meta"`
	Links Links        `json:"links"`
}

NumberedResponse contains explicit DTO values and shared page metadata.

type PageLink ¶

type PageLink struct {
	Number int    `json:"page"`
	URL    string `json:"url"`
}

PageLink is one numbered page around the current page, in ascending order.

type Parameters ¶

type Parameters[F any] = parameters[F, orm.PageRequest]

Parameters retains generated domain filters and the actual ORM request.

type Request ¶

type Request[P, F any] = pageRequest[P, F, orm.PageRequest]

Request is the thin domain-handler input, with concrete path/filter types. Page is usable directly by an ORM query's Paginate or SimplePaginate method.

type SimpleEndpoint ¶

type SimpleEndpoint[P, F, T any] = pageEndpoint[P, F, orm.PageRequest, orm.SimplePage[T], SimpleResponse[T]]

SimpleEndpoint is the corresponding count-free transport contract.

func DefineSimple[P, F, T any](route foundryhttp.Route[P], filters foundryhttp.Query[F], item contract.JSON[T], config Config, options ...foundryhttp.EndpointOption) SimpleEndpoint[P, F, T]

type SimpleMeta ¶

type SimpleMeta struct {
	Number  int  `json:"current_page"`
	Size    int  `json:"per_page"`
	HasMore bool `json:"has_more"`
}

SimpleMeta retains navigation information without claiming a total count.

type SimpleResponse ¶

type SimpleResponse[T any] struct {
	Data  []T        `json:"data"`
	Meta  SimpleMeta `json:"meta"`
	Links Links      `json:"links"`
}

SimpleResponse contains explicit DTO values and count-free metadata.