Pagination Library for EVO

This library provides a robust and flexible solution for handling pagination in Go applications. Built using GORM for database interaction and EVO for request handling, it is designed to simplify pagination logic, making it easy to retrieve and display paginated data in a structured and efficient way.

Why This Library?

Pagination is essential for applications that deal with large datasets. Fetching all data at once is not practical for performance and usability reasons. This library offers:

Ease of Use: Simplifies the implementation of pagination in APIs and applications.
Flexibility: Provides customization options for page size, maximum size, and debug mode.
Efficiency: Uses GORM’s database capabilities to fetch only the required data.
Structured Output: Returns data with metadata like total records, current page, total pages, and more.

Features

Automatically calculates offsets and limits for database queries.
Handles edge cases like invalid page numbers or page sizes.
Supports debugging for SQL queries.
Offers metadata such as total records, total pages, and page range.
Easily integrates with GORM and EVO.

Installation

Add this library to your Go project:

go get github.com/getevo/pagination

Usage

Basic Example

This example demonstrates how to paginate user orders:

func (c Controller) getUserOrdersHandler(request *evo.Request) any {
    if request.User().Anonymous() {
        return errors.New(403, "access denied")
    }
    var orders []models.Order
    var model = db.Where("uuid = ?", request.User().UUID())
    var p, err = pagination.New(model, request, &orders, pagination.Options{MaxSize: 50})
    if err != nil {
        log.Error(err)
    }
    return p
}

Example Using cURL

You can test the pagination API by adjusting the size and page parameters in the query string. For example:

curl --location 'https://api.example.com/api/user/orders?size=10&page=2'

Customizing Page and Size

You can customize the page and size directly in the options:

var p, err = pagination.New(model, request, &data, pagination.Options{
    Page:    2,
    Size:    20,
    MaxSize: 100,
})

Debug Mode

Enable debug mode to see detailed SQL logs:

var p, err = pagination.New(model, request, &data, pagination.Options{
    Debug: true,
})

Handling Errors

The library gracefully handles errors. If an error occurs during data fetching, the response will include the error message:

if err != nil {
    return errors.New(500, "Failed to fetch paginated data")
}

Accessing Metadata

The Pagination struct contains metadata you can use in your response:

response := map[string]interface{}{
    "total_records": p.Records,
    "current_page": p.CurrentPage,
    "total_pages":  p.Pages,
    "data":         p.Data,
}
return response

Custom Query Examples

Paginate Products with a Filter

var products []models.Product
var model = db.Where("category = ?", "electronics")
var p, err = pagination.New(model, request, &products, pagination.Options{MaxSize: 20})
if err != nil {
    log.Error(err)
}
return p

Paginate Logs with Date Range

var logs []models.Log
var model = db.Where("created_at BETWEEN ? AND ?", startDate, endDate)
var p, err = pagination.New(model, request, &logs, pagination.Options{Size: 15, MaxSize: 50})
if err != nil {
    log.Error(err)
}
return p

Paginate with Sorting

var users []models.User
var model = db.Order("created_at DESC")
var p, err = pagination.New(model, request, &users)
if err != nil {
    log.Error(err)
}
return p

API Reference

`Options`

The Options struct allows you to customize pagination behavior:

Field	Type	Description
`Size`	`int`	Number of records per page.
`Page`	`int`	Current page number.
`MaxSize`	`int`	Maximum allowed page size.
`Debug`	`bool`	Enables debug mode for SQL queries.

`Pagination`

Field	Type	Description
`Records`	`int`	Total number of records.
`CurrentPage`	`int`	Current page number.
`Pages`	`int`	Total number of pages.
`Size`	`int`	Number of records per page.
`First`	`int`	First record on the current page.
`Last`	`int`	Last record on the current page.
`Data`	`interface{}`	The paginated data.

Methods

`New`

Creates a new instance of the pagination object.

func New(model *gorm.DB, request *evo.Request, out interface{}, options ...Options) (*Pagination, error)

`LoadData`

Loads paginated data into the output variable.

func (p *Pagination) LoadData(out interface{}) (*Pagination, error)

`GetOffset`

Calculates the offset for paginated data.

func (p *Pagination) GetOffset() int

`GetResponse`

Returns a standardized response object.

func (p *Pagination) GetResponse() outcome.Response

# README