pagination

Documentation

Overview

Package pagination provides Relay style pagination.

Index

• Constants
• 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
• type TablerWithID

Constants

const UUID_Length = 16

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.

type TablerWithID

type TablerWithID interface {
	Tabler
	IDField() string
}

TablerWithID extends the Tabler interface to support models with custom identifier fields. The IDField method returns the name of the struct field that should be used as the cursor. Implement this interface for types where the identifier field differs from the default "ID".