{"id":21571573,"url":"https://github.com/zheeeng/pagination","last_synced_at":"2025-04-10T14:20:59.248Z","repository":{"id":80218234,"uuid":"158917013","full_name":"zheeeng/pagination","owner":"zheeeng","description":"A pagination wrapper for decorating resource list response.","archived":false,"fork":false,"pushed_at":"2019-08-21T07:12:24.000Z","size":44,"stargazers_count":16,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-24T13:02:56.583Z","etag":null,"topics":["go","pager","pagination","paginator","restful"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zheeeng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-11-24T08:29:58.000Z","updated_at":"2023-04-06T10:26:25.000Z","dependencies_parsed_at":"2023-07-16T20:15:28.283Z","dependency_job_id":null,"html_url":"https://github.com/zheeeng/pagination","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zheeeng%2Fpagination","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zheeeng%2Fpagination/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zheeeng%2Fpagination/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zheeeng%2Fpagination/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zheeeng","download_url":"https://codeload.github.com/zheeeng/pagination/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248233936,"owners_count":21069493,"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":["go","pager","pagination","paginator","restful"],"created_at":"2024-11-24T11:16:43.420Z","updated_at":"2025-04-10T14:20:59.223Z","avatar_url":"https://github.com/zheeeng.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e:star: pagination\u003c/h1\u003e\n\n\u003cdiv align=\"center\"\u003e\n\nA pagination wrapper for decorating resource list response.\n\n[![CircleCI](https://img.shields.io/circleci/project/github/zheeeng/pagination/master.svg?label=tests)](https://circleci.com/gh/zheeeng/pagination)\n[![Coveralls](https://img.shields.io/coveralls/github/zheeeng/pagination.svg)](https://circleci.com/api/v1.1/project/github/zheeeng/pagination/latest/artifacts/0/tmp/artifacts/coverage.html)\n[![Language](https://img.shields.io/github/languages/top/zheeeng/pagination.svg?color=71e1ff)](https://golang.org/)\n[![Release](https://img.shields.io/github/tag/zheeeng/pagination.svg)](https://github.com/zheeeng/pagination/releases)\n[![License](https://img.shields.io/github/license/zheeeng/pagination.svg)](https://github.com/zheeeng/pagination/blob/master/LICENSE)\n\u003c/div\u003e\n\n## :paperclip: Go doc\n\nGet document at: https://godoc.org/github.com/zheeeng/pagination\n\n## :fire: Features\n\n1. Parse pagination info from request URI:\n    - Extract page and page size\n    - Extract quires and feed them to paginated response\n2. Decorate response body with pagination info:\n    - Feedback page navigation: `page`, `page_size`, `total`\n    - Feedback hyper links: `first`, `last`, `prev`, `next`\n    - Feedback query pairs\n3. Get calculated valuable pagination params:\n    - Get whether the URI provided pagination info\n    - Calculate the offset and the chunk length\n    - Calculate the start and end offsets, for manually truncate the list by yourself\n    - Calculate values above from your specified page or item index\n4. Manipulate pagination info:\n    - Modify quires\n    - Reset page and pageSize, maybe sometimes you want to overwrite them\n5. Truncate resource list by demands:\n    - If the list length is greater than pageSize\n6. Config default params:\n    - Change the default page size\n\n## :bulb: Note\n\nThis pagination wrapper requires the resource list implements `Trunctable` interface.\n\n```go\ntype Truncatable interface {\n    Len() int\n    Slice(startIndex, endIndex int) Truncatable\n}\n```\n\ne.g.\n```go\ntype TrunctableBooks []Book\n\nfunc (tb TrunctableBooks) Slice(startIndex, endIndex int) pagination.Truncatable {\n\treturn tb[startIndex:endIndex]\n}\nfunc (tb TrunctableBooks) Len() int {\n\treturn len(tb)\n}\n```\n\n## Usage :point_down:\n\n**Init a pagination instance:**\n```go\npg := pagination.DefaultPagination()\n```\n\n```go\npg := pagination.NewPagination(PaginatorConfiguration{\n    PageSize: 50,\n})\n```\n\n**Parse URI and get a manipulable paginator**\n```go\npgt := pg.Parse(someURI)\n\n```\n\n**Get/set page information**\n```go\noffset, length := pgt.GetOffsetRange()\n\ntotal, items := db.Offset(offset).Limit(length).Query()\n```\n\n```go\nstart, end := pgt.GetRange()\n\ntotal, items := db.QueryAll()\nitems = items[start:end]\n```\n\n```go\n// Put all items into one page\nif !pgt.HasRawPagination() {\n    total, items := db.QueryAll()\n    pgt.SetPageInfo(1, total)\n}\n```\n\n**Manipulate queries**\n\n```go\n// got url.Values\nquery := pgt.Query()\nif query.Get(\"publisher\") == \"\" {\n\tquery.Add(\"publisher\", \"Tada Publications\")\n}\nif query.Get(\"author\") == \"Fisher\" {\n\tquery.Set(\"author\", \"F.isher\")\n}\nschema.Parse(query.Encode(), \u0026someQueryBookStruct)\n```\n\n**Wrap your list**\n\n```go\nresponse := pgt.Wrap(TruncatableItems(partialItems), total)\n```\n\n```go\n// WrapWithTruncate helps truncating the list\nresponse := pgt.WrapWithTruncate(TruncatableItems(allItems), total)\n```\n\n## Example :point_down:\n\n```go\npackage pagination_test\n\nimport (\n\t\"encoding/json\"\n\t\"fmt\"\n\n\t\"github.com/zheeeng/pagination\"\n)\n\ntype Book struct {\n\tID     int    `json:\"id\"`\n\tAuthor string `json:\"author\"`\n\tName   string `json:\"name\"`\n}\n\ntype TrunctableBooks []Book\n\nfunc (tb TrunctableBooks) Slice(startIndex, endIndex int) pagination.Truncatable {\n\treturn tb[startIndex:endIndex]\n}\nfunc (tb TrunctableBooks) Len() int {\n\treturn len(tb)\n}\n\nvar total = 20\nvar requestURI = \"api.example.com/books?author=jk\u0026page=2\u0026page_size=5\"\nvar books = []Book{}\n\nfunc init() {\n\tfor i := 0; i \u003c 20; i++ {\n\t\tbook := Book{i, \"jk\", \"book\"}\n\t\tbooks = append(books, book)\n\t}\n}\n\nfunc Example() {\n\tpg := pagination.DefaultPagination()\n\n\tpgt := pg.Parse(requestURI)\n\n\tpaginatedData := pgt.WrapWithTruncate(TrunctableBooks(books), total)\n\n\tresponseBody, _ := json.MarshalIndent(paginatedData, \"\", \"    \")\n\n\tfmt.Println(string(responseBody))\n}\n```\n\n## Sample output :point_down:\n\n```json\n{\n    \"pagination\": {\n        \"page\": 2,\n        \"page_size\": 5,\n        \"total\": 20,\n        \"first\": \"api.example.com/books?author=jk\u0026page=1\u0026page_size=5\",\n        \"last\": \"api.example.com/books?author=jk\u0026page=4\u0026page_size=5\",\n        \"prev\": \"api.example.com/books?author=jk\u0026page=1\u0026page_size=5\",\n        \"next\": \"api.example.com/books?author=jk\u0026page=3\u0026page_size=5\",\n        \"query\": {\n            \"author\": [\n                \"jk\"\n            ],\n            \"page\": [\n                \"2\"\n            ],\n            \"page_size\": [\n                \"5\"\n            ]\n        }\n    },\n    \"result\": [\n        {\n            \"id\": 5,\n            \"author\": \"jk\",\n            \"name\": \"book\"\n        },\n        {\n            \"id\": 6,\n            \"author\": \"jk\",\n            \"name\": \"book\"\n        },\n        {\n            \"id\": 7,\n            \"author\": \"jk\",\n            \"name\": \"book\"\n        },\n        {\n            \"id\": 8,\n            \"author\": \"jk\",\n            \"name\": \"book\"\n        },\n        {\n            \"id\": 9,\n            \"author\": \"jk\",\n            \"name\": \"book\"\n        }\n    ]\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzheeeng%2Fpagination","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzheeeng%2Fpagination","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzheeeng%2Fpagination/lists"}