Add pagination support to Table with ListPaged and WithPaginator methods

Author: klaidliadon

table.go

@@ -25,8 +25,9 @@ type Record[T any, I ID] interface {
 // Table provides basic CRUD operations for database records.
 type Table[T any, P Record[T, I], I ID] struct {
 	*DB
-	Name     string
-	IDColumn string
+	Name      string
+	IDColumn  string
+	Paginator Paginator[P]
 }
 
 // helpers for setting timestamp fields
@@ -202,6 +203,18 @@ func (t *Table[T, P, I]) List(ctx context.Context, where sq.Sqlizer, orderBy []s
 	return records, nil
 }
 
+// ListPaged returns paginated records matching the condition.
+func (t *Table[T, P, I]) ListPaged(ctx context.Context, where sq.Sqlizer, page *Page) ([]P, *Page, error) {
+	q := t.SQL.Select("*").From(t.Name).Where(where)
+
+	result, q := t.Paginator.PrepareQuery(q, page)
+	if err := t.Query.GetAll(ctx, q, &result); err != nil {
+		return nil, nil, err
+	}
+	result = t.Paginator.PrepareResult(result, page)
+	return result, page, nil
+}
+
 // Iter returns an iterator for records matching the condition.
 func (t *Table[T, P, I]) Iter(ctx context.Context, where sq.Sqlizer, orderBy []string) (iter.Seq2[P, error], error) {
 	q := t.getListQuery(where, orderBy)
@@ -281,6 +294,16 @@ func (t *Table[T, P, I]) HardDeleteByID(ctx context.Context, id I) error {
 	return nil
 }
 
+// WithPaginator returns a table instance with the given paginator.
+func (t *Table[T, P, I]) WithPaginator(opts ...PaginatorOption) *Table[T, P, I] {
+	return &Table[T, P, I]{
+		DB:        t.DB,
+		Name:      t.Name,
+		IDColumn:  t.IDColumn,
+		Paginator: NewPaginator[P](opts...),
+	}
+}
+
 // WithTx returns a table instance bound to the given transaction.
 func (t *Table[T, P, I]) WithTx(tx pgx.Tx) *Table[T, P, I] {
 	return &Table[T, P, I]{
@@ -289,8 +312,9 @@ func (t *Table[T, P, I]) WithTx(tx pgx.Tx) *Table[T, P, I] {
 			SQL:   t.DB.SQL,
 			Query: t.DB.TxQuery(tx),
 		},
-		Name:     t.Name,
-		IDColumn: t.IDColumn,
+		Name:      t.Name,
+		IDColumn:  t.IDColumn,
+		Paginator: t.Paginator,
 	}
 }
 

tests/table_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	sq "github.com/Masterminds/squirrel"
+	"github.com/goware/pgkit/v2"
 	"github.com/jackc/pgx/v5"
 	"github.com/stretchr/testify/require"
 )
@@ -195,6 +196,104 @@ func TestTable(t *testing.T) {
 		require.NoError(t, err, "SaveTx transaction failed")
 	})
 
+	t.Run("ListPaged", func(t *testing.T) {
+		ctx := t.Context()
+
+		account := &Account{Name: "ListPaged Account"}
+		err := db.Accounts.Save(ctx, account)
+		require.NoError(t, err)
+
+		// Create 15 articles.
+		for i := range 15 {
+			err := db.Articles.Save(ctx, &Article{
+				AccountID: account.ID,
+				Author:    fmt.Sprintf("Author %02d", i),
+			})
+			require.NoError(t, err)
+		}
+
+		// Default paginator (page size 10).
+		page := pgkit.NewPage(0, 1)
+		results, retPage, err := db.Articles.ListPaged(ctx, sq.Eq{"account_id": account.ID}, page)
+		require.NoError(t, err)
+		require.Len(t, results, 10)
+		require.True(t, retPage.More, "should have more pages")
+
+		// Second page.
+		page2 := pgkit.NewPage(0, 2)
+		results2, retPage2, err := db.Articles.ListPaged(ctx, sq.Eq{"account_id": account.ID}, page2)
+		require.NoError(t, err)
+		require.Len(t, results2, 5)
+		require.False(t, retPage2.More, "should not have more pages")
+
+		// No overlap between pages.
+		for _, r1 := range results {
+			for _, r2 := range results2 {
+				require.NotEqual(t, r1.ID, r2.ID, "pages should not overlap")
+			}
+		}
+	})
+
+	t.Run("WithPaginator", func(t *testing.T) {
+		ctx := t.Context()
+
+		account := &Account{Name: "WithPaginator Account"}
+		err := db.Accounts.Save(ctx, account)
+		require.NoError(t, err)
+
+		for i := range 10 {
+			err := db.Articles.Save(ctx, &Article{
+				AccountID: account.ID,
+				Author:    fmt.Sprintf("PagAuthor %02d", i),
+			})
+			require.NoError(t, err)
+		}
+
+		// Use a custom paginator with page size 3.
+		pagedTable := db.Articles.Table.WithPaginator(pgkit.WithDefaultSize(3), pgkit.WithMaxSize(5))
+
+		page := pgkit.NewPage(0, 1)
+		results, retPage, err := pagedTable.ListPaged(ctx, sq.Eq{"account_id": account.ID}, page)
+		require.NoError(t, err)
+		require.Len(t, results, 3, "should return 3 records with custom paginator")
+		require.True(t, retPage.More)
+
+		// Request size larger than max should be capped.
+		bigPage := pgkit.NewPage(100, 1)
+		results, _, err = pagedTable.ListPaged(ctx, sq.Eq{"account_id": account.ID}, bigPage)
+		require.NoError(t, err)
+		require.Len(t, results, 5, "should be capped at max size 5")
+	})
+
+	t.Run("WithTx preserves Paginator", func(t *testing.T) {
+		ctx := t.Context()
+
+		account := &Account{Name: "WithTx Paginator Account"}
+		err := db.Accounts.Save(ctx, account)
+		require.NoError(t, err)
+
+		for i := range 5 {
+			err := db.Articles.Save(ctx, &Article{
+				AccountID: account.ID,
+				Author:    fmt.Sprintf("TxPag %02d", i),
+			})
+			require.NoError(t, err)
+		}
+
+		pagedTable := db.Articles.Table.WithPaginator(pgkit.WithDefaultSize(2))
+
+		err = pgx.BeginFunc(ctx, db.Conn, func(pgTx pgx.Tx) error {
+			txTable := pagedTable.WithTx(pgTx)
+			page := pgkit.NewPage(0, 1)
+			results, retPage, err := txTable.ListPaged(ctx, sq.Eq{"account_id": account.ID}, page)
+			require.NoError(t, err)
+			require.Len(t, results, 2, "paginator should be preserved through WithTx")
+			require.True(t, retPage.More)
+			return nil
+		})
+		require.NoError(t, err)
+	})
+
 	t.Run("WithTx keeps IDColumn", func(t *testing.T) {
 		ctx := t.Context()