README
¶
paginate
paginate is a Go library that lets you paginate any data source. Typically, it's intended to be used in a flow resembling something like this:
1. Create cursor based on request url.
2. Fetch data based on cursor.
3. Pass data to cursor.
4. Respond with items and pagination urls.
Example
Paginate comments stored in a database:
func commentsHandler(w http.ResponseWriter, r *http.Request) {
// 1. Create cursor based on request url.
defaults := &paginate.Defaults{Count: 5, Order: "updated_at", Direction: paginate.DESC}
options := &paginate.Options{Prefetch: true}
cursor := paginate.NewCursorFromUrl(r.URL, defaults, options)
// 2. Fetch data based on cursor.
// Note: Use cursor.PrefetchCount() instead of cursor.Count if the cursor was
// created with the Prefetch option set to true.
comments := ...
// 3. Pass data to cursor so that it can generate the next and previous cursors.
items := make([]paginate.Item, len(comments))
for i, comment := range comments {
items[i] = comment
}
cursor.Items = items
// 3.5. (Optional) Drop extra comment that was prefetched for pagination.
// This is only necessary when the cursor is created with the Prefetch
// option.
if len(comments) > cursor.Count {
comments = comments[0:cursor.Count]
}
return comments, nil
// 4. Respond with comments and pagination urls.
fmt.Fprint(w, comments)
if cursor.Next() != nil {
next := cursor.Next().ToUrl()
fmt.Fprint(w, next)
}
if cursor.Prev() != nil {
prev := cursor.Prev().ToUrl()
fmt.Fprint(w, prev)
}
}
You can see the full example in examples/comments.go.
Documentation
¶
Index ¶
Constants ¶
View Source
const ( DESC = 0 ASC = 1 DEFAULT_COUNT = 10 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cursor ¶
type Cursor struct {
// Value should be used an an inclusive value when making queries based on this
// cursor.
// For example, in SQL: WHERE created_at <= cursor.Value (assuming descending
// sort order).
Value string
// Offset should be as offset when making queries based on this cursor.
// For example, in SQL: LIMIT cursor.Offset, 10.
Offset int
// Count is the number of items per page. Instead of using this directly you should
// use PrefetchCount() to account for prefetching.
// For example, in SQL: LIMIT 0, cursor.PrefetchCount()
Count int
// Order is an arbitrary string that should be used by Item.PaginationValue to
// decide what pagination value to return.
Order string
// Direction should control the comparison order when making queries based on this
// cursor.
// For example, in SQL:
// when Direction is DESC: WHERE created_at <= cursor.Value
// when Direction is ASC: WHERE created_at >= cursor.Value
Direction int
// Url is the url that was used to create this cursor. It's used to construct the
// next and previous urls.
Url *url.URL
Options *Options
// Items is a slice of Item objects on which we should paginate. It must be set before
// calling Next, Prev or ToPagination.
Items []Item
}
func NewCursorFromUrl ¶
func (*Cursor) PrefetchCount ¶
func (*Cursor) ToPagination ¶
func (c *Cursor) ToPagination() *Pagination
type Item ¶
type Item interface {
// PaginationValue should return a pagination value for this item.
// For example, when pagination SQL rows this could simply be the id of the row.
// If paginating a redis zset, this might be the score of the zset member.
// When paginating an array this would be the index of the array element.
PaginationValue(c *Cursor) string
}
Item is the iterface that must be implemented by objects that can be paginated.
type Options ¶
type Options struct {
// Prefetch can be set to true to indicate to the cursor that Items will contain one
// additional item, i.e. the first item from the next page.
Prefetch bool
}
type Pagination ¶
type Pagination struct {
Next *string `json:"next"`
}
Source Files
Directories
Click to show internal directories.
Click to hide internal directories.