coalescing

type Cache[I, T any] interface {
	// Get returns the value cached under the given key, if one exists. On a miss,
	// it returns the value a Loader function obtains using the given input, and
	// caches that value unless the Loader function or this Cache's own
	// configuration directs otherwise. Crucially, implementations MUST coalesce
	// concurrent loads for a single key such that potentially expensive work is
	// done only once, with all applicable, concurrent callers receiving the same
	// result when loading completes. Subsequent callers presenting that key MUST
	// receive the cached value, where one was cached, until it expires.
	//
	// A key and an input are separate arguments because the caller often will
	// have derived the key from the input using a transformation (like a hash,
	// for instance) that cannot be reversed, yet the original input will
	// typically be required by an underlying Loader function in the event of a
	// cache miss.
	//
	// A caller whose own context ends before a load completes stops waiting and
	// receives an error saying so. The load itself carries on, belonging as it
	// does to no one caller, so that those still waiting on it are served.
	Get(ctx context.Context, key string, input I) (T, error)
}

type CacheOptions struct {
	// CleanupInterval is how often to evict expired entries from the Cache. When
	// nil, NewCache() substitutes a default of 1m. A zero or negative duration is
	// invalid and will cause NewCache() to return an error. This field is ignored
	// entirely when CacheNothing is true, there being nothing to evict.
	CleanupInterval *time.Duration
	// DefaultTTL specifies how long to cache values obtained from a Loader
	// function when the TTL also returned from that Loader function is zero. When
	// nil, NewCache() substitutes a default of 1h. A zero or negative duration is
	// valid and indicates the effective DefaultTTL is indefinite.
	DefaultTTL *time.Duration
	// LoadTimeout bounds execution of a Loader function. When nil, NewCache()
	// substitutes a default of 1m. A zero or negative duration is invalid and
	// will cause NewCache() to return an error.
	LoadTimeout *time.Duration
	// CacheNothing, when true, effectively disables all internal caching. When
	// true, DefaultTTL and CleanupInterval have no effect, regardless of their
	// values. This option is useful primarily for tests that wish to
	// deterministically avoid all caching and ensure every call to Cache.Get()
	// executes a Loader function or waits on one already in-flight.
	CacheNothing bool
}

type Loader[I, T any] func(
	ctx context.Context,
	input I,
) (T, *time.Duration, error)