{"id":24056934,"url":"https://github.com/getevo/pagination","last_synced_at":"2025-07-20T17:33:41.873Z","repository":{"id":271314345,"uuid":"913050310","full_name":"getevo/pagination","owner":"getevo","description":"Paginate gorm objects for EVO","archived":false,"fork":false,"pushed_at":"2025-01-31T10:53:54.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-02-26T12:16:22.582Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getevo.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-06T23:45:13.000Z","updated_at":"2025-01-31T10:53:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"8506dfac-50b1-4adf-899d-199e45a49efd","html_url":"https://github.com/getevo/pagination","commit_stats":null,"previous_names":["getevo/pagination"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/getevo/pagination","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getevo%2Fpagination","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getevo%2Fpagination/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getevo%2Fpagination/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getevo%2Fpagination/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getevo","download_url":"https://codeload.github.com/getevo/pagination/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getevo%2Fpagination/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266165988,"owners_count":23886710,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-09T05:28:04.942Z","updated_at":"2025-07-20T17:33:41.855Z","avatar_url":"https://github.com/getevo.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pagination Library for EVO\n\nThis 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.\n\n---\n\n## Why This Library?\n\nPagination 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:\n\n- **Ease of Use**: Simplifies the implementation of pagination in APIs and applications.\n- **Flexibility**: Provides customization options for page size, maximum size, and debug mode.\n- **Efficiency**: Uses GORM’s database capabilities to fetch only the required data.\n- **Structured Output**: Returns data with metadata like total records, current page, total pages, and more.\n\n---\n\n## Features\n\n- Automatically calculates offsets and limits for database queries.\n- Handles edge cases like invalid page numbers or page sizes.\n- Supports debugging for SQL queries.\n- Offers metadata such as total records, total pages, and page range.\n- Easily integrates with GORM and EVO.\n\n---\n\n## Installation\n\nAdd this library to your Go project:\n\n```sh\ngo get github.com/getevo/pagination\n```\n\n---\n\n## Usage\n\n### Basic Example\n\nThis example demonstrates how to paginate user orders:\n\n```go\nfunc (c Controller) getUserOrdersHandler(request *evo.Request) any {\n    if request.User().Anonymous() {\n        return errors.New(403, \"access denied\")\n    }\n    var orders []models.Order\n    var model = db.Where(\"uuid = ?\", request.User().UUID())\n    var p, err = pagination.New(model, request, \u0026orders, pagination.Options{MaxSize: 50})\n    if err != nil {\n        log.Error(err)\n    }\n    return p\n}\n```\n\n### Example Using cURL\n\nYou can test the pagination API by adjusting the `size` and `page` parameters in the query string. For example:\n\n```sh\ncurl --location 'https://api.example.com/api/user/orders?size=10\u0026page=2'\n```\n\n\n\n### Customizing Page and Size\n\nYou can customize the page and size directly in the options:\n\n```go\nvar p, err = pagination.New(model, request, \u0026data, pagination.Options{\n    Page:    2,\n    Size:    20,\n    MaxSize: 100,\n})\n```\n\n### Debug Mode\n\nEnable debug mode to see detailed SQL logs:\n\n```go\nvar p, err = pagination.New(model, request, \u0026data, pagination.Options{\n    Debug: true,\n})\n```\n\n### Handling Errors\n\nThe library gracefully handles errors. If an error occurs during data fetching, the response will include the error message:\n\n```go\nif err != nil {\n    return errors.New(500, \"Failed to fetch paginated data\")\n}\n```\n\n### Accessing Metadata\n\nThe `Pagination` struct contains metadata you can use in your response:\n\n```go\nresponse := map[string]interface{}{\n    \"total_records\": p.Records,\n    \"current_page\": p.CurrentPage,\n    \"total_pages\":  p.Pages,\n    \"data\":         p.Data,\n}\nreturn response\n```\n\n### Custom Query Examples\n\n#### Paginate Products with a Filter\n\n```go\nvar products []models.Product\nvar model = db.Where(\"category = ?\", \"electronics\")\nvar p, err = pagination.New(model, request, \u0026products, pagination.Options{MaxSize: 20})\nif err != nil {\n    log.Error(err)\n}\nreturn p\n```\n\n#### Paginate Logs with Date Range\n\n```go\nvar logs []models.Log\nvar model = db.Where(\"created_at BETWEEN ? AND ?\", startDate, endDate)\nvar p, err = pagination.New(model, request, \u0026logs, pagination.Options{Size: 15, MaxSize: 50})\nif err != nil {\n    log.Error(err)\n}\nreturn p\n```\n\n#### Paginate with Sorting\n\n```go\nvar users []models.User\nvar model = db.Order(\"created_at DESC\")\nvar p, err = pagination.New(model, request, \u0026users)\nif err != nil {\n    log.Error(err)\n}\nreturn p\n```\n\n---\n\n## API Reference\n\n### `Options`\n\nThe `Options` struct allows you to customize pagination behavior:\n\n| Field     | Type   | Description                         |\n| --------- | ------ | ----------------------------------- |\n| `Size`    | `int`  | Number of records per page.         |\n| `Page`    | `int`  | Current page number.                |\n| `MaxSize` | `int`  | Maximum allowed page size.          |\n| `Debug`   | `bool` | Enables debug mode for SQL queries. |\n\n### `Pagination`\n\n| Field         | Type          | Description                       |\n| ------------- | ------------- | --------------------------------- |\n| `Records`     | `int`         | Total number of records.          |\n| `CurrentPage` | `int`         | Current page number.              |\n| `Pages`       | `int`         | Total number of pages.            |\n| `Size`        | `int`         | Number of records per page.       |\n| `First`       | `int`         | First record on the current page. |\n| `Last`        | `int`         | Last record on the current page.  |\n| `Data`        | `interface{}` | The paginated data.               |\n\n### Methods\n\n#### `New`\n\nCreates a new instance of the pagination object.\n\n```go\nfunc New(model *gorm.DB, request *evo.Request, out interface{}, options ...Options) (*Pagination, error)\n```\n\n#### `LoadData`\n\nLoads paginated data into the output variable.\n\n```go\nfunc (p *Pagination) LoadData(out interface{}) (*Pagination, error)\n```\n\n#### `GetOffset`\n\nCalculates the offset for paginated data.\n\n```go\nfunc (p *Pagination) GetOffset() int\n```\n\n#### `GetResponse`\n\nReturns a standardized response object.\n\n```go\nfunc (p *Pagination) GetResponse() outcome.Response\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetevo%2Fpagination","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetevo%2Fpagination","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetevo%2Fpagination/lists"}