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

For more comprehensive examples, you can check example/main.go and paginator_test.go

Assume there is an query struct for paging:

type PagingQuery struct {
    After  *string
    Before *string
    Limit  *int
    Order  *string
}

and a GORM model:

type Model struct {
    ID          int
    CreatedAt   time.Time
}

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

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

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

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

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

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

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

    if q.Order != nil && *q.Order == "asc" {
        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.Cursor, error) {
    var models []Model

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

    // get paginator for Model
    p := GetModelPaginator(q)

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

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

    return models, cursor, nil
}

After paginating, you can call GetNextCursor(), which returns a Cursor struct containing cursor for next iteration:

type Cursor struct {
    After  *string `json:"after"`
    Before *string `json:"before"`
}

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

License

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

Released under the MIT License

Documentation

Index

• Variables
• func Decode(cursor string) []interface{}
• func Encode(v reflect.Value, keys []string) string
• type Cursor
• type CursorDecoder
  • func NewCursorDecoder(ref interface{}, keys ...string) (CursorDecoder, error)
• type CursorEncoder
  • func NewCursorEncoder(keys ...string) CursorEncoder
• type Order
• type Paginator
  • func New() *Paginator
  • func (p *Paginator) GetNextCursor() Cursor
  • func (p *Paginator) Paginate(stmt *gorm.DB, out interface{}) *gorm.DB
  • func (p *Paginator) SetAfterCursor(afterCursor string)
  • func (p *Paginator) SetBeforeCursor(beforeCursor string)
  • func (p *Paginator) SetKeys(keys ...string)
  • func (p *Paginator) SetLimit(limit int)
  • func (p *Paginator) SetOrder(order Order)

Variables

var (
	ErrInvalidDecodeReference = errors.New("decode reference should be struct")
	ErrInvalidField           = errors.New("invalid field")
	ErrInvalidOldField        = errors.New("invalid old field")
)

Errors for decoders

Functions

func Decode

func Decode(cursor string) []interface{}

Decode decodes cursor into values in the same order as encoding Deprecated: Decode will remove in v2, use CursorDecoder instead

func Encode

func Encode(v reflect.Value, keys []string) string

Encode encodes properties in order defined by keys on the struct of v Deprecated: Encode will remove in v2, use CursorEncoder instead

Types

type Cursor

type Cursor struct {
	After  *string `json:"after" query:"after"`
	Before *string `json:"before" query:"before"`
}

Cursor cursor data

type CursorDecoder

type CursorDecoder interface {
	Decode(cursor string) []interface{}
}

CursorDecoder decoder for cursor

func NewCursorDecoder

func NewCursorDecoder(ref interface{}, keys ...string) (CursorDecoder, error)

NewCursorDecoder creates cursor decoder

type CursorEncoder

type CursorEncoder interface {
	Encode(v interface{}) string
}

CursorEncoder encoder for cursor

func NewCursorEncoder

func NewCursorEncoder(keys ...string) CursorEncoder

NewCursorEncoder creates cursor encoder

type Order

type Order string

Order type for order

const (
	ASC  Order = "ASC"
	DESC Order = "DESC"
)

Orders

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) GetNextCursor

func (p *Paginator) GetNextCursor() Cursor

GetNextCursor returns cursor for next 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(afterCursor string)

SetAfterCursor sets paging after cursor

func (*Paginator) SetBeforeCursor

func (p *Paginator) SetBeforeCursor(beforeCursor 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