tome

README

Package tome was designed to paginate simple RESTful APIs.

Installation

go get -u github.com/cyruzin/tome

Usage

To get started, import the tome package and initiate the pagination:

import "github.com/cyruzin/tome"

// Post type is a struct for a single post.
type Post struct {
	Title string `json:"title"`
	Body  string `json:"body"`
}

// Posts type is a struct for multiple posts.
type Posts []*Post

// Result type is a struct of posts with pagination.
type Result struct {
	Data *Posts `json:"data"`
	*tome.Chapter
}

// GetPosts gets the latest 10 posts with pagination.
func GetPosts(w http.ResponseWriter, r *http.Request) {
	// Creating a tome chapter with links.
	chapter := &tome.Chapter{
		// Setting base URL.
		BaseURL: "http://yourapi.com/v1/posts",
		// Enabling link results.
		Links: true,
		// Page that you captured in params inside you handler.
		NewPage: 2,
		// Total of pages, this usually comes from a SQL query total rows result.
		TotalResults: model.GetPostsTotalResults(),
	}

	// Paginating the results.
	if err := chapter.Paginate(); err != nil { 
		log.Panic(err)
	}

	// Here you pass the offset and limit.
	database, err := model.GetPosts(chapter.Offset, chapter.Limit)
	if err != nil {
		log.Panic(err)
	}

	// Mocking results with pagination.
	res := &Result{Data: database, Chapter: chapter}
    
	w.WriteHeader(http.StatusOK)  // Setting status 200.
	json.NewEncoder(w).Encode(res) // Returning JSON.
}

Output:

{
 "data": [
  {
   "title": "What is Lorem Ipsum?",
   "body": "Lorem Ipsum is simply dummy text of the printing and..."
  },
  {
   "title": "Why do we use it?",
   "body": "It is a long established fact that a reader will be..."
  }
 ],
 "base_url": "http://yourapi.com/v1/posts",
 "next_url": "http://yourapi.com/v1/posts?page=3",
 "prev_url": "http://yourapi.com/v1/posts?page=1",
 "per_page": 10,
 "current_page": 2,
 "last_page": 30,
 "total_results": 300
}

Performance

Without links:

Iterations	ns/op	B/op	allocs/op
200000000	7.80	0	0

With links:

Iterations	ns/op	B/op	allocs/op
10000000	133	96	2

Documentation

Overview

Package tome was designed to paginate simple RESTful APIs.

Index

• type Chapter
  • func (c *Chapter) Paginate() error

Types

type Chapter

type Chapter struct {
	// The base URL for the endpoint.
	// It is only necessary when using links.
	// Will be omitted from JSON when links are set to false.
	BaseURL string `json:"base_url,omitempty"`
	// The next URL string.
	// Will be omitted from JSON when links are set to false.
	NextURL string `json:"next_url,omitempty"`
	// The previous URL string.
	// Will be omitted from JSON when links are set to false.
	PreviousURL string `json:"prev_url,omitempty"`
	// Whether to create links or not.
	// Pagination without links is faster.
	Links bool `json:"-"`
	// The inicial offset position.
	Offset int `json:"-"`
	// The limit per page.
	// If none is provided, the limit will be setted to 10.
	Limit int `json:"per_page"`
	// The new page number captured on the request params.
	// Will be omitted from JSON, since there is no need for it.
	NewPage int `json:"-"`
	// The current page of the tome.
	// If none is provided, the current page will be setted to 1.
	CurrentPage int `json:"current_page"`
	// The last page of the tome.
	LastPage int `json:"last_page"`
	// The total results, this usually comes from
	// a database query.
	TotalResults int `json:"total_results"`
}

Chapter handles pagination results.

func (*Chapter) Paginate

func (c *Chapter) Paginate() error

Paginate handles the pagination calculation.