pagination

Documentation

Overview

Package pagination provides Relay style pagination.

Index

• Variables
• type Arguments
• type Cursor
  • func (c *Cursor) SetString(text string) (*Cursor, error)
  • func (c *Cursor) String() string
• type Item
• type PSQLPaginator
  • func (p PSQLPaginator[T]) ListItems(_ context.Context, paginationParams Arguments) (*Page[T], error)
• type Page
• type PageInfo
• type Paginator
• type Tabler

Variables

var (
	// ErrCursorFieldNotFound is returned when a cursor field is not found.
	ErrCursorFieldNotFound = errors.New("field not found")
	// ErrCursorInvalidValueType is returned when a cursor field is not of the correct type.
	ErrCursorInvalidValueType = errors.New("invalid value type")
)

var ErrInvalidCursor = errors.New("invalid Cursor")

ErrInvalidCursor is returned when the cursor is invalid.

Types

type Arguments

type Arguments struct {
	First *int
	After *string

	Last   *int
	Before *string
	// contains filtered or unexported fields
}

Arguments represents pagination arguments. The arguments can be used to paginate forward or backward.

To enable forward pagination, two arguments must be provided:

• first: the number of items to retrieve
• after: the cursor of the last item of the previous page

The server will return at most `first` items after the `after` cursor.

To enable backward pagination, two arguments must be provided:

• last: the number of items to retrieve
• before: the cursor of the first item of the previous page

The server will return at most `last` items before the `before` cursor.

The items may be ordered however the business logic dictates. The ordering may be determined based upon additional arguments given to each implementation.

type Cursor

type Cursor struct {
	ID        string
	CreatedAt time.Time
}

Cursor defines the fields used to compose a cursor.

func (*Cursor) SetString

func (c *Cursor) SetString(text string) (*Cursor, error)

SetString decodes the cursor from a base64 string.

func (*Cursor) String

func (c *Cursor) String() string

String returns the cursor fields encoded as a base64 string.

type Item

type Item[T any] struct {
	Item   T
	Cursor string
}

Item contains a generic item and its cursor.

In order to be able to compute the Cursor, the expectation is that T defines a field named ID of type string and field named CreatedAt of type time.Time or *time.Time.

type PSQLPaginator

type PSQLPaginator[T Tabler] struct {
	DB *gorm.DB
}

PSQLPaginator implements the Paginator interface for PostgreSQL databases.

func (PSQLPaginator[T]) ListItems

func (p PSQLPaginator[T]) ListItems(
	_ context.Context,
	paginationParams Arguments,
) (*Page[T], error)

ListItems retrieves the paginated result set. nolint: gocognit, gocyclo

type Page

type Page[T any] struct {
	Items []Item[T]
	Info  PageInfo
}

Page represents a paginated result set.

type PageInfo

type PageInfo struct {
	// HasPreviousPage is used to indicate whether more items exist prior to the
	// set defined by the pagination arguments.
	// If the client is paginating with last/before,
	// then the server must return true if prior items exist, otherwise false.
	// If the client is paginating with first/after, then the client may return true if
	// items prior to after exist, if it can do so efficiently, otherwise may return false.
	HasPreviousPage bool
	// HasNextPage is used to indicate whether more items exist following the
	// set defined by the pagination arguments.
	// If the client is paginating with first/after, then the server must return true
	// if further items exist, otherwise false.
	// If the client is paginating with last/before, then the server may return true if
	// items further from before exist, if it can do so efficiently, otherwise may return false.
	HasNextPage bool

	// StartCursor corresponds to the first item in the result set.
	StartCursor *string
	// EndCursor corresponds to the last item in the result set.
	EndCursor *string
}

PageInfo represents pagination information.

type Paginator

type Paginator[T any] interface {
	ListItems(ctx context.Context, pagination Arguments) (*Page[T], error)
}

Paginator defines methods for retrieving paginated items. The items may be ordered however the business logic dictates. The ordering must be consistent from page to page.

! The ordering of items should be the same when using first/after as when using last/before, all other arguments being equal. It should not be reversed when using last/before. !

When before: cursor is used, the edge closest to cursor must come last in the result edges. When after: cursor is used, the edge closest to cursor must come first in the result edges.

type Tabler

type Tabler = schema.Tabler

Tabler is an interface that must be implemented by all models. Currently it's an alias for Gorm's schema.Tabler interface.