eq2go/internal/common/interfaces.go

package common

import (
	"context"

	"eq2emu/internal/database"
)

// DatabaseIntegrated defines the interface for master lists that can load from database
type DatabaseIntegrated interface {
	// LoadFromDatabase loads all items from the database
	LoadFromDatabase(db *database.Database) error
	
	// SaveToDatabase saves all items to the database (if supported)
	SaveToDatabase(db *database.Database) error
}

// ContextAware defines the interface for master lists that need context for initialization
type ContextAware interface {
	// Initialize performs setup operations that may require external dependencies
	Initialize(ctx context.Context) error
}

// Validatable defines the interface for master lists that support validation
type Validatable interface {
	// Validate checks the integrity of all items in the list
	Validate() []error
	
	// ValidateItem checks the integrity of a specific item
	ValidateItem(item interface{}) error
}

// Searchable defines the interface for master lists that support advanced search
type Searchable[V any] interface {
	// Search finds items matching the given criteria
	Search(criteria SearchCriteria) []V
	
	// SearchByName finds items by name (case-insensitive)
	SearchByName(name string) []V
}

// SearchCriteria defines search parameters for advanced search operations
type SearchCriteria struct {
	Name     string                 // Name-based search (case-insensitive)
	Category string                 // Category-based search
	Filters  map[string]interface{} // Custom filters
	Limit    int                    // Maximum results to return (0 = no limit)
}

// Cacheable defines the interface for master lists that support caching
type Cacheable interface {
	// ClearCache clears any cached data
	ClearCache()
	
	// RefreshCache rebuilds cached data
	RefreshCache() error
	
	// IsCacheValid returns true if cache is valid
	IsCacheValid() bool
}

// Statistician defines the interface for master lists that track statistics
type Statistician interface {
	// GetStatistics returns usage statistics for the list
	GetStatistics() Statistics
	
	// ResetStatistics resets all tracked statistics
	ResetStatistics()
}

// Statistics represents usage statistics for a master list
type Statistics struct {
	TotalItems    int     `json:"total_items"`
	AccessCount   int64   `json:"access_count"`
	HitRate       float64 `json:"hit_rate"`
	MissCount     int64   `json:"miss_count"`
	LastAccessed  int64   `json:"last_accessed"`
	MemoryUsage   int64   `json:"memory_usage"`
}

// Indexable defines the interface for master lists that support multiple indexes
type Indexable[K comparable, V any] interface {
	// GetByIndex retrieves items using an alternate index
	GetByIndex(indexName string, key interface{}) []V
	
	// GetIndexes returns the names of all available indexes
	GetIndexes() []string
	
	// RebuildIndex rebuilds a specific index
	RebuildIndex(indexName string) error
	
	// RebuildAllIndexes rebuilds all indexes
	RebuildAllIndexes() error
}

// Categorizable defines the interface for master lists that support categorization
type Categorizable[V any] interface {
	// GetByCategory returns all items in a specific category
	GetByCategory(category string) []V
	
	// GetCategories returns all available categories
	GetCategories() []string
	
	// GetCategoryCount returns the number of items in a category
	GetCategoryCount(category string) int
}

// Versioned defines the interface for master lists that support version filtering
type Versioned[V any] interface {
	// GetByVersion returns items compatible with a specific version
	GetByVersion(version uint32) []V
	
	// GetByVersionRange returns items compatible within a version range
	GetByVersionRange(minVersion, maxVersion uint32) []V
}

// Relationship defines the interface for master lists that manage entity relationships
type Relationship[K comparable, V any] interface {
	// GetRelated returns items related to the given item
	GetRelated(id K, relationshipType string) []V
	
	// AddRelationship adds a relationship between two items
	AddRelationship(fromID K, toID K, relationshipType string) error
	
	// RemoveRelationship removes a relationship between two items
	RemoveRelationship(fromID K, toID K, relationshipType string) error
	
	// GetRelationshipTypes returns all supported relationship types
	GetRelationshipTypes() []string
}

// Grouped defines the interface for master lists that support grouping
type Grouped[K comparable, V any] interface {
	// GetByGroup returns all items in a specific group
	GetByGroup(groupID K) []V
	
	// GetGroups returns all available groups
	GetGroups() []K
	
	// GetGroupSize returns the number of items in a group
	GetGroupSize(groupID K) int
}

// Hierarchical defines the interface for master lists that support tree structures
type Hierarchical[K comparable, V any] interface {
	// GetChildren returns direct children of an item
	GetChildren(parentID K) []V
	
	// GetDescendants returns all descendants of an item
	GetDescendants(parentID K) []V
	
	// GetParent returns the parent of an item
	GetParent(childID K) (V, bool)
	
	// GetRoot returns the root item(s)
	GetRoot() []V
	
	// IsAncestor checks if one item is an ancestor of another
	IsAncestor(ancestorID K, descendantID K) bool
}

// Observable defines the interface for master lists that support event notifications
type Observable[K comparable, V any] interface {
	// Subscribe adds a listener for list events
	Subscribe(listener EventListener[K, V])
	
	// Unsubscribe removes a listener
	Unsubscribe(listener EventListener[K, V])
	
	// NotifyEvent sends an event to all listeners
	NotifyEvent(event Event[K, V])
}

// EventListener receives notifications about list changes
type EventListener[K comparable, V any] interface {
	// OnItemAdded is called when an item is added
	OnItemAdded(id K, item V)
	
	// OnItemRemoved is called when an item is removed
	OnItemRemoved(id K, item V)
	
	// OnItemUpdated is called when an item is updated
	OnItemUpdated(id K, oldItem V, newItem V)
	
	// OnListCleared is called when the list is cleared
	OnListCleared()
}

// Event represents a change event in a master list
type Event[K comparable, V any] struct {
	Type    EventType `json:"type"`
	ItemID  K         `json:"item_id"`
	Item    V         `json:"item,omitempty"`
	OldItem V         `json:"old_item,omitempty"`
}

// EventType represents the type of event that occurred
type EventType int

const (
	EventItemAdded EventType = iota
	EventItemRemoved
	EventItemUpdated
	EventListCleared
)