cache

type Cache[ENT any, ID comparable] struct {
	// Source is the location of the original data
	Source Source[ENT, ID]
	// Repository is the resource that keeps the cached data.
	Repository Repository[ENT, ID]
	// IDA [optional] is the ENT's ID accessor.
	//
	// default: extid Lookup/Set
	IDA extid.Accessor[ENT, ID]
	// Invalidators [optional] is a list of invalidation rule which is being used whenever an entity is being invalidated.
	// It is ideal to invalidate a query by reconstucting the cache.HitID using the contents of the ENT OR ID.
	Invalidators []Invalidator[ENT, ID]
	// RefreshBehind [optional] enables background refreshing of cache.
	// When set to true, after the cache serves stale data, it triggers an
	// asynchronous update from the data source to refresh the cache in the background.
	// This ensures eventual consistency without blocking read operations.
	//
	// If you want to ensure that Refresh-Behind queries don't overlap between parallel cache instances,
	// then make sure that Scheduler uses a distributed locking.
	//
	// default: false
	RefreshBehind bool
	// Locks is used to sync background task scheduling.
	// RefreshBehind depends on Locks.
	//
	// default: process level locking
	Locks Locks
	// contains filtered or unexported fields
}

type EntityRepository[ENT, ID any] interface {
	crud.Creator[ENT]
	crud.Updater[ENT]
	crud.Finder[ENT, ID]
	crud.Deleter[ID]
	crud.ByIDsFinder[ENT, ID]
	crud.Saver[ENT]
}

type Hit[ID any] struct {
	ID        HitID `ext:"id"`
	EntityIDs []ID
	Timestamp time.Time
}

type HitID string

type HitRepository[EntID any] interface {
	crud.Saver[Hit[EntID]]
	crud.Finder[Hit[EntID], HitID]
	crud.Deleter[HitID]
}

type Interface[ENT, ID any] interface {
	CachedQueryOne(ctx context.Context, hid HitID, query QueryOneFunc[ENT]) (_ent ENT, _found bool, _err error)
	CachedQueryMany(ctx context.Context, hid HitID, query QueryManyFunc[ENT]) (iter.Seq2[ENT, error], error)
	InvalidateCachedQuery(ctx context.Context, hid HitID) error
	InvalidateByID(ctx context.Context, id ID) (rErr error)
	DropCachedValues(ctx context.Context) error
}

type Invalidator[ENT, ID any] struct {
	// CheckEntity checks an entity which is being invalidated, and using its properties,
	// you can construct the entity values
	CheckEntity func(ent ENT) []HitID
	// CheckHit meant to check a Hit to decide if it needs to be invalidated.
	// If CheckHit returns with true, then the hit will be invalidated.
	CheckHit func(hit Hit[ID]) bool
}

type Locks interface {
	guard.NonBlockingLockerFactory[HitID]
}

type Query struct {
	// Name is the name of the repository's query operation.
	// A method name or any unique deterministic name is sufficient.
	Name constant.String
	// ARGS contain parameters to the query that can affect the query result.
	// Supplying the ARGS ensures that a query call with different arguments cached individually.
	// Request lifetime related values are not expected to be part of ARGS.
	// ARGS should contain values that are serializable.
	ARGS QueryARGS
	// Version can help supporting multiple version of the same cached operation,
	// so if the application rolls out with a new version, that has different behaviour or fifferend signature
	// these values can be distringuesed
	Version int
}

type QueryARGS map[string]any

type QueryManyFunc[ENT any] func(ctx context.Context) (iter.Seq2[ENT, error], error)

type QueryOneFunc[ENT any] func(ctx context.Context) (_ ENT, found bool, _ error)

type RefreshCache[T any] struct {
	// Refresh [REQUIRED] is a mandatory function that fetches a new value when the current cache entry is expired or missing.
	//
	// This must be provided; otherwise, calls to Load will panic.
	Refresh func(ctx context.Context) (T, error)
	// IsExpired [OPTIONAL] is custom expiration checker.
	// If set, it determines whether the current cached value has expired.
	//
	// The function takes a context and the cached value T as inputs, returning true if expired or false otherwise.
	// Errors returned by this function are propagated to callers of Load().
	IsExpired func(ctx context.Context, v T) (bool, error)
	// TimeToLive [OPTIONAL] is a duration specifying how long the cached value remains valid before automatic refresh occurs.
	//
	// A zero or negative value disables TTL-based expiration.
	TimeToLive time.Duration
	// contains filtered or unexported fields
}

type Repository[ENT, ID any] interface {
	comproto.OnePhaseCommitProtocol
	Entities() EntityRepository[ENT, ID]
	Hits() HitRepository[ID]
}

type Source[ENT, ID any] interface {
	crud.ByIDFinder[ENT, ID]
}