loadingcache

type Cache[Key comparable, Value any] interface {
	// Get returns the value associated with a given key. If no entry exists for
	// the provided key, loadingcache.ErrKeyNotFound is returned.
	Get(ctx context.Context, key Key) (Value, error)

	// Put adds a value to the cache identified by a key.
	// If a value already exists associated with that key, it
	// is replaced.
	Put(key Key, value Value)

	// Invalidate removes keys from the cache. If a key does not exists it is a noop.
	Invalidate(keys ...Key)

	// InvalidateAll invalidates all keys
	InvalidateAll()

	// Close cleans up any resources used by the cache
	Close()

	// Stats returns the curret stats
	Stats() Stats
}

type CacheOption[Key comparable, Value any] func(cacheOptions[Key, Value]) cacheOptions[Key, Value]

type LoadFunc[Key comparable, Value any] func(context.Context, Key) (Value, error)

type LoadingError interface {
	error
	CacheFor() time.Duration
}

type RemovalListener[Key comparable, Value any] func(RemovalNotification[Key, Value])

type RemovalNotification[Key comparable, Value any] struct {
	Key    Key
	Value  Value
	Reason RemovalReason
}

type RemovalReason string

type Stats interface {
	// EvictionCount is the number of times an entry has been evicted
	EvictionCount() int64

	// HitCount the number of times Cache lookup methods have returned a cached value
	HitCount() int64

	// HitRate is the ratio of cache requests which were hits. This is defined as
	// hitCount / requestCount, or 1.0 when requestCount == 0
	HitRate() float64

	// MissCount is the number of times Cache lookup methods have returned an uncached
	// (newly loaded) value
	MissCount() int64

	// MissRate is the ratio of cache requests which were misses. This is defined as
	// missCount / requestCount, or 0.0 when requestCount == 0
	MissRate() float64

	// RequestCount is the number of times Cache lookup methods have returned either a cached or
	// uncached value. This is defined as hitCount + missCount
	RequestCount() int64

	// LoadSuccessCount is the number of times Cache lookup methods have successfully
	// loaded a new value
	LoadSuccessCount() int64

	// LoadErrorCount is the number of times Cache lookup methods threw an exception while loading
	// a new value
	LoadErrorCount() int64

	// LoadErrorRate is the ratio of cache loading attempts which threw exceptions.
	// This is defined as loadExceptionCount / (loadSuccessCount + loadExceptionCount), or 0.0 when
	// loadSuccessCount + loadExceptionCount == 0
	LoadErrorRate() float64

	// LoadCount the total number of times that Cache lookup methods attempted to load new values.
	// This includes both successful load operations, as well as those that threw exceptions.
	// This is defined as loadSuccessCount + loadExceptionCount
	LoadCount() int64

	// LoadTotalTime is the total duration the cache has spent loading new values
	LoadTotalTime() time.Duration

	// AverageLoadPenalty is the average duration spent loading new values. This is defined as
	// totalLoadTime / (loadSuccessCount + loadExceptionCount).
	AverageLoadPenalty() time.Duration
}