iris

Documentation

Index

• Variables
• type List
  • func NewList[T any](items []T, totalCount int64, filter any, opts ListOptions) *List[T]
  • func TransformList[T any, V any](list *List[T], transform func(T) (V, error)) (*List[V], error)
• type ListOptions
  • func (opts ListOptions) Bind(r *http.Request) error
  • func (opts ListOptions) GetCurrentPage() int
  • func (opts ListOptions) GetLimit() int
  • func (opts ListOptions) GetNextPage() int
  • func (opts ListOptions) GetOffset() int

Variables

var (
	// MaxSize defines the max size of items to display.
	MaxSize = 100000
	// DefaultSize defines the default size when ListOptions.Size is zero.
	DefaultSize = MaxSize
)

Types

type List

type List[T any] struct {
	CurrentPage int   `json:"current_page"`  // the current page.
	PageSize    int   `json:"page_size"`     // the total amount of the entities return.
	TotalPages  int   `json:"total_pages"`   // the total number of pages based on page, size and total count.
	TotalItems  int64 `json:"total_items"`   // the total number of rows.
	HasNextPage bool  `json:"has_next_page"` // true if more data can be fetched, depending on the current page * page size and total pages.
	Filter      any   `json:"filter"`        // if any filter data.
	Items       []T   `json:"items"`         // Items is empty array if no objects returned. Do NOT modify from outside.
}

List is the http response of a server handler which should render items with pagination support.

func NewList

func NewList[T any](items []T, totalCount int64, filter any, opts ListOptions) *List[T]

NewList returns a new List response which holds the current page, page size, total pages, total items count, any custom filter and the items array.

Example Code:

import "github.com/kataras/iris/v12/x/pagination"
...more code

type User struct {
	Firstname string `json:"firstname"`
	Lastname  string `json:"lastname"`
}

type ExtraUser struct {
	User
	ExtraData string
}

func main() {
	users := []User{
		{"Gerasimos", "Maropoulos"},
		{"Efi", "Kwfidou"},
	}

	t := pagination.NewList(users, 100, nil, pagination.ListOptions{
		Page: 1,
		Size: 50,
	})

	// Optionally, transform a T list of objects to a V list of objects.
	v, err := pagination.TransformList(t, func(u User) (ExtraUser, error) {
		return ExtraUser{
			User:      u,
			ExtraData: "test extra data",
		}, nil
	})
	if err != nil { panic(err) }

	paginationJSON, err := json.MarshalIndent(v, "", "    ")
	if err!=nil { panic(err) }
	fmt.Println(paginationJSON)
}

func TransformList

func TransformList[T any, V any](list *List[T], transform func(T) (V, error)) (*List[V], error)

TransformList accepts a List response and converts to a list of V items. T => from V => to

Example Code:

listOfUsers := pagination.NewList(...)
newListOfExtraUsers, err := pagination.TransformList(listOfUsers, func(u User) (ExtraUser, error) {
	return ExtraUser{
		User:      u,
		ExtraData: "test extra data",
	}, nil
})

type ListOptions

type ListOptions struct {
	// Current page number.
	// If Page > 0 then:
	// Limit = DefaultLimit
	// Offset = DefaultLimit * Page
	// If Page == 0 then no actual data is return,
	// internally we must check for this value
	// because in postgres LIMIT 0 returns the columns but with an empty set.
	Page int `json:"page" url:"page"`
	// The elements to get, this modifies the LIMIT clause,
	// this Size can't be higher than the MaxSize.
	// If Size is zero then size is set to DefaultSize.
	Size int `json:"size" url:"size"`
}

ListOptions is the list request object which should be provided by the client through URL Query. Then the server passes that options to a database query, including any custom filters may be given from the request body and, then the server responds back with a `Context.JSON(NewList(...))` response based on the database query's results.

func (ListOptions) Bind

func (opts ListOptions) Bind(r *http.Request) error

Bind binds the ListOptions values to a request value. It should be used as an x/client.RequestOption to fire requests on a server that supports pagination.

func (ListOptions) GetCurrentPage

func (opts ListOptions) GetCurrentPage() int

GetCurrentPage returns the Page or 1.

func (ListOptions) GetLimit

func (opts ListOptions) GetLimit() int

GetLimit returns the LIMIT value of a query.

func (ListOptions) GetNextPage

func (opts ListOptions) GetNextPage() int

GetNextPage returns the next page, current page + 1.

func (ListOptions) GetOffset

func (opts ListOptions) GetOffset() int

GetLimit returns the OFFSET value of a query.