cursor pagination

pkg/mongo/repository.go

@@ -2,7 +2,6 @@ package mongo
 
 import (
 	"context"
-	"encoding/base64"
 	"errors"
 	"fmt"
 	"time"
@@ -26,6 +25,8 @@ type Pagination struct {
 	Cursor    string `json:"cursor"`    // Base64 encoded cursor for cursor-based pagination
 	SortField string `json:"sortField"` // Field to sort by (default: "_id")
 	SortOrder int    `json:"sortOrder"` // Sort order: 1 for ascending, -1 for descending
+	// SkipCount skips CountDocuments (use with cursor or deep offset pagination).
+	SkipCount bool `json:"skipCount,omitempty"`
 	// Projection limits fields returned from Find (e.g. exclude large blobs on list endpoints).
 	Projection bson.M `json:"projection,omitempty"`
 }
@@ -132,8 +133,16 @@ func (r *repository[T]) FindAll(ctx context.Context, filter bson.M, pagination P
 		pagination.SortOrder = -1 // Default to descending
 	}
 
-	// Build sort options
+	// Build sort with _id tie-breaker for stable keyset pagination.
 	sort := bson.D{{Key: pagination.SortField, Value: pagination.SortOrder}}
+	if pagination.SortField != "_id" {
+		sort = append(sort, bson.E{Key: "_id", Value: pagination.SortOrder})
+	}
+
+	countFilter, err := cloneFilter(filter)
+	if err != nil {
+		return nil, fmt.Errorf("failed to clone filter for count: %w", err)
+	}
 
 	// Build find options
 	findOptions := options.Find().
@@ -150,10 +159,7 @@ func (r *repository[T]) FindAll(ctx context.Context, filter bson.M, pagination P
 		if err != nil {
 			return nil, err
 		}
-		// Merge cursor filter with existing filter
-		for key, value := range cursorFilter {
-			filter[key] = value
-		}
+		filter = mergeFilters(filter, cursorFilter)
 	} else if pagination.Skip > 0 {
 		// Use offset-based pagination
 		findOptions.SetSkip(int64(pagination.Skip))
@@ -187,21 +193,23 @@ func (r *repository[T]) FindAll(ctx context.Context, filter bson.M, pagination P
 		items = items[:pagination.Limit] // Remove the extra item
 	}
 
-	// Get total count for pagination metadata
-	var totalCount int64
-	var countErr error
-	totalCount, countErr = r.Count(ctx, filter)
-	if countErr != nil {
-		r.logger.Error("Failed to get total count", map[string]interface{}{
-			"error": countErr.Error(),
-		})
-		totalCount = 0
+	// Get total count for pagination metadata (never include cursor constraints).
+	var totalCount int64 = -1
+	if !pagination.SkipCount {
+		var countErr error
+		totalCount, countErr = r.Count(ctx, countFilter)
+		if countErr != nil {
+			r.logger.Error("Failed to get total count", map[string]interface{}{
+				"error": countErr.Error(),
+			})
+			totalCount = 0
+		}
 	}
 
 	// Generate next cursor
 	var nextCursor string
 	if hasMore && len(items) > 0 {
-		nextCursor, err = r.generateCursor(items[len(items)-1], pagination.SortField)
+		nextCursor, err = r.generateCursor(items[len(items)-1], pagination.SortField, pagination.SortOrder)
 		if err != nil {
 			r.logger.Error("Failed to generate next cursor", map[string]interface{}{
 				"error": err.Error(),
@@ -445,43 +453,20 @@ func (r *repository[T]) validatePagination(pagination Pagination) error {
 	return nil
 }
 
-// buildCursorFilter builds a filter for cursor-based pagination
+// buildCursorFilter builds a filter for cursor-based pagination.
 func (r *repository[T]) buildCursorFilter(cursor, sortField string, sortOrder int) (bson.M, error) {
-	// Decode cursor
-	cursorBytes, err := base64.StdEncoding.DecodeString(cursor)
+	pageCursor, err := decodePageCursor(cursor)
 	if err != nil {
-		return nil, fmt.Errorf("%w: invalid cursor encoding", ErrInvalidCursor)
+		return nil, err
 	}
-
-	var cursorValue interface{}
-
-	// Try to parse as ObjectID first
-	if sortField == "_id" {
-		if objectID, err := bson.ObjectIDFromHex(string(cursorBytes)); err == nil {
-			cursorValue = objectID
-		} else {
-			return nil, fmt.Errorf("%w: invalid ObjectID in cursor", ErrInvalidCursor)
-		}
-	} else {
-		// For other fields, try to parse as appropriate type
-		// This is a simplified implementation - you might want to make this more sophisticated
-		cursorValue = string(cursorBytes)
+	if !pageCursor.matches(sortField, sortOrder) {
+		return nil, fmt.Errorf("%w: cursor does not match requested sort", ErrInvalidCursor)
 	}
-
-	// Build comparison operator based on sort order
-	var operator string
-	if sortOrder == 1 {
-		operator = "$gt"
-	} else {
-		operator = "$lt"
-	}
-
-	return bson.M{sortField: bson.M{operator: cursorValue}}, nil
+	return pageCursor.mongoFilter()
 }
 
-// generateCursor generates a cursor from a document
-func (r *repository[T]) generateCursor(doc T, sortField string) (string, error) {
-	// Convert document to BSON
+// generateCursor generates an opaque cursor from the last document in a page.
+func (r *repository[T]) generateCursor(doc T, sortField string, sortOrder int) (string, error) {
 	docBytes, err := bson.Marshal(doc)
 	if err != nil {
 		return "", fmt.Errorf("failed to marshal document: %w", err)
@@ -492,29 +477,17 @@ func (r *repository[T]) generateCursor(doc T, sortField string) (string, error)
 		return "", fmt.Errorf("failed to unmarshal document: %w", err)
 	}
 
-	// Get the sort field value
-	sortValue, exists := docMap[sortField]
-	if !exists {
-		return "", fmt.Errorf("sort field %s not found in document", sortField)
+	sortValue, err := documentSortValue(docMap, sortField)
+	if err != nil {
+		return "", err
 	}
 
-	// Convert to string for encoding
-	var cursorStr string
-	switch v := sortValue.(type) {
-	case bson.ObjectID:
-		cursorStr = v.Hex()
-	case string:
-		cursorStr = v
-	case int64:
-		cursorStr = fmt.Sprintf("%d", v)
-	case float64:
-		cursorStr = fmt.Sprintf("%f", v)
-	default:
-		cursorStr = fmt.Sprintf("%v", v)
+	idHex, err := documentIDHex(docMap)
+	if err != nil {
+		return "", err
 	}
 
-	// Encode as base64
-	return base64.StdEncoding.EncodeToString([]byte(cursorStr)), nil
+	return encodePageCursor(sortField, sortOrder, sortValue, idHex)
 }
 
 // getModelID extracts the ID from a model