paging

Documentation

Index

• func Boundary_FindFunc[T any](b Boundary, in []T, get func(T) string) int
• func EmptyResponse() *apimodel.PageableResponse
• func PackageResponse(params ResponseParams) *apimodel.PageableResponse
• func Page_PageFunc[WithID any](p *Page, in []WithID, get func(WithID) string) []WithID
• func ParseLimit(c *gin.Context, min, max, _default int) (int, gtserror.WithCode)
• type Boundary
  • func EitherMinID(minID, sinceID string) Boundary
  • func MaxID(maxID string) Boundary
  • func MaxShortcodeDomain(max string) Boundary
  • func MinID(minID string) Boundary
  • func MinShortcodeDomain(min string) Boundary
  • func SinceID(sinceID string) Boundary
  • func (b Boundary) Find(in []string) int
• type Order
  • func (i Order) Ascending() bool
  • func (i Order) Descending() bool
  • func (i Order) String() string
• type Page
  • func ParseIDPage(c *gin.Context, min, max, _default int) (*Page, gtserror.WithCode)
  • func ParseShortcodeDomainPage(c *gin.Context, min, max, _default int) (*Page, gtserror.WithCode)
  • func (p *Page) GetLimit() int
  • func (p *Page) GetMax() string
  • func (p *Page) GetMin() string
  • func (p *Page) GetOrder() Order
  • func (p *Page) Next(lo, hi string) *Page
  • func (p *Page) Page(in []string) []string
  • func (p *Page) Prev(lo, hi string) *Page
  • func (p *Page) ToLink(proto, host, path string, queryParams url.Values) string
  • func (p *Page) ToLinkURL(proto, host, path string, queryParams url.Values) *url.URL
• type ResponseParams

Functions

func Boundary_FindFunc

func Boundary_FindFunc[T any](b Boundary, in []T, get func(T) string) int

Boundary_FindFunc is functionally equivalent to Boundary{}.Find() but for an arbitrary type with ID. Note: this is not a Boundary{} method as Go generics are not supported in method receiver functions.

func EmptyResponse

func EmptyResponse() *apimodel.PageableResponse

EmptyResponse just returns an empty PageableResponse with no link header or items.

func PackageResponse

func PackageResponse(params ResponseParams) *apimodel.PageableResponse

PackageResponse is a convenience function for returning a bunch of pageable items (notifications, statuses, etc), as well as a Link header to inform callers of where to find next/prev items.

func Page_PageFunc

func Page_PageFunc[WithID any](p *Page, in []WithID, get func(WithID) string) []WithID

Page_PageFunc is functionally equivalent to Page{}.Page(), but for an arbitrary type with ID. Note: this is not a Page{} method as Go generics are not supported in method receiver functions.

func ParseLimit

func ParseLimit(c *gin.Context, min, max, _default int) (int, gtserror.WithCode)

ParseLimit parses the limit query parameter from a request context, returning BadRequest on error parsing and _default if zero limit given.

Types

type Boundary

type Boundary struct {
	Name  string // i.e. query key
	Value string
	Order Order // NOTE: see Order type for explanation
}

Boundary represents the upper or lower limit in a page slice.

func EitherMinID

func EitherMinID(minID, sinceID string) Boundary

EitherMinID returns an ID boundary with given min ID value, using either the `since_id`,"DESC" name,ordering or `min_id`,"ASC" name,ordering depending on which is set.

func MaxID

func MaxID(maxID string) Boundary

MaxID returns an ID boundary with given max ID value, and the "max_id" query key set.

func MaxShortcodeDomain

func MaxShortcodeDomain(max string) Boundary

MaxShortcodeDomain returns a boundary with the given maximum emoji shortcode@domain, and the "max_shortcode_domain" query key set.

func MinID

func MinID(minID string) Boundary

MinID ...

func MinShortcodeDomain

func MinShortcodeDomain(min string) Boundary

MinShortcodeDomain returns a boundary with the given minimum emoji shortcode@domain, and the "min_shortcode_domain" query key set.

func SinceID

