feat: Unified Paginator[T] API with Fetcher pattern and functional options

[josemarluedke]

Overview

This PR unifies all three pagination strategies (offset, cursor, quotafill) around a common Paginator[T] interface with the Fetcher pattern and functional options. This is a major API improvement that makes the library more consistent, flexible, and easier to use.

Breaking Changes

1. Unified Paginator[T] Interface

All strategies now implement the same interface:

type Paginator[T any] interface {
    Paginate(ctx context.Context, args *PageArgs, opts ...PaginateOption) (*Page[T], error)
}

2. Fetcher Pattern

All constructors now take Fetcher[T] as the first parameter:

• offset.New(fetcher)
• cursor.New(fetcher, schema)
• quotafill.New(fetcher, filter, schema, opts...)

3. Functional Options

Page size limits moved from constructors to Paginate() options:

• paging.WithMaxSize(100) - cap maximum page size
• paging.WithDefaultSize(25) - set default when First is nil

4. Page[T] Result Type

Paginate() returns *Page[T] with:

• Nodes - the actual items
• PageInfo - pagination metadata
• Metadata - observability data (strategy, timing, offset, etc.)

5. Simplified BuildConnection

All BuildConnection functions now take the *Page[T] result:

• offset.BuildConnection(page, transform)
• cursor.BuildConnection(page, schema, args, transform)
• quotafill.BuildConnection(page, schema, args, transform)

Removed/Deprecated

• offset: QueryMods() method removed (use Paginate() instead)
• cursor: BuildFetchParams() deprecated (use Paginate() instead)
• quotafill: WithPageConfig() option removed (use Paginate() options)

Benefits

✨ Consistent API - All three strategies work the same way
✨ Reusable fetchers - Define once, use across multiple requests
✨ Per-request configuration - Page size limits via functional options
✨ Rich metadata - Observability data for monitoring and debugging
✨ Easier testing - Mockable Fetcher[T] interface
✨ Simpler strategy switching - Change 3 lines of code to switch strategies

Migration Example

Before (v0.3.0)

totalCount, _ := models.Users().Count(ctx, r.DB)
paginator := offset.New(page, totalCount)
dbUsers, _ := models.Users(paginator.QueryMods()...).All(ctx, r.DB)
conn, _ := offset.BuildConnection(paginator, dbUsers, toDomainUser)

After (v2.0)

fetcher := sqlboiler.NewFetcher(queryFunc, countFunc, sqlboiler.OffsetToQueryMods)
paginator := offset.New(fetcher)
result, _ := paginator.Paginate(ctx, page, paging.WithMaxSize(100))
conn, _ := offset.BuildConnection(result, toDomainUser)

Testing

✅ 204 tests passing across all packages:

• Root package: 48 passed
• Cursor: 41 passed
• Offset: 10 passed
• Quotafill: 23 passed
• SQLBoiler: 32 passed
• Integration tests: 50 passed

Documentation

• ✅ README.md updated with new API examples
• ✅ MIGRATION.md updated with comprehensive migration guide from v0.3.0 to v2.0
• ✅ All code examples updated to show unified API pattern
• ✅ Added "API Design Philosophy" section explaining the design decisions

Files Changed

Core API:

• interfaces.go - Added Offset to Metadata, updated Paginator[T] interface
• page_args.go - Added PaginateOption types and functional options

Offset Strategy:

• offset/paginator.go - Implemented Paginator[T], added Fetcher pattern
• offset/paginator_test.go - Updated tests for new API

Cursor Strategy:

• cursor/paginator.go - Implemented Paginator[T], added Fetcher pattern
• cursor/paginator_test.go - Updated tests for new API

Quotafill Strategy:

• quotafill/quotafill.go - Updated to use PaginateOption

Tests:

• connection_test.go - Updated BuildConnection tests
• tests/offset_integration_test.go - Rewritten for new API
• tests/cursor_integration_test.go - Updated for new API
• tests/security_test.go - Updated for new API

Documentation:

• README.md - Complete rewrite with unified API examples
• MIGRATION.md - Detailed v0.3.0 → v2.0 migration guide

Reviewers

This is a major breaking change. Please review:

1. API design consistency across all three strategies
2. Migration guide completeness
3. Test coverage for new API
4. Documentation clarity

See MIGRATION.md for the complete migration guide.