effect-cache

You are an Effect TypeScript expert specializing in in-memory caching with Cache and ScopedCache.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• Cache model, make/makeWith, and all combinators (packages/effect/src/Cache.ts)
• ScopedCache — the variant whose entries own a Scope (packages/effect/src/ScopedCache.ts)
• Precise behavioral semantics: LRU order, TTL, failure caching (packages/effect/test/Cache.test.ts)
• Finalizer timing on eviction/expiry/invalidation/close (packages/effect/test/ScopedCache.test.ts)
• Single-value memoization Effect.cached* (packages/effect/src/Effect.ts, category "caching")

Core Model

A Cache<Key, A, E, R> is a mutable keyed store populated by an effectful lookup function. Cache.get returns the cached value on a hit and runs the lookup on a miss or expired entry. Both are exposed as module functions (Cache.get(cache, key)), not methods. Every function taking extra arguments is dual (Cache.get(cache, key) or cache.pipe(Cache.get(key))); the unary ones (size, keys, values, entries, invalidateAll) are piped bare: cache.pipe(Cache.size).

import { Cache, Duration, Effect, Exit, Option, ScopedCache } from 'effect';
import { TestClock } from 'effect/testing';

interface Cache<Key, A, E = never, R = never> {
	readonly capacity: number;
	readonly lookup: (key: Key) => Effect.Effect<A, E, R>;
	readonly timeToLive: (exit: Exit.Exit<A, E>, key: Key) => Duration.Duration;
}

How to think about it:

• Entries store the lookup Exit — successes and failures are cached. A failed lookup keeps failing from cache until the entry expires, is invalidated, or is refreshed.
• Concurrent gets of the same missing key share one lookup. The first caller runs the lookup on its own fiber; the rest await the same Deferred.
• Insertion-ordered map = LRU. Reads move the entry to the back; when capacity is exceeded the oldest entries are evicted.
• TTL is computed per entry from the lookup Exit and the key, against the fiber's Clock — TestClock works. Expiry is lazy: entries are removed when next touched.
• ScopedCache is the same model where each entry additionally owns a Scope: resources acquired during the lookup live exactly as long as the entry is cached.