pagination

Documentation

Index

• Constants
• type Cursor
• type Direction
• type FilterQuery
  • func CreateFilterQuery(s string) (*FilterQuery, error)
• type Key
• type KeyType
  • func (kt KeyType) Validate() error
• type KeyTypes
  • func (kt KeyTypes) Validate() error
• type Option
  • func EndingBefore(cursor Cursor) Option
  • func Filter(filter string) Option
  • func Limit(limit int) Option
  • func SortKey(key Key) Option
  • func SortOrder(order Order) Option
  • func StartingAfter(cursor Cursor) Option
• type Order
  • func (o Order) Validate() error
• type PageableType
• type Paginator
  • func ApplyOptions(options ...Option) (*Paginator, error)
  • func NewPaginatorFromQuery(query url.Values, defaultOptions ...Option) (*Paginator, error)
  • func NewPaginatorFromRequest(r *http.Request, defaultOptions ...Option) (*Paginator, error)
  • func (p *Paginator) AdvanceCursor(rf ResponseFields) bool
  • func (p Paginator) GetCursor() Cursor
  • func (p Paginator) GetLimit() int
  • func (p Paginator) GetOptions() []Option
  • func (p Paginator) GetVersion() Version
  • func (p Paginator) HasResultType() bool
  • func (p Paginator) IsForward() bool
  • func (p Paginator) Query() url.Values
  • func (p Paginator) Validate() error
  • func (p Paginator) ValidateCursor(c Cursor) error
• type ResponseFields
• type Version
  • func (v Version) Validate() error

Constants

const DefaultLimit = 50

DefaultLimit is the default pagination limit, appropriate for a UI query

const MaxLimit = 1500

MaxLimit is (at the moment) fairly arbitrarily chosen and limits results in a single call. This protects the server/DB from trying to process too much data at once

const TimestampKeyTypeLayout = "2006-01-02 15:04:05"

TimestampKeyTypeLayout represents the supported format for TimestampKeyType

Types

type Cursor

type Cursor string

Cursor is an opaque string that represents a place to start iterating from.

const (
	CursorBegin Cursor = ""    // Default cursor value which indicates the beginning of a collection
	CursorEnd   Cursor = "end" // Special cursor value which indicates the end of the collection
)

Cursor sentinel values.

type Direction

type Direction int

Direction indicates that results should be fetched forward through the view starting after the cursor (not including the cursor), or backward up to (but not including) the cursor.

const (
	DirectionForward  Direction = 0 // Default
	DirectionBackward Direction = 1
)

Direction can either be forward or backward.

type FilterQuery

type FilterQuery struct {
	// contains filtered or unexported fields
}

FilterQuery represents a parsed query tree for a filter query

func CreateFilterQuery

func CreateFilterQuery(s string) (*FilterQuery, error)

CreateFilterQuery creates a parsed filter query from a filter string

type Key

type Key string

Key is a comma-separated list of fields in the collection in which a view can be sorted

type KeyType

type KeyType string

KeyType represents the type of a key; cursor keys, ordering keys, and filter keys must all be of a supported type

const (
	BoolKeyType      KeyType = "Boolean"
	StringKeyType    KeyType = "String"
	TimestampKeyType KeyType = "Timestamp"
	UUIDKeyType      KeyType = "UUID"
)

Valid KeyTypes

func (KeyType) Validate

func (kt KeyType) Validate() error

Validate implements the Validatable interface

type KeyTypes

type KeyTypes map[string]KeyType

KeyTypes is a map from pagination keys to their associated KeyTypes

func (KeyTypes) Validate

func (kt KeyTypes) Validate() error

Validate implements the Validatable interface

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option defines a method of passing optional args to paginated List APIs

func EndingBefore

func EndingBefore(cursor Cursor) Option

EndingBefore iterates the collection's values before (but not including) the value at the cursor. It is commonly used to implement "Prev" functionality.

func Filter

func Filter(filter string) Option

Filter specifies a filter clause to use in the pagination query.

A filter query must either be:

1. A LEAF query, consisting of a key, operator, and value, formatted like:

   ('KEY',OPERATOR,'VALUE')

2. A NESTED query, formatted like:

   (FILTER_QUERY)

3. A COMPOSITE query, formatted like:

   (FILTER_QUERY,OPERATOR,FILTER_QUERY)

   For NESTED and COMPOSITE queries, FILTER_QUERY can be a LEAF, NESTED, or COMPOSITE query.

For LEAF queries, KEY must be a valid result type key for type of the result being returned. Valid keys are stored in a KeyTypes map in a configured paginator, mapping a key name to a KeyType. Supported KeyTypes include:

