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 Query, 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) IsCachable() 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 Query
• type QueryParams
  • func QueryParamsFromRequest(r *http.Request) QueryParams
• 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

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 (
	ArrayKeyType     KeyType = "Array"
	BoolKeyType      KeyType = "Boolean"
	IntKeyType       KeyType = "Int"
	StringKeyType    KeyType = "String"
	TimestampKeyType KeyType = "Timestamp"
	UUIDArrayKeyType KeyType = "UUIDArray"
	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,...,OPERATOR,FILTER_QUERY)

   The OPERATORs in a COMPOSITE query must be a LOGICAL OPERATOR. Note that if more than one LOGICAL OPERATOR is present in the COMPOSITE query, standard SQL precedence rules will be followed, with consecutive AND queries grouped together before OR queries. So the query (fee,OR,fie,AND,foe,AND,fum) would be executed as (fee,OR,(fie,AND,foe,AND,fum)).

   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:

ArrayKeyType     (must be a string value to be searched for in an array of strings)
BoolKeyType      (value may be specified as any string that can be parsed by https://pkg.go.dev/strconv#example-ParseBool)
IntKeyType       (must be a valid string representation of an int64)
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 (the number of microseconds since January 1, 1970 UTC)
UUIDArrayKeyType (must be a valid string representation of a UUID)
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 be an ARRAY operator, a COMPARISON operator, or a PATTERN operator.

ARRAY operators include:

	HAS // ANY

Only ArrayKeyType and UUIDArrayKeyType supports ARRAY operators.

COMPARISON operators include:

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

All supported KeyTypes other than ArrayKeyType and UUIDArrayKeyType 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 '_').

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 Query, 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, creating a PaginationQuery 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) IsCachable

func (p Paginator) IsCachable() bool

IsCachable returns true if the paginator is configured to be default and cached value can be returned

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 Query

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

Query is the interface needed by NewPaginatorFromQuery to create a Paginator

type QueryParams

type QueryParams struct {
	StartingAfter *string `description:"A cursor value after which the returned list will start" query:"starting_after"`
	EndingBefore  *string `description:"A cursor value before which the returned list will end" query:"ending_before"`
	Limit         *string `description:"The maximum number of results to be returned per page" query:"limit"`
	Filter        *string `description:"A filter clause to use in the pagination query" query:"filter"`
	SortKey       *string `description:"The field(s) used to sort the results" query:"sort_key"`
	SortOrder     *string `description:"The sort order for each field (ascending or descending)" query:"sort_order"`
	Version       *string `description:"The version of the API to be called" query:"version"`
}

QueryParams is a struct that implements PaginationQuery, which can be incorporated in other request structs for handlers that need to take pagination query parameters

func QueryParamsFromRequest

func QueryParamsFromRequest(r *http.Request) QueryParams

QueryParamsFromRequest creates a QueryParams struct from the query parameters in an http.Request

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