func SinceID(sinceID string) Boundary

SinceID ...

func (Boundary) Find

func (b Boundary) Find(in []string) int

Find finds the boundary's set value in input slice, or returns -1.

type Order

type Order int

Order represents the order an input page should be sorted and paged in.

NOTE: this does not effect the order of returned API results, which must always be in descending order. This behaviour is confusing, but we adopt it to stay inline with Mastodon API expectations.

const (
	OrderDescending Order
	OrderAscending
)

func (Order) Ascending

func (i Order) Ascending() bool

Ascending returns whether this Order is ascending.

func (Order) Descending

func (i Order) Descending() bool

Descending returns whether this Order is descending.

func (Order) String

func (i Order) String() string

String returns a string representation of Order.

type Page

type Page struct {
	// Min is the Page's lower limit value.
	Min Boundary

	// Max is this Page's upper limit value.
	Max Boundary

	// Limit will limit the returned
	// page of items to at most 'limit'.
	Limit int
}

func ParseIDPage

func ParseIDPage(c *gin.Context, min, max, _default int) (*Page, gtserror.WithCode)

ParseIDPage parses an ID Page from a request context, returning BadRequest on error parsing. The min, max and default parameters define the page size limit minimum, maximum and default value, where a non-zero default will enforce paging for the endpoint on which this is called. While conversely, a zero default limit will not enforce paging, returning a nil page value.

func ParseShortcodeDomainPage

func ParseShortcodeDomainPage(c *gin.Context, min, max, _default int) (*Page, gtserror.WithCode)

ParseShortcodeDomainPage parses an emoji shortcode domain Page from a request context, returning BadRequest on error parsing. The min, max and default parameters define the page size limit minimum, maximum and default value where a non-zero default will enforce paging for the endpoint on which this is called. While conversely, a zero default limit will not enforce paging, returning a nil page value.

func (*Page) GetLimit

func (p *Page) GetLimit() int

GetLimit is a small helper function to return limit (checking for nil page and unusable limit).

func (*Page) GetMax

func (p *Page) GetMax() string

GetMax is a small helper function to return maximum boundary value (checking for nil page).

func (*Page) GetMin

func (p *Page) GetMin() string

GetMin is a small helper function to return minimum boundary value (checking for nil page).

func (*Page) GetOrder

func (p *Page) GetOrder() Order

GetOrder is a small helper function to return page sort ordering (checking for nil page).

func (*Page) Next

func (p *Page) Next(lo, hi string) *Page

Next creates a new instance for the next returnable page, using given max value. This preserves original limit and max key name.

func (*Page) Page

func (p *Page) Page(in []string) []string

Page will page the given slice of input according to the receiving Page's minimum, maximum and limit. NOTE: input slice MUST be sorted according to the order is expected to be paged in, i.e. it is currently sorted according to Page.Order(). Sorted data isn't always according to string inequalities so this CANNOT be checked here.

func (*Page) Prev

func (p *Page) Prev(lo, hi string) *Page

Prev creates a new instance for the prev returnable page, using given min value. This preserves original limit and min key name.

func (*Page) ToLink

func (p *Page) ToLink(proto, host, path string, queryParams url.Values) string

ToLink performs ToLinkURL() and calls .String() on the resulting URL.

func (*Page) ToLinkURL

func (p *Page) ToLinkURL(proto, host, path string, queryParams url.Values) *url.URL

ToLink builds a URL link for given endpoint information and extra query parameters, appending this Page's minimum / maximum boundaries and available limit (if any).

type ResponseParams

type ResponseParams struct {
	Items []interface{} // Sorted slice of items (statuses, notifications, etc)
	Path  string        // path to use for next/prev queries in the link header
	Next  *Page         // page details for the next page
	Prev  *Page         // page details for the previous page
	Query url.Values    // any extra query parameters to provide in the link header, should be in the format 'example=value'
}

ResponseParams models the parameters to pass to PageableResponse.

The given items will be provided in the paged response.

The other values are all used to create the Link header so that callers know which endpoint to query next and previously in order to do paging.