BoolKeyType      (value may be specified as any string that can be parsed by https://pkg.go.dev/strconv#example-ParseBool)
StringKeyType    (string value can only have single-quotes or double-quotes in the string that are escaped with a
                  back-slash (i.e., \' or \"))
TimestampKeyType (must conform to the format "2006-01-02 15:04:05", as defined in pagination.TimestampKeyLayout)
UUIDKeyType      (must be a valid string representation of a UUID)

By default, all result types support "id" as a valid key of KeyType UUIDKeyType. New supported keys can be added to a result type by defining the GetPaginationKeys() method of the PageableType interface for the result type, adding the keys and associated KeyType for each key that is supported.

For a LEAF query, the OPERATOR must either be a COMPARISON operator or a PATTERN operator.

COMPARISON operators include:

  EQ  // =
  GE  // >=
  GT  // >
  LE  // <=
  LT  // <
  NE  // !=

  All supported KeyTypes support COMPARISON operators.

PATTERN operators include:

  LK  // LIKE
  NL  // NOT LIKE

  Only StringKeyType keys support PATTERN operators. For a PATTERN operator, % matches 0 or more characters. _
  matches any single character. To match the % or _ characters, the character must be escaped with a \ in the
  value (i.e., '\%' matches the '%' character, and '\_' matches '_').

For a COMPOSITE query, the OPERATOR must be a LOGICAL operator.

LOGICAL operators include:

  AND // AND
  OR  // OR

func Limit

func Limit(limit int) Option

Limit specifies how many results to fetch at once. If unspecified, the default limit will be used.

func SortKey

func SortKey(key Key) Option

SortKey optionally specifies which field of the collection should be used to sort results in the view.

func SortOrder

func SortOrder(order Order) Option

SortOrder optionally specifies which way a view on a collection should be sorted.

func StartingAfter

func StartingAfter(cursor Cursor) Option

StartingAfter iterates the collection starting after (but not including) the value at the cursor. It can be used to fetch the "current" page starting at a cursor, as well as to iterate the next page by passing in the cursor of the last item on the page.

type Order

type Order string

Order is a direction in which a view on a collection can be sorted, mapping to ASC/DESC in SQL.

const (
	OrderAscending  Order = "ascending" // Default
	OrderDescending Order = "descending"
)

Order can be either ascending or descending.

func (Order) Validate

func (o Order) Validate() error

Validate implements the Validatable interface for the Order type

type PageableType

type PageableType interface {
	GetPaginationKeys() KeyTypes
}

PageableType is an interface that should be implemented for result types for which we want to iterate or filter based on more than the default id UUID column

type Paginator

type Paginator struct {
	// contains filtered or unexported fields
}

Paginator represents a configured paginator, based on a set of Options and defaults derived from those options

func ApplyOptions

func ApplyOptions(options ...Option) (*Paginator, error)

ApplyOptions initializes and validates a Paginator from a series of Option objects

func NewPaginatorFromQuery

func NewPaginatorFromQuery(query url.Values, defaultOptions ...Option) (*Paginator, error)

NewPaginatorFromQuery applies any default options and any additional options from parsing the query to produce a Paginator instance, validates that instance, and returns it if valid

func NewPaginatorFromRequest

func NewPaginatorFromRequest(r *http.Request, defaultOptions ...Option) (*Paginator, error)

NewPaginatorFromRequest calls NewPaginatorFromQuery, passing in the URL query from the request and any specified default pagination options

func (*Paginator) AdvanceCursor

func (p *Paginator) AdvanceCursor(rf ResponseFields) bool

AdvanceCursor will advance the currrent cursor based on the direction of iteration; if we are moving forward, it will use the next cursor if one exists, or otherwise will attempt to use the prev cursor. True is returned if we were able to advance in the desired direction.

func (Paginator) GetCursor

func (p Paginator) GetCursor() Cursor

GetCursor returns the current Cursor

func (Paginator) GetLimit

func (p Paginator) GetLimit() int

GetLimit returns the specified limit

func (Paginator) GetOptions

func (p Paginator) GetOptions() []Option

GetOptions returns the underlying options used to initialize the paginator

func (Paginator) GetVersion

func (p Paginator) GetVersion() Version

GetVersion returns the version of the pagination request

func (Paginator) HasResultType

func (p Paginator) HasResultType() bool

HasResultType returns true if the result type has been provided

func (Paginator) IsForward

func (p Paginator) IsForward() bool

IsForward returns true if the paginator is configured to page forward

func (Paginator) Query

func (p Paginator) Query() url.Values

Query converts the paginator settings into HTTP GET query parameters.

func (Paginator) Validate

func (p Paginator) Validate() error

Validate implements the Validatable interface for the Paginator type

func (Paginator) ValidateCursor

func (p Paginator) ValidateCursor(c Cursor) error

ValidateCursor validates the passed in Cursor, making sure that each key:value pair key is unique and supported, and that the associated value is valid

type ResponseFields

type ResponseFields struct {
	HasNext bool   `json:"has_next"`
	Next    Cursor `json:"next,omitempty"`
	HasPrev bool   `json:"has_prev"`
	Prev    Cursor `json:"prev,omitempty"`
}

ResponseFields represents pagination-specific fields present in every response.

type Version

type Version int

Version represents the version of the pagination request and reply wire format. It will be incremented any time that the wire format has changed.

const (
	Version2 Version = 2 // cursor format is "key1:id1,...,keyN:idN"
	Version3 Version = 3 // filter option now supported in client
)

Supported pagination versions

const (
	Version1 Version = 1 // cursor format is "id"
)

Deprecated pagination versions

func (Version) Validate

func (v Version) Validate() error

Validate implements the Validatable interface for the Version type