API Reference

Constants

const (
    DefaultPage       = 1
    DefaultSize       = 10
    MaxSize           = 1000
    DefaultCursorSize = 10
    MaxCursorSize     = 1000
)

Sort

Types

type Direction string

const (
    ASC  Direction = "asc"
    DESC Direction = "desc"
)

type Sort struct {
    Field     string
    Direction Direction
}

Functions

Function	Signature	Description
`ParseSort`	`(raw string) *Sort`	Parse a single `"field,direction"` string
`ParseSorts`	`(raw []string) []Sort`	Parse multiple sort strings
`Sort.String`	`() string`	Returns `"field,direction"` format

PageRequest

Type

type PageRequest struct {
    Page int
    Size int
    Sort []Sort
}

Constructors

Function	Signature	Description
`NewPageRequest`	`(page, size int, sort []Sort) PageRequest`	Create with clamping
`PageRequestFromQuery`	`(values url.Values) PageRequest`	Parse from query params

Methods

Method	Signature	Description
`Offset`	`() int`	`(Page - 1) * Size`
`Limit`	`() int`	Returns `Size`
`SortableFields`	`(fields ...string) PageRequest`	Whitelist sort fields
`MapSortFields`	`(fieldMap map[string]string) PageRequest`	Map user-facing field names to database columns
`WithDefaultSort`	`(sorts ...Sort) PageRequest`	Set fallback sort
`OrderBy`	`() string`	`"field dir, field dir"`

Page[T]

Types

type Page[T any] struct {
    Items    []T          `json:"items"`
    Metadata PageMetadata `json:"metadata"`
}

type PageMetadata struct {
    Page       int   `json:"page"`
    Size       int   `json:"size"`
    TotalItems int64 `json:"totalItems"`
    TotalPages int   `json:"totalPages"`
}

Functions

Function	Signature	Description
`NewPage`	`(items []T, request PageRequest, totalItems int64) Page[T]`	Create with computed metadata
`EmptyPage`	`(request PageRequest) Page[T]`	Create empty page with zero results

CursorRequest

Type

type CursorRequest struct {
    Cursor string
    Size   int
    Sort   []Sort
}

Constructors

Function	Signature	Description
`NewCursorRequest`	`(cursor string, size int, sort []Sort) CursorRequest`	Create with clamping
`CursorRequestFromQuery`	`(values url.Values) CursorRequest`	Parse from query params

Methods

Method	Signature	Description
`Limit`	`() int`	Returns `Size + 1` (fetch extra to detect hasNext)
`HasCursor`	`() bool`	True if cursor is non-empty
`DecodedCursor`	`() (CursorData, error)`	Decode the cursor token
`SortableFields`	`(fields ...string) CursorRequest`	Whitelist sort fields
`MapSortFields`	`(fieldMap map[string]string) CursorRequest`	Map user-facing field names to database columns
`WithDefaultSort`	`(sorts ...Sort) CursorRequest`	Set fallback sort
`OrderBy`	`() string`	`"field dir, field dir"`

CursorPage[T]

Types

type CursorPage[T any] struct {
    Items    []T                `json:"items"`
    Metadata CursorPageMetadata `json:"metadata"`
}

type CursorPageMetadata struct {
    NextCursor string `json:"nextCursor"`
    PrevCursor string `json:"prevCursor"`
    HasNext    bool   `json:"hasNext"`
    HasPrev    bool   `json:"hasPrev"`
    Size       int    `json:"size"`
}

Functions

Function	Signature	Description
`NewCursorPage`	`(items []T, nextCursor, prevCursor string, hasNext, hasPrev bool, size int) CursorPage[T]`	Create cursor page
`EmptyCursorPage`	`(size int) CursorPage[T]`	Create empty cursor page

Cursor Encoding

Types

type CursorDirection string

const (
    Next CursorDirection = "next"
    Prev CursorDirection = "prev"
)

type CursorData struct {
    Value     string            `json:"v"`
    Direction CursorDirection   `json:"d"`
    Extra     map[string]string `json:"e"`
}

Functions

Function	Signature	Description
`EncodeCursor`	`(data CursorData) (string, error)`	Encode to base64 URL-safe token
`DecodeCursor`	`(cursor string) (CursorData, error)`	Decode from base64 token