paginator

README

gorm-cursor-paginator

A paginator doing cursor-based pagination based on GORM

Installation

go get -u github.com/pilagod/gorm-cursor-paginator

Usage by Example

Assume there is an optional query struct for paging:

type PagingQuery struct {
    AfterCursor     *string
    BeforeCursor    *string
    Limit           *int
    Order           *string
}

and a GORM model:

type Model struct {
    ID          uint
    CreatedAt   time.Time
}

You can simply build up a cursor paginator from the PagingQuery like:

import (
    paginator "github.com/pilagod/gorm-cursor-paginator"
)

func InitModelPaginatorFrom(q PagingQuery) paginator.Paginator {
    p := paginator.New()

    p.SetKeys("CreatedAt", "ID") // [defualt: "ID"] (order of keys matters)

    if q.AfterCursor != nil {
        p.SetAfterCursor(*q.AfterCursor) // [default: ""]
    }

    if q.BeforeCursor != nil {
        p.SetBeforeCursor(*q.BeforeCursor) // [default: ""]
    }

    if q.Limit != nil {
        p.SetLimit(*q.Limit) // [default: 10]
    }

    if q.Order != nil {
        if *q.Order == "ascending" {
            p.SetOrder(paginator.ASC) // [default: paginator.DESC]
        }
    }
    return p
}

Then you can start to do pagination easily with GORM:

func Find(db *gorm.DB, q PagingQuery) ([]Model, paginator.Cursors, error) {
    var models []Model

    stmt := db.Where(/* ... other filters ... */)
    stmt = db.Or(/* ... more other filters ... */)

    // init paginator for Model
    p := InitModelPaginatorFrom(q)

    // use GORM-like syntax to do pagination
    result := p.Paginate(stmt, &models)

    if result.Error != nil {
        // ...
    }
    // get cursors for next iteration
    cursors := p.GetNextCursors()

    return models, cursors, nil
}

After pagination, you can call GetNextCursors(), which returns a Cursors struct, to get cursors for next iteration:

type Cursors struct {
    AfterCursor     string
    BeforeCursor    string
}

That's all ! Enjoy your paging in the GORM world 🎉

License

© Chun-Yan Ho (pilagod), 2018-NOW

Released under the MIT License

Documentation

Index

• Constants
• type Cursors
• type Paginator
  • func New() Paginator
  • func (p *Paginator) GetNextCursors() Cursors
  • func (p *Paginator) Paginate(stmt *gorm.DB, out interface{}) *gorm.DB
  • func (p *Paginator) SetAfterCursor(cursor string)
  • func (p *Paginator) SetBeforeCursor(cursor string)
  • func (p *Paginator) SetKeys(keys ...string)
  • func (p *Paginator) SetLimit(limit int)
  • func (p *Paginator) SetOrder(order order)

Constants

const (
	// ASC refers to ascending order
	ASC order = "ASC"
	// DESC refers to descending order
	DESC order = "DESC"
)

Types

type Cursors

type Cursors struct {
	AfterCursor  string `json:"afterCursor"`
	BeforeCursor string `json:"beforeCursor"`
}

Cursors groups after/before cursors

type Paginator

type Paginator struct {
	// contains filtered or unexported fields
}

Paginator a builder doing pagination

func New

func New() Paginator

New inits paginator

func (*Paginator) GetNextCursors

func (p *Paginator) GetNextCursors() Cursors

GetNextCursors gets new cursors after pagination

func (*Paginator) Paginate

func (p *Paginator) Paginate(stmt *gorm.DB, out interface{}) *gorm.DB

Paginate paginates data

func (*Paginator) SetAfterCursor

func (p *Paginator) SetAfterCursor(cursor string)

SetAfterCursor sets paging after cursor

func (*Paginator) SetBeforeCursor

func (p *Paginator) SetBeforeCursor(cursor string)

SetBeforeCursor sets paging before cursor

func (*Paginator) SetKeys

func (p *Paginator) SetKeys(keys ...string)

SetKeys sets paging keys

func (*Paginator) SetLimit

func (p *Paginator) SetLimit(limit int)

SetLimit sets paging limit

func (*Paginator) SetOrder

func (p *Paginator) SetOrder(order order)

SetOrder sets paging order