paging

Documentation

Index

• func NewToken(cipherKey TokenCipherKey, v any) (string, error)
• func ParseToken(cipherKey TokenCipherKey, encoded string, v any) error
• type FetchFunc
• type Iterator
  • func NewIterator[T any](fetchFunc FetchFunc[T], opts ...IteratorOption) *Iterator[T]
  • func (i *Iterator[T]) HasNext() bool
  • func (i *Iterator[T]) Next() (T, error)
• type IteratorOption
  • func WithIteratorPageSize(size int) IteratorOption
  • func WithIteratorPageToken(token string) IteratorOption
  • func WithIteratorReverse(isReverse bool) IteratorOption
• type Option
  • func WithLimit(limit int) Option
  • func WithPageToken(token string) Option
• type Options
  • func (o Options) HasPageToken() bool
  • func (o Options) Limit() int
  • func (o Options) PageToken() string
• type Page
• type TokenCipherKey

Functions

func NewToken

func NewToken(cipherKey TokenCipherKey, v any) (string, error)

NewToken creates a new token from the given value. The value `v` represents the query parameters the caller is executing against its persistence storage.

Moreover, tokens should replace any query parameters if present to avoid inconsistencies when querying pages using tokens.

It is important to make sure that `v` is serializable (fields are exported and serializable as well).

Use ParseToken to parse the token back into the value.

func ParseToken

func ParseToken(cipherKey TokenCipherKey, encoded string, v any) error

ParseToken parses the given token into the given value.

Use NewToken to create a token from a value.

Types

type FetchFunc

type FetchFunc[T any] func(opts ...Option) (*Page[T], error)

FetchFunc is a function type that defines how to fetch a page of items.

type Iterator

type Iterator[T any] struct {
	// contains filtered or unexported fields
}

Iterator is a generic iterator for paginated data. It fetches data using a provided FetchFunc and allows iteration over the items. The iterator supports both forward and reverse pagination, controlled by the WithIteratorReverse option.

Usage example: ```go ctx := context.Background()

fetchFunc := func(opts ...paging.Option) (*paging.Page[YourType], error) {
    // Implement your fetching logic here, e.g., querying a database or an API.
    return yourPage, nil
}

iterator := paging.NewIterator(ctx, fetchFunc,

paging.WithIteratorPageSize(50), // Optional: set custom page size
paging.WithIteratorReverse(false), // Optional: set reverse pagination
paging.WithIteratorPageToken("your-page-token"), // Optional: set initial page token

)

for iterator.HasNext() {
    item, err := iterator.Next()
    if err != nil {
        if err == io.EOF {
            break // No more items to iterate
        }
        // Handle other errors
        panic(err)
    }
    // Process the item
    fmt.Println(item)
}

The iterator will automatically handle pagination, fetching new pages as needed. The items are returned in the order they are fetched, and the iterator will stop when there are no more items to fetch.

func NewIterator

func NewIterator[T any](fetchFunc FetchFunc[T], opts ...IteratorOption) *Iterator[T]

NewIterator creates a new Iterator instance with the provided fetch function and options.

func (*Iterator[T]) HasNext

func (i *Iterator[T]) HasNext() bool

HasNext checks if there are more items to iterate over.

func (*Iterator[T]) Next

func (i *Iterator[T]) Next() (T, error)

Next retrieves the next item from the iterator.

type IteratorOption

type IteratorOption func(*iteratorOptions)

func WithIteratorPageSize

func WithIteratorPageSize(size int) IteratorOption

WithIteratorPageSize sets the page size for the iterator.

func WithIteratorPageToken

func WithIteratorPageToken(token string) IteratorOption

WithIteratorPageToken sets the initial page token for the iterator.

func WithIteratorReverse

func WithIteratorReverse(isReverse bool) IteratorOption

WithIteratorReverse sets whether the iterator should fetch items in reverse order.

type Option

type Option func(*Options)

Option represents an option for pagination.

func WithLimit

func WithLimit(limit int) Option

WithLimit sets the maximum number of items to return.

func WithPageToken

func WithPageToken(token string) Option

WithPageToken sets the page token to use for pagination.

type Options

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

Options represents the options for pagination.

func (Options) HasPageToken

func (o Options) HasPageToken() bool

HasPageToken returns true if the page token is set.

func (Options) Limit

func (o Options) Limit() int

Limit returns the limit option.

func (Options) PageToken

func (o Options) PageToken() string

PageToken returns the page token option.

type Page

type Page[T any] struct {
	TotalItems        int
	PreviousPageToken string
	NextPageToken     string
	Items             []T
}

Page is a segment of data retrieved from a source (i.e. persistence stores).

As in books, sources using Page may allow callers to retrieve a certain part of their whole data set. This also allows callers to fetch previous or following results easily.

type TokenCipherKey

type TokenCipherKey []byte

TokenCipherKey is a type alias for a byte slice representing the cipher key used for encrypting and decrypting tokens. It is used to ensure that the cipher key is of the correct type when passed to functions that handle token encryption and decryption.

The cipher key must be 16, 24, or 32 bytes long, depending on the encryption algorithm used.

A separate type is defined so developers can easily inject the cipher key into the application configuration, ensuring that it is used consistently across the application.