eq2go/MODERNIZE.md

Package Modernization Instructions

Goal

Transform legacy packages to use generic MasterList pattern with simplified database operations.

Steps

1. Implement Generic MasterList Base

Create internal/common/master_list.go with generic collection management:

type MasterList[K comparable, V Identifiable[K]] struct {
    items map[K]V
    mutex sync.RWMutex
}

2. Consolidate Package Structure

Remove:

• Legacy wrapper functions (LoadAll, SaveAll, etc.)
• Duplicate database files (database.go, database_legacy.go)
• README.md (use doc.go instead)
• Separate "active_record.go" files

Consolidate into:

• {type}.go - Main type with embedded database operations
• types.go - Supporting types only (no main type)
• master.go - MasterList using generic base
• player.go - Player-specific logic (if applicable)
• doc.go - Primary documentation
• {type}_test.go - Focused tests

3. Refactor Main Type

Transform the main type to include database operations:

// Before: Separate type and database operations
type Achievement struct {
    ID    uint32
    Title string
}

func LoadAchievement(db *database.Database, id uint32) (*Achievement, error)
func SaveAchievement(db *database.Database, a *Achievement) error

// After: Embedded database operations
type Achievement struct {
    ID    uint32
    Title string
    
    db    *database.Database
    isNew bool
}

func New(db *database.Database) *Achievement
func Load(db *database.Database, id uint32) (*Achievement, error)
func (a *Achievement) Save() error
func (a *Achievement) Delete() error
func (a *Achievement) Reload() error

4. Update MasterList

Replace manual implementation with generic base:

// Before: Manual thread-safety
type MasterList struct {
    items map[uint32]*Achievement
    mutex sync.RWMutex
}

func (m *MasterList) AddAchievement(a *Achievement) bool {
    m.mutex.Lock()
    defer m.mutex.Unlock()
    // manual implementation
}

// After: Generic base
type MasterList struct {
    *common.MasterList[uint32, *Achievement]
}

func NewMasterList() *MasterList {
    return &MasterList{
        MasterList: common.NewMasterList[uint32, *Achievement](),
    }
}

func (m *MasterList) AddAchievement(a *Achievement) bool {
    return m.MasterList.Add(a)
}

5. Implement Identifiable Interface

Ensure main type implements GetID():

func (a *Achievement) GetID() uint32 {
    return a.AchievementID  // or appropriate ID field
}

6. Simplify API

Remove:

• Legacy type variants (Achievement vs AchievementRecord)
• Conversion methods (ToLegacy, FromLegacy)
• Duplicate CRUD operations
• Complex wrapper functions

Keep:

• Single type definition
• Direct database methods on type
• Domain-specific extensions only

7. Update Documentation

Create concise doc.go:

// Package achievements provides [brief description].
//
// Basic Usage:
//
//	achievement := achievements.New(db)
//	achievement.Title = "Dragon Slayer"
//	achievement.Save()
//
//	loaded, _ := achievements.Load(db, 1001)
//	loaded.Delete()
//
// Master List:
//
//	masterList := achievements.NewMasterList()
//	masterList.Add(achievement)
package achievements

8. Testing

Create focused tests:

• Test core type operations (New, Save, Load, Delete)
• Test MasterList basic operations
• Remove legacy compatibility tests
• Keep tests simple and direct

Key Principles

1. Single Source of Truth: One type definition, not multiple variants
2. Embedded Operations: Database methods on the type itself
3. Generic Base: Use common.MasterList for thread-safety
4. No Legacy Baggage: Remove all "Legacy" types and converters
5. Documentation in Code: Use doc.go, not README.md

Migration Checklist

• Create/verify generic MasterList in common package
• Identify main type and supporting types
• Consolidate database operations into main type
• Add db field and methods to main type
• Replace manual MasterList with generic base
• Implement GetID() for Identifiable interface
• Remove all legacy types and converters
• Update doc.go with concise examples
• Simplify tests to cover core functionality
• Create comprehensive benchmarks (benchmark_test.go)
• Verify performance meets targets
• Run go fmt, go test, and go test -bench=.

Expected Results

• 80% less code in most packages
• Single type instead of multiple variants
• Thread-safe operations via generic base
• Consistent API across all packages
• Better maintainability with less duplication

Benchmarking

After modernization, create comprehensive benchmarks to measure performance improvements and ensure no regressions:

Required Benchmarks

Core Operations:

func BenchmarkTypeCreation(b *testing.B)         // New type creation
func BenchmarkTypeOperations(b *testing.B)       // CRUD operations
func BenchmarkMasterListOperations(b *testing.B) // Collection operations

Performance Critical Paths:

func BenchmarkCoreAlgorithm(b *testing.B)      // Main business logic
func BenchmarkConcurrentAccess(b *testing.B)   // Thread safety
func BenchmarkMemoryAllocation(b *testing.B)   // Memory patterns

Comparison Benchmarks:

func BenchmarkComparisonWithOldSystem(b *testing.B) // Before/after metrics

Benchmark Structure

Use sub-benchmarks for detailed measurements:

func BenchmarkMasterListOperations(b *testing.B) {
    ml := NewMasterList()
    // Setup data...
    
    b.Run("Add", func(b *testing.B) {
        for i := 0; i < b.N; i++ {
            ml.Add(createTestItem(i))
        }
    })
    
    b.Run("Get", func(b *testing.B) {
        b.RunParallel(func(pb *testing.PB) {
            for pb.Next() {
                _ = ml.Get(randomID())
            }
        })
    })
}

Mock Implementations

Create lightweight mocks for interfaces:

type mockPlayer struct {
    level    int16
    location int32
}

func (p *mockPlayer) GetLevel() int16 { return p.level }
func (p *mockPlayer) GetLocation() int32 { return p.location }

Performance Expectations

Target performance after modernization:

• Creation operations: <100ns per operation
• Lookup operations: <50ns per operation
• Collection operations: O(1) for gets, O(N) for filters
• Memory allocations: Minimize in hot paths
• Concurrent access: Linear scaling with cores

Running Benchmarks

# Run all benchmarks
go test -bench=. ./internal/package_name

# Detailed benchmarks with memory stats
go test -bench=. -benchmem ./internal/package_name

# Compare performance over time
go test -bench=. -count=5 ./internal/package_name

# CPU profiling for optimization
go test -bench=BenchmarkCoreAlgorithm -cpuprofile=cpu.prof ./internal/package_name

Example Commands

# Remove legacy files
rm README.md database_legacy.go active_record.go

# Rename if needed
mv active_record.go achievement.go

# Test the changes
go fmt ./...
go test ./...
go test -bench=. ./...
go build ./...