feat!: require Schema for cursor and quotafill pagination (Phase 2 + 3)

[josemarluedke]

Breaking Changes - Schema-Based Cursor Pagination

This PR makes Schema required for cursor and quotafill pagination, eliminating encoder/OrderBy mismatches at compile-time and validating sort fields at runtime.

Summary

BREAKING CHANGE: cursor.New() and quotafill.New() now require *cursor.Schema[T] instead of separate encoder + OrderBy parameters.

API Changes

Cursor API (Before):

encoder := cursor.NewCompositeCursorEncoder(func(u *User) map[string]any {
    return map[string]any{"created_at": u.CreatedAt, "id": u.ID}
})
orderBy := []paging.OrderBy{{Column: "created_at", Desc: true}, {Column: "id", Desc: true}}
paginator := cursor.New(page, encoder, users)
fetchParams := cursor.BuildFetchParams(page, encoder, orderBy)
conn, _ := cursor.BuildConnection(paginator, users, encoder, transform)

Cursor API (After):

schema := cursor.NewSchema[*User]().
    Field("created_at", "c", func(u *User) any { return u.CreatedAt }).
    FixedField("id", cursor.DESC, "i", func(u *User) any { return u.ID })

paginator, err := cursor.New(page, schema, users)  // Validates PageArgs
fetchParams, err := cursor.BuildFetchParams(page, schema)  // OrderBy from schema
conn, err := cursor.BuildConnection(paginator, users, transform)  // No encoder param

Quotafill API (Before):

quotafill.New(fetcher, filter, encoder, orderBy, opts...)

Quotafill API (After):

quotafill.New(fetcher, filter, schema, opts...)

What Changed

Core Implementation

• Added cursor.Schema[T] pattern as single source of truth for sortable fields
• Schema validates PageArgs before creating encoders
• Schema automatically includes fixed fields in OrderBy
• All cursor functions now return errors for validation
• Enhanced PageArgs with WithSortBy() and WithMultiSort() helpers

Benefits

1. Type Safety: Impossible to create mismatched encoder/OrderBy pairs
2. Runtime Validation: Schema validates sort fields before encoding
3. Security: Short cursor keys prevent information leakage
4. Simplicity: One parameter (schema) instead of two (encoder + orderBy)
5. Multi-tenant Support: Fixed prefix fields for efficient partitioning

Commits

• 832ed1e feat(cursor): add Schema pattern for type-safe pagination
• 75fb5ae feat(cursor)!: require Schema for cursor pagination
• a669f6e feat(quotafill)!: require Schema for quotafill pagination
• 907a227 test: update integration tests for Schema-based API
• 8f8b30e docs: update README for Schema-based API
• e49f6f0 refactor(core): enhance PageArgs with structured multi-column sorting
• 54aa727 fix(tests): ensure PageArgs.SortBy matches schema OrderBy

Test Results

✅ All 46 cursor unit tests passing
✅ All 19 quotafill unit tests passing
✅ All 53 integration tests passing

Migration Guide

Simple Migration

// Before:
encoder := cursor.NewCompositeCursorEncoder(func(u *User) map[string]any {
    return map[string]any{"created_at": u.CreatedAt, "id": u.ID}
})
orderBy := []paging.OrderBy{{Column: "created_at", Desc: true}, {Column: "id", Desc: true}}

// After:
schema := cursor.NewSchema[*User]().
    Field("created_at", "c", func(u *User) any { return u.CreatedAt }).
    FixedField("id", cursor.DESC, "i", func(u *User) any { return u.ID })

Update Function Calls

// cursor.New: add error handling
paginator, err := cursor.New(page, schema, users)
if err != nil {
    return nil, err
}

// cursor.BuildFetchParams: pass schema only
fetchParams, err := cursor.BuildFetchParams(page, schema)
if err != nil {
    return nil, err
}

// cursor.BuildConnection: remove encoder
conn, err := cursor.BuildConnection(paginator, users, transform)

// quotafill.New: pass schema instead of encoder + orderBy
wrapper := quotafill.New(fetcher, filter, schema, opts...)

// Use PageArgs helpers for sorting
args := paging.WithSortBy(nil, "created_at", true)
args = paging.WithMultiSort(args,
    paging.OrderBy{Column: "name", Desc: false},
    paging.OrderBy{Column: "created_at", Desc: true},
)

Related

• Implements cursor modernization Phase 2 requirements
• Builds on Phase 1 (PR feat: Phase 1 modernization - Generic Connection builders and SQLBoiler integration #10) generic Connection builders