feat: Phase 1 modernization - Generic Connection builders and SQLBoiler integration

[josemarluedke]

Phase 1 Modernization Complete

This PR completes Phase 1 of the go-paging modernization plan, introducing generic Connection/Edge types, core interfaces, and a refactored SQLBoiler adapter with comprehensive integration tests.

🎯 Key Features

1. Generic Connection/Edge Builders (60-80% Boilerplate Reduction)

• Generic Connection[T] and Edge[T] types for Relay-compliant GraphQL pagination
• BuildConnection() helper eliminates manual edge/node building across repositories
• Strategy-specific wrappers (e.g., offset.BuildConnection()) for convenient cursor encoding

Before (25+ lines per repository):

result := &domain.UserConnection{PageInfo: &paginator.PageInfo}
for i, row := range dbUsers {
    user, err := toDomainUser(row)
    if err != nil { return nil, err }
    result.Edges = append(result.Edges, domain.Edge{
        Cursor: *offset.EncodeCursor(paginator.Offset + i + 1),
        Node:   user,
    })
    result.Nodes = append(result.Nodes, user)
}
return result, nil

After (1 line):

return offset.BuildConnection(paginator, dbUsers, toDomainUser)

2. Core Generic Interfaces

• Paginator[T] - Strategy-agnostic pagination interface
• Fetcher[T] - Generic data fetching interface
• FilterFunc[T] - Type-safe filtering
• FetchParams - Unified parameters (offset, limit, orderBy, filters)

3. SQLBoiler Adapter (Option B Architecture)

Refactored to separate ORM concerns from pagination strategies:

• sqlboiler.Fetcher[T] - Generic ORM adapter (strategy-agnostic)
• sqlboiler.OffsetToQueryMods - Offset strategy builder
• Future-ready for cursor pagination and alternative ORMs (GORM, sqlc)

Example:

fetcher := sqlboiler.NewFetcher(
    models.Users().All,
    models.Users().Count,
    sqlboiler.OffsetToQueryMods, // Strategy injected here
)

4. Integration Tests with Real PostgreSQL

• 6 comprehensive integration tests using testcontainers
• Minimal SQLBoiler models (no code generation needed)
• End-to-end validation of offset pagination with real database
• Test coverage: Filters, sorting, relationships, large datasets

Test scenarios:

• ✅ Basic pagination with page size
• ✅ Second page navigation with cursors
• ✅ Last page handling
• ✅ Custom sorting (email ascending)
• ✅ Large dataset performance (100 users, 4 pages)
• ✅ Posts with relationships and WHERE filters

5. Documentation

• MIGRATION.md - Comprehensive migration guide with before/after examples
• README.md - Updated with v2 API examples
• Shows 60-80% code reduction in real-world scenarios

🐛 Bug Fixes

• HasPreviousPage logic corrected from (offset - pageSize > 0) to (offset > 0)

📊 Test Coverage

• 12 unit tests (paging package)
• 12 unit tests (offset package)
• 6 integration tests (SQLBoiler + PostgreSQL)
• Total: 30 tests, all passing ✅

🔧 Dependencies Added

• testcontainers-go - PostgreSQL test containers
• testcontainers-go/modules/postgres
• lib/pq - PostgreSQL driver
• google/uuid - Test data generation

🚀 What's Next (Phase 2 & 3)

• Phase 2: Cursor-based pagination implementation
• Phase 3: Quota-fill strategy for optimal page sizes

📝 Breaking Changes

None - this is additive functionality. Existing offset pagination code continues to work.

🧪 How to Test

# Run all tests including integration tests with PostgreSQL
go test ./...

# Run only integration tests
go test ./tests/

# Run specific integration test
go test ./tests/ -run "should paginate users"

📚 Related Documentation

• MIGRATION.md - Migration guide with examples
• README.md - Updated API documentation
• MODERNIZATION_RESEARCH.md - Full modernization plan (not committed)