{"id":13786662,"url":"https://github.com/cyruzin/tome","last_synced_at":"2026-01-24T11:43:27.352Z","repository":{"id":57494479,"uuid":"181048178","full_name":"cyruzin/tome","owner":"cyruzin","description":"Package tome was designed to paginate simple RESTful APIs.","archived":false,"fork":false,"pushed_at":"2022-04-20T16:41:33.000Z","size":124,"stargazers_count":35,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-11T22:39:25.015Z","etag":null,"topics":["api","go","golang","pagination","rest","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/cyruzin.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}},"created_at":"2019-04-12T16:49:45.000Z","updated_at":"2025-03-27T23:52:30.000Z","dependencies_parsed_at":"2022-09-02T19:50:37.182Z","dependency_job_id":null,"html_url":"https://github.com/cyruzin/tome","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cyruzin/tome","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyruzin%2Ftome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyruzin%2Ftome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyruzin%2Ftome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyruzin%2Ftome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cyruzin","download_url":"https://codeload.github.com/cyruzin/tome/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cyruzin%2Ftome/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28727087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T10:24:43.181Z","status":"ssl_error","status_checked_at":"2026-01-24T10:24:36.112Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["api","go","golang","pagination","rest","restful"],"created_at":"2024-08-03T19:01:27.436Z","updated_at":"2026-01-24T11:43:27.333Z","avatar_url":"https://github.com/cyruzin.png","language":"Go","funding_links":[],"categories":["公用事业公司","Utilities","工具库","工具库`可以提升效率的通用代码库和工具`","Utility"],"sub_categories":["实用程序/Miscellaneous","Utility/Miscellaneous","查询语","HTTP Clients","Fail injection"],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"./img/logo.png\"\u003e\u003c/p\u003e\n\n[![build](https://github.com/cyruzin/tome/actions/workflows/build.yml/badge.svg?branch=master)](https://github.com/cyruzin/tome/actions/workflows/build.yml) [![Coverage Status](https://coveralls.io/repos/github/cyruzin/tome/badge.svg?branch=master)](https://coveralls.io/github/cyruzin/tome?branch=master) [![GoDoc](https://godoc.org/github.com/cyruzin/tome?status.svg)](https://godoc.org/github.com/cyruzin/tome) [![Go Report Card](https://goreportcard.com/badge/github.com/cyruzin/tome)](https://goreportcard.com/report/github.com/cyruzin/tome) [![GitHub license](https://img.shields.io/github/license/Naereen/StrapDown.js.svg)](https://github.com/Naereen/StrapDown.js/blob/master/LICENSE)\n\nPackage tome was designed to paginate simple RESTful APIs.\n\n## Installation\n\n```sh\ngo get -u github.com/cyruzin/tome\n```\n## Usage\n\nTo get started, import the `tome` package and initiate the pagination:\n\n```go\nimport \"github.com/cyruzin/tome\"\n\n// Post type is a struct for a single post.\ntype Post struct {\n\tTitle string `json:\"title\"`\n\tBody  string `json:\"body\"`\n}\n\n// Posts type is a struct for multiple posts.\ntype Posts []*Post\n\n// Result type is a struct of posts with pagination.\ntype Result struct {\n\tData *Posts `json:\"data\"`\n\t*tome.Chapter\n}\n\n// GetPosts gets the latest 10 posts with pagination.\nfunc GetPosts(w http.ResponseWriter, r *http.Request) {\n\t// Creating a tome chapter with links.\n\tchapter := \u0026tome.Chapter{\n\t\t// Setting base URL.\n\t\tBaseURL: \"http://yourapi.com/v1/posts\",\n\t\t// Enabling link results.\n\t\tLinks: true,\n\t\t// Page that you captured in params inside you handler.\n\t\tNewPage: 2,\n\t\t// Total of pages, this usually comes from a SQL query total rows result.\n\t\tTotalResults: model.GetPostsTotalResults(),\n\t}\n\n\t// Paginating the results.\n\tif err := chapter.Paginate(); err != nil { \n\t\tw.WriteHeader(http.StatusUnprocessableEntity)  // Setting status 422.\n\t        json.NewEncoder(w).Encode(err) // Returning JSON with an error.\n\t\treturn\n\t}\n\n\t// Here you pass the offset and limit.\n\tdatabase, err := model.GetPosts(chapter.Offset, chapter.Limit)\n\tif err != nil {\n\t\tw.WriteHeader(http.StatusUnprocessableEntity)  // Setting status 422.\n\t        json.NewEncoder(w).Encode(err) // Returning JSON with an error.\n\t\treturn\n\t}\n\n\t// Mocking results with pagination.\n\tres := \u0026Result{Data: database, Chapter: chapter}\n    \n\tw.WriteHeader(http.StatusOK)  // Setting status 200.\n\tjson.NewEncoder(w).Encode(res) // Returning success JSON.\n}\n```\n\nOutput: \n\n```json\n{\n \"data\": [\n  {\n   \"title\": \"What is Lorem Ipsum?\",\n   \"body\": \"Lorem Ipsum is simply dummy text of the printing and...\"\n  },\n  {\n   \"title\": \"Why do we use it?\",\n   \"body\": \"It is a long established fact that a reader will be...\"\n  }\n ],\n \"base_url\": \"http://yourapi.com/v1/posts\",\n \"next_url\": \"http://yourapi.com/v1/posts?page=3\",\n \"prev_url\": \"http://yourapi.com/v1/posts?page=1\",\n \"per_page\": 10,\n \"current_page\": 2,\n \"last_page\": 30,\n \"total_results\": 300\n}\n```\n\n## Performance\n\nWithout links:\n\n| Iterations | ns/op | B/op | allocs/op |\n|------------|-------|------|-----------|\n| 200000000  | 7.80  | 0    | 0         |\n\nWith links:\n\n| Iterations | ns/op | B/op | allocs/op |\n|------------|-------|------|-----------|\n| 10000000   | 133   | 96   | 2         |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyruzin%2Ftome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyruzin%2Ftome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyruzin%2Ftome/lists"}