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
- type PagingLinks
- type PagingParams
- type SortParams
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AddWhereClauseIfNotEmpty ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶
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 ¶ added in v0.2.0
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 ¶ added in v0.2.1
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 ¶
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 ¶ added in v0.2.1
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.
Source Files