feat: add additional column ordering to keysetpagination

pagination/keysetpagination/header.go

@@ -94,7 +94,11 @@ func Header(w http.ResponseWriter, u *url.URL, p *Paginator) {
 func Parse(q url.Values) ([]Option, error) {
 	var opts []Option
 	if q.Has("page_token") {
-		opts = append(opts, WithToken(q.Get("page_token")))
+		pageToken, err := url.QueryUnescape(q.Get("page_token"))
+		if err != nil {
+			return nil, errors.WithStack(err)
+		}
+		opts = append(opts, WithToken(pageToken))
 	}
 	if q.Has("page_size") {
 		size, err := strconv.Atoi(q.Get("page_size"))

pagination/keysetpagination/paginator.go

@@ -4,21 +4,50 @@
 package keysetpagination
 
 import (
+	"errors"
 	"fmt"
+	"strings"
 
 	"github.com/gobuffalo/pop/v6"
+	"github.com/gobuffalo/pop/v6/columns"
 )
 
 type (
-	Item      interface{ PageToken() string }
+	Item interface{ PageToken() string }
+
+	Order string
+
+	columnOrdering struct {
+		name  string
+		order Order
+	}
 	Paginator struct {
 		token, defaultToken        string
 		size, defaultSize, maxSize int
 		isLast                     bool
+		additionalColumn           columnOrdering
 	}
 	Option func(*Paginator) *Paginator
 )
 
+var ErrUnknownOrder = errors.New("unknown order")
+
+const (
+	OrderDescending Order = "DESC"
+	OrderAscending  Order = "ASC"
+)
+
+func (o Order) extract() (string, string, error) {
+	switch o {
+	case OrderAscending:
+		return ">", string(o), nil
+	case OrderDescending:
+		return "<", string(o), nil
+	default:
+		return "", "", ErrUnknownOrder
+	}
+}
+
 func (p *Paginator) Token() string {
 	if p.token == "" {
 		return p.defaultToken
@@ -40,6 +69,23 @@ func (p *Paginator) Size() int {
 	return size
 }
 
+func parseToken(idField string, s string) map[string]string {
+	tokens := strings.Split(s, "/")
+	if len(tokens) != 2 {
+		return map[string]string{idField: s}
+	}
+
+	r := map[string]string{}
+
+	for _, p := range tokens {
+		if columnName, value, found := strings.Cut(p, "="); found {
+			r[columnName] = value
+		}
+	}
+
+	return r
+}
+
 func (p *Paginator) IsLast() bool {
 	return p.isLast
 }
@@ -51,22 +97,59 @@ func (p *Paginator) ToOptions() []Option {
 		WithDefaultToken(p.defaultToken),
 		WithDefaultSize(p.defaultSize),
 		WithMaxSize(p.maxSize),
+		WithColumn(p.additionalColumn.name, p.additionalColumn.order),
 		withIsLast(p.isLast),
 	}
 }
 
+func (p *Paginator) multipleOrderFieldsQuery(q *pop.Query, idField string, cols map[string]*columns.Column, quote func(string) string) error {
+	column, ok := cols[p.additionalColumn.name]
+	if !ok {
+		return errors.New("column not supported")
+	}
+
+	tokenParts := parseToken(idField, p.Token())
+	idValue := tokenParts[idField]
+
+	quoteName := quote(column.Name)
+
+	value, ok := tokenParts[column.Name]
+
+	if !ok {
+		return errors.New("no value provided for " + column.Name)
+	}
+
+	sign, keyword, err := p.additionalColumn.order.extract()
+	if err != nil {
+		return err
+	}
+
+	q.
+		Where(fmt.Sprintf("%s %s ? OR (%s = ? AND %s > ?)", quoteName, sign, quoteName, quote(idField)), value, value, idValue).
+		Order(fmt.Sprintf("%s %s", quoteName, keyword))
+
+	return nil
+}
+
 // Paginate returns a function that paginates a pop.Query.
 // Usage:
 //
 //	q := c.Where("foo = ?", foo).Scope(keysetpagination.Paginate[Item](paginator))
 func Paginate[I Item](p *Paginator) pop.ScopeFunc {
 	var item I
-	id := (&pop.Model{Value: item}).IDField()
+	model := &pop.Model{Value: item}
+	id := model.IDField()
 	return func(q *pop.Query) *pop.Query {
 		eid := q.Connection.Dialect.Quote(id)
+
+		if err := p.multipleOrderFieldsQuery(q, id, model.Columns().Cols, q.Connection.Dialect.Quote); err != nil {
+			// silently ignore the error, and fall back to the "default" behavior of just ordering by the token
+			q.Where(fmt.Sprintf(`%s > ?`, eid), p.Token())
+		}
+
 		return q.
-			Limit(p.Size()+1).
-			Where(fmt.Sprintf(`%s > ?`, eid), p.Token()).
+			Limit(p.Size() + 1).
+			// we always need to order by the id field last
 			Order(fmt.Sprintf(`%s ASC`, eid))
 	}
 }
@@ -127,6 +210,16 @@ func WithSize(size int) Option {
 	}
 }
 
+func WithColumn(name string, order Order) Option {
+	return func(opts *Paginator) *Paginator {
+		opts.additionalColumn = columnOrdering{
+			name:  name,
+			order: order,
+		}
+		return opts
+	}
+}
+
 func withIsLast(isLast bool) Option {
 	return func(opts *Paginator) *Paginator {
 		opts.isLast = isLast

pagination/keysetpagination/paginator_test.go

@@ -14,7 +14,8 @@ import (
 )
 
 type testItem struct {
-	ID string `db:"pk"`
+	ID        string `db:"pk"`
+	CreatedAt string `db:"created_at"`
 }
 
 func (t testItem) PageToken() string {
@@ -32,7 +33,7 @@ func TestPaginator(t *testing.T) {
 		q = q.Scope(Paginate[testItem](paginator))
 
 		sql, args := q.ToSQL(&pop.Model{Value: new(testItem)})
-		assert.Equal(t, "SELECT test_items.pk FROM test_items AS test_items WHERE \"pk\" > $1 ORDER BY \"pk\" ASC LIMIT 11", sql)
+		assert.Equal(t, "SELECT test_items.created_at, test_items.pk FROM test_items AS test_items WHERE \"pk\" > $1 ORDER BY \"pk\" ASC LIMIT 11", sql)
 		assert.Equal(t, []interface{}{"token"}, args)
 	})
 
@@ -46,7 +47,7 @@ func TestPaginator(t *testing.T) {
 		q = q.Scope(Paginate[testItem](paginator))
 
 		sql, args := q.ToSQL(&pop.Model{Value: new(testItem)})
-		assert.Equal(t, "SELECT test_items.pk FROM test_items AS test_items WHERE `pk` > ? ORDER BY `pk` ASC LIMIT 11", sql)
+		assert.Equal(t, "SELECT test_items.created_at, test_items.pk FROM test_items AS test_items WHERE `pk` > ? ORDER BY `pk` ASC LIMIT 11", sql)
 		assert.Equal(t, []interface{}{"token"}, args)
 	})
 
@@ -156,3 +157,59 @@ func TestParse(t *testing.T) {
 		require.ErrorIs(t, err, strconv.ErrSyntax)
 	})
 }
+
+func TestPaginateWithAdditionalColumn(t *testing.T) {
+	c, err := pop.NewConnection(&pop.ConnectionDetails{
+		URL: "postgres://foo.bar",
+	})
+	require.NoError(t, err)
+
+	for _, tc := range []struct {
+		d    string
+		opts []Option
+		e    string
+		args []interface{}
+	}{
+		{
+			d:    "with sort by created_at DESC",
+			opts: []Option{WithToken("pk=token_value/created_at=timestamp"), WithColumn("created_at", "DESC")},
+			e:    "created_at\" < $1 OR (\"created_at\" = $2 AND \"pk\" > $3) ORDER BY \"created_at\" DESC, \"pk\" ASC",
+			args: []interface{}{"timestamp", "timestamp", "token_value"},
+		},
+		{
+			d:    "with sort by created_at ASC",
+			opts: []Option{WithToken("pk=token_value/created_at=timestamp"), WithColumn("created_at", "ASC")},
+			e:    "created_at\" > $1 OR (\"created_at\" = $2 AND \"pk\" > $3) ORDER BY \"created_at\" ASC, \"pk\" ASC",
+			args: []interface{}{"timestamp", "timestamp", "token_value"},
+		},
+		{
+			d:    "with malformed token",
+			opts: []Option{WithToken("some/random/token"), WithColumn("created_at", "ASC")},
+			e:    "WHERE \"pk\" > $1 ORDER BY \"pk\"",
+			args: []interface{}{"some/random/token"},
+		},
+		{
+			d:    "with unknown column",
+			opts: []Option{WithToken("pk=token_value/created_at=timestamp"), WithColumn("unknown_column", "ASC")},
+			e:    "WHERE \"pk\" > $1 ORDER BY \"pk\"",
+			args: []interface{}{"pk=token_value/created_at=timestamp"},
+		},
+		{
+			d:    "with unknown order",
+			opts: []Option{WithToken("pk=token_value/created_at=timestamp"), WithColumn("created_at", Order("unknown order"))},
+			e:    "WHERE \"pk\" > $1 ORDER BY \"pk\"",
+			args: []interface{}{"pk=token_value/created_at=timestamp"},
+		},
+	} {
+		t.Run("case="+tc.d, func(t *testing.T) {
+			opts := append(tc.opts, WithSize(10))
+			paginator := GetPaginator(opts...)
+			sql, args := pop.Q(c).
+				Scope(Paginate[testItem](paginator)).
+				ToSQL(&pop.Model{Value: new(testItem)})
+			assert.Contains(t, sql, tc.e)
+			assert.Contains(t, sql, "LIMIT 11")
+			assert.Equal(t, tc.args, args)
+		})
+	}
+}