pagi

README

getting start

• install

go get -u "github.com/billowdev/pagi"

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.