item

type CacheItem[T any] interface {

	// Check will check if the item has expired or not.
	//
	// Returns:
	//   - bool: true if the item has expired, false otherwise.
	//
	// If the item has expired, it will be removed from the cache automatically.
	Check() bool

	// Clean will remove the item from the cache.
	//
	// It is generally not necessary to call Clean as items are automatically
	// removed from the cache when they expire. However, calling Clean can be
	// useful in certain cases, such as when the item is no longer needed and
	// you want to free up memory.
	//
	Clean()

	// Duration returns the expiration time of the item.
	//
	// Returns:
	//   - time.Duration: the expiration time of the item.
	//
	// The expiration time is the amount of time after which the item will be
	// removed from the cache if not accessed again.
	//
	// The expiration time is set by the `New` function when creating a new
	// item. It can be set to any positive value of time.Duration.
	//
	// If the expiration time is set to 0, the item will never expire.
	Duration() time.Duration

	// Remain returns the remaining time until the item expires and a boolean
	// indicating whether the item has expired or not.
	//
	// Returns:
	//   - time.Duration: the remaining time until the item expires.
	//   - bool: true if the item has expired, false otherwise.
	//
	// If the item has expired, it will be removed from the cache automatically.
	// If the item has not expired, the function returns the remaining time until
	// the item expires.
	Remain() (time.Duration, bool)

	// Store will store the given value into the cache.
	//
	// Parameters:
	// - T: the value to store into the cache.
	Store(val T)

	// Load will return the value stored into the cache for the given key.
	//
	// Returns:
	//   - T: the value stored into the cache.
	//   - bool: true if the value was found and valid, false otherwise.
	Load() (T, bool)

	// LoadRemain loads the value stored into the cache for the given key and returns
	// the remaining time until the item expires. If no valid value is stored for the
	// given key, it returns false.
	//
	// Returns:
	//   - T: the value stored into the cache for the given key.
	//   - time.Duration: the remaining time until the item expires.
	//   - bool: true if the value was found, false otherwise.
	//
	// If the item has expired, the function returns false.
	// If the item does not exist in the cache, the function returns false.
	//
	// It is safe to call LoadRemain while other goroutines are accessing the cache.
	LoadRemain() (T, time.Duration, bool)
}