pagi

README

pagi: Pagination Helper Package

pagi is a Go package designed to simplify pagination in your applications. It provides utility functions and types to handle pagination parameters, sorting, filtering, and generating pagination links.

Installation

To install pagi, use go get:

go get -u github.com/billowdev/pagi

Usage

1. Import the Package

import "github.com/billowdev/pagi"

2. Pagination Parameters

The PagingParams type represents pagination parameters including limits, page numbers, sorting, and filtering.

3. Sorting

The SortParams type defines parameters for sorting, including the field to sort by, sorting order, and default sorting order.

4. Filtering

The CommonTimeFilters type contains common time-based filters such as date ranges and timestamps.

5. Utility Functions

AddWhereClauseIfNotEmpty

func AddWhereClauseIfNotEmpty(query *gorm.DB, columnName string, filterValue string, filterType string) *gorm.DB

Adds a WHERE clause to the query if the filter value is not empty, based on the provided column name, filter value, and filter type.

ApplyFilter

func ApplyFilter(query *gorm.DB, column string, value interface{}, filterType string) *gorm.DB

Applies filtering to the query based on the provided column, value, and filter type.

ApplyCommaFilter

func ApplyCommaFilter(query *gorm.DB, columnName, filterValue string) *gorm.DB

Applies filtering to the query for comma-separated values in the specified column.

ApplyCommaFilterWithJoin

func ApplyCommaFilterWithJoin(query *gorm.DB, joinTable, joinCondition, columnName, filterValue string) *gorm.DB

Applies filtering to the query with a JOIN condition for comma-separated values.

ApplyDatetimeFilters

func ApplyDatetimeFilters(query *gorm.DB, filter CommonTimeFilters) *gorm.DB

Applies datetime filtering to the query based on the provided CommonTimeFilters.

ApplyDatetimePreloadFilters

func ApplyDatetimePreloadFilters(query *gorm.DB, filter CommonTimeFilters, preloadKey string) *gorm.DB

Applies datetime filtering with preloading to the query based on the provided CommonTimeFilters.

Examples

Basic Pagination

params := pagi.PagingParams{}
params.Limit = 10
params.Page = 1
params.Sort = "id"
params.Order = "asc"
params.BaseURL = "https://example.com"

License

pagi is licensed under the MIT License. See the LICENSE file for details.

Contributing

• Contributions are welcome! Feel free to open issues or submit pull requests on the GitHub repository.

Documentation

Index

• func AddWhereClauseIfNotEmpty(query *gorm.DB, columnName string, filterValue string, filterType string) *gorm.DB
• func ApplyCommaFilter(query *gorm.DB, columnName, filterValue string) *gorm.DB
• func ApplyCommaFilterWithJoin(query *gorm.DB, joinTable, joinCondition, columnName, filterValue string) *gorm.DB
• func ApplyDatetimeFilters(query *gorm.DB, filter CommonTimeFilters) *gorm.DB
• func ApplyDatetimePreloadFilters(query *gorm.DB, filter CommonTimeFilters, preloadKey string) *gorm.DB
• func ApplyFilter(query *gorm.DB, column string, value interface{}, filterType string) *gorm.DB
• func GetAPIEndpoint(host, path string) string
• func NewOrderBy(params SortParams) string
• type CommonTimeFilters
• type PagingInfo
  • func Paginate[FT any, T any](p PagingParams[FT], query *gorm.DB) (PagingInfo[T], error)
  • func PaginateArray[T any](data []T, page, pageSize int, endpoint string) (PagingInfo[T], []T)
• type PagingLinks
• type PagingParams
  • func NewPaginationParams[FilterType interface{}](host string, sort string, order string, page string, pageSize string, ...) PagingParams[FilterType]
  • func (p *PagingParams[FilterType]) GetLimit() int
  • func (p *PagingParams[FilterType]) GetOffset() int
  • func (p *PagingParams[FilterType]) GetPage() int
  • func (p *PagingParams[FilterType]) GetSort() string
• type SortParams

Functions

func AddWhereClauseIfNotEmpty

func AddWhereClauseIfNotEmpty(query *gorm.DB, columnName string, filterValue string, filterType string) *gorm.DB

AddWhereClauseIfNotEmpty adds a WHERE clause to the query if the filter value is not empty, based on the provided column name, filter value, and filter type.

Parameters:

• query: A pointer to the gorm.DB instance.
• columnName: The name of the column to filter.
• filterValue: The value to filter by.
• filterType: The type of filtering to apply (exact, like, date).

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func ApplyCommaFilter

func ApplyCommaFilter(query *gorm.DB, columnName, filterValue string) *gorm.DB

ApplyCommaFilter applies filtering to the query for comma-separated values in the specified column.

Parameters:

• query: A pointer to the gorm.DB instance.
• columnName: The name of the column to filter.
• filterValue: The comma-separated values to filter by.

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func ApplyCommaFilterWithJoin

func ApplyCommaFilterWithJoin(query *gorm.DB, joinTable, joinCondition, columnName, filterValue string) *gorm.DB

ApplyCommaFilterWithJoin applies filtering to the query with a JOIN condition for comma-separated values.

Parameters:

• query: A pointer to the gorm.DB instance.
• joinTable: The table to join.
• joinCondition: The condition for joining.
• columnName: The name of the column to filter.
• filterValue: The comma-separated values to filter by.

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func ApplyDatetimeFilters

func ApplyDatetimeFilters(query *gorm.DB, filter CommonTimeFilters) *gorm.DB

ApplyDatetimeFilters applies datetime filtering to the query based on the provided CommonTimeFilters.

Parameters:

• query: A pointer to the gorm.DB instance.
• filter: The CommonTimeFilters containing filtering parameters.

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func ApplyDatetimePreloadFilters

func ApplyDatetimePreloadFilters(query *gorm.DB, filter CommonTimeFilters, preloadKey string) *gorm.DB

ApplyDatetimePreloadFilters applies datetime filtering with preloading to the query based on the provided CommonTimeFilters.

Parameters:

• query: A pointer to the gorm.DB instance.
• filter: The CommonTimeFilters containing filtering parameters.
• preloadKey: The key for preloading.

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func ApplyFilter

func ApplyFilter(query *gorm.DB, column string, value interface{}, filterType string) *gorm.DB

ApplyFilter applies filtering to the query based on the provided column, value, and filter type.

Parameters:

• query: A pointer to the gorm.DB instance.
• column: The name of the column to filter.
• value: The value to filter by.
• filterType: The type of filtering to apply (contains, exact).

Returns:

• *gorm.DB: A pointer to the modified gorm.DB instance.

func GetAPIEndpoint

func GetAPIEndpoint(host, path string) string

GetAPIEndpoint constructs the API endpoint URL based on the provided host and path.

Parameters:

• host: The host of the API.
• path: The path of the API endpoint.

Returns:

• string: The constructed API endpoint URL.

Example:

endpoint := GetAPIEndpoint("example.com", "/api/v1/resource")
// Constructs the API endpoint URL as "https://example.com/api/v1/resource".

func NewOrderBy

func NewOrderBy(params SortParams) string

NewOrderBy constructs the ORDER BY clause based on sorting parameters.

Parameters:

• params: A SortParams instance containing sorting parameters.

Returns:

• string: The constructed ORDER BY clause.

Example:

orderBy := NewOrderBy(SortParams{"name", "asc", "id asc"})
// Constructs an ORDER BY clause sorting by "name" in ascending order,
// and if invalid sorting parameters are provided, falls back to default order.

Types

type CommonTimeFilters

type CommonTimeFilters struct {
	DateField     string `json:"date_field"`
	CreatedAfter  string `json:"created_after"`
	UpdatedAfter  string `json:"updated_after"`
	CreatedBefore string `json:"created_before"`
	UpdatedBefore string `json:"updated_before"`
	CreatedAt     string `json:"created_at"`
	UpdatedAt     string `json:"updated_at"`
	StartDate     string `json:"start_date"`
	EndDate       string `json:"end_date"`
}

CommonTimeFilters contains common time-based filters such as date ranges and timestamps.

type PagingInfo

type PagingInfo[T interface{}] struct {
	Links      PagingLinks `json:"links"`
	Total      int64       `json:"total"`
	Page       int         `json:"page"`
	PageSize   int         `json:"page_size"`
	TotalPages int         `json:"total_pages"`
	Rows       T           `json:"rows,omitempty"`
}

PagingInfo provides information about pagination, including links, total count, page number, page size, total pages, and rows.

func Paginate

func Paginate[FT any, T any](p PagingParams[FT], query *gorm.DB) (PagingInfo[T], error)

Paginate is a function that facilitates pagination of data retrieved using GORM in Go. It takes in paging parameters and a GORM query, then returns a PagingInfo structure containing paginated data along with links for navigating through the pages.

Parameters:

• p: PagingParams[FT] represents the paging parameters including page number, page size, base URL, etc.
• query: *gorm.DB is a pointer to the GORM query used to fetch data.

Returns:

• PagingInfo[T]: A structure containing paginated data along with metadata and navigation links.
• error: An error, if any occurred during the pagination process.

Usage Example:

// Define paging parameters
pagingParams := PagingParams{
	Page:     1,
	Limit:    10,
	BaseURL:  "http://example.com/data",
	Sort:     "created_at desc",
}

// Perform pagination
paginatedData, err := Paginate(pagingParams, db.Model(&YourModel{}))
if err != nil {
	log.Fatal(err)
}

func PaginateArray

func PaginateArray[T any](data []T, page, pageSize int, endpoint string) (PagingInfo[T], []T)

PaginateArray is a function that paginates an array of elements of type T. It takes the array, page number, page size, and endpoint URL as input parameters, and returns a PagingInfo structure containing paginated data along with links for navigating through the pages, and the subset of data for the current page.

Parameters:

• data: []T is the array of elements to be paginated.
• page: int represents the current page number.
• pageSize: int represents the number of elements per page.
• endpoint: string is the base URL endpoint used for constructing next and previous page links.

Returns:

• PagingInfo[T]: A structure containing paginated data metadata and navigation links.
• []T: A subset of data representing the elements for the current page.

Note:

• If pageSize or page is less than or equal to 0, the function returns an empty PagingInfo and nil slice.
• If the requested page number exceeds the total number of pages, the function returns an empty PagingInfo and nil slice.
• The function constructs next and previous page links based on the provided endpoint URL.
• The returned PagingInfo contains metadata such as total number of items, current page number, page size, and total number of pages.

type PagingLinks

type PagingLinks struct {
	Next     string `json:"next"`
	Previous string `json:"previous"`
}

PagingLinks contains links for next and previous pages.

type PagingParams

type PagingParams[FilterType interface{}] struct {
	Limit      int        `json:"limit"`
	Page       int        `json:"page"`
	Sort       string     `json:"sort"`
	Order      string     `json:"order"`
	TotalRows  int64      `json:"total_rows"`
	TotalPages int        `json:"total_pages"`
	BaseURL    string     `json:"base_url"`
	Filters    FilterType `json:"filters"`
}

PagingParams represents pagination parameters including limits, sorting, total rows, and filters.

func NewPaginationParams

func NewPaginationParams[FilterType interface{}](host string, sort string, order string, page string, pageSize string, defaultSort string) PagingParams[FilterType]

NewPaginationParams creates a new instance of PagingParams with the provided parameters.

Parameters:

• host: The base URL for the pagination.
• sort: The field to sort the results by.
• order: The order in which to sort the results ('asc' or 'desc').
• page: The page number for pagination.
• pageSize: The number of items per page.
• defaultSort: The default field to sort the results by if 'sort' parameter is not provided.

Returns:

• PagingParams[FilterType]: A PagingParams instance configured with the provided parameters.

Example:

params := NewPaginationParams("https://example.com", "name", "asc", "1", "20", "id")
// Creates a PagingParams instance with base URL "https://example.com",
// sorting by "name" in ascending order, with 20 items per page and starting from page 1.

func (*PagingParams[FilterType]) GetLimit

func (p *PagingParams[FilterType]) GetLimit() int

GetLimit returns the limit value for pagination. If no limit is set, it defaults to 10.

Returns:

• int: The limit value for pagination.

func (*PagingParams[FilterType]) GetOffset

func (p *PagingParams[FilterType]) GetOffset() int

GetOffset calculates and returns the offset for pagination based on the current page and limit.

Returns:

• int: The offset value for pagination.

func (*PagingParams[FilterType]) GetPage

func (p *PagingParams[FilterType]) GetPage() int

GetPage returns the current page number for pagination. If no page is set, it defaults to 1.

Returns:

• int: The current page number for pagination.

func (*PagingParams[FilterType]) GetSort

func (p *PagingParams[FilterType]) GetSort() string

GetSort returns the sort field and order for pagination. If no sorting parameters are provided, it defaults to "Id desc".

Returns:

• string: The sort field and order for pagination.

type SortParams

type SortParams struct {
	Sort           string // Field to sort by
	Order          string // Sorting order ("ASC" or "DESC")
	DefaultOrderBy string // Default
}

SortParams contains parameters for sorting.