Cache
Caches values loaded by an Effect lookup function.
A cache stores successful and failed lookup results, shares an in-progress lookup when multiple callers request the same missing key, and limits entries by capacity and optional time-to-live rules. This module includes helpers for reading, setting, refreshing, invalidating, and inspecting cache contents.
Combinators
Signature
declare function entries<Key, A, E, R>(
self: Cache<Key, A, E, R>,
): Effect<Iterable<[Key, A], any, any>>;Retrieves the value for a key, invoking the lookup function on a cache miss or expired entry.
Details
Concurrent get calls for the same missing key share the same pending lookup. The cache stores the lookup Exit, so failed lookups are cached and will fail again until the entry expires, is invalidated, or is refreshed.
Signature
declare const get: {
<Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect<A, E, R>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<A, E, R>;
};Reads an existing cache entry without invoking the lookup function.
Details
Returns Option.none() when the key is missing or expired, and Option.some when a cached lookup has succeeded. If the entry is still pending, waits for it to complete. If the cached or pending lookup fails, this effect fails with the same error.
Signature
declare const getOption: {
<Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect<Option<A>, E>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<Option<A>, E>;
};getSuccess
Retrieves the value associated with the specified key from the cache, only if it contains a resolved successful value.
Details
This checks only an existing non-expired entry. It returns Option.some when the entry has already resolved successfully, and Option.none for missing, expired, failed, or still-pending entries.
See
Signature
declare const getSuccess: {
<Key, A, R>(key: Key): <E>(self: Cache<Key, A, E, R>) => Effect<Option<A>>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<Option<A>>;
};Checks whether the cache contains an entry for the specified key.
Details
This checks for an existing non-expired entry without invoking the cache lookup function. Expired entries are treated as absent.
Signature
declare const has: {
<Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect<boolean>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<boolean>;
};invalidate
Invalidates the entry associated with the specified key in the cache.
Signature
declare const invalidate: {
<Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect<void>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<void>;
};invalidateAll
Invalidates all entries in the cache.
Signature
declare function invalidateAll<Key, A, E, R>(self: Cache<Key, A, E, R>): Effect<void>;invalidateWhen
Invalidates the entry associated with the specified key in the cache when the predicate returns true for the cached value.
Signature
declare const invalidateWhen: {
<Key, A>(key: Key, f: Predicate<A>): <E, R>(self: Cache<Key, A, E, R>) => Effect<boolean>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, f: Predicate<A>): Effect<boolean>;
};Retrieves all active keys from the cache, automatically filtering out expired entries.
Signature
declare function keys<Key, A, E, R>(self: Cache<Key, A, E, R>): Effect<Iterable<Key, any, any>>;Forces a refresh of the value associated with the specified key in the cache.
Details
It will always invoke the lookup function to construct a new value, overwriting any existing value for that key.
Signature
declare const refresh: {
<Key, A>(key: Key): <E, R>(self: Cache<Key, A, E, R>) => Effect<A, E, R>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key): Effect<A, E, R>;
};Sets the value associated with the specified key in the cache. This will overwrite any existing value for that key, skipping the lookup function.
Signature
declare const set: {
<Key, A>(key: Key, value: A): <E, R>(self: Cache<Key, A, E, R>) => Effect<void>;
<Key, A, E, R>(self: Cache<Key, A, E, R>, key: Key, value: A): Effect<void>;
};Retrieves the approximate number of entries in the cache.
Details
Note that expired entries are counted until they are accessed and removed. The size reflects the current number of entries stored, not the number of valid entries.
Signature
declare function size<Key, A, E, R>(self: Cache<Key, A, E, R>): Effect<number>;Retrieves all successfully cached values from the cache, excluding failed lookups and expired entries.
Signature
declare function values<Key, A, E, R>(self: Cache<Key, A, E, R>): Effect<Iterable<A, any, any>>;Constructors
Creates a cache with a fixed time-to-live for all entries.
Details
This is the basic cache constructor where all entries share the same TTL. The lookup function will be called when a key is not found or has expired.
Signature
declare function make<
Key,
A,
E = never,
R = never,
ServiceMode extends "lookup" | "construction" = never,
>(options: {
readonly capacity: number;
readonly lookup: (key: Key) => Effect<A, E, R>;
readonly requireServicesAt?: ServiceMode;
readonly timeToLive?: Input;
}): Effect<
Cache<Key, A, E, "lookup" extends ServiceMode ? R : never>,
never,
"lookup" extends ServiceMode ? never : R
>;Creates a cache with dynamic time-to-live based on the result and key.
When to use
Use when you need different cache entry lifetimes based on the lookup result or key characteristics.
Details
The timeToLive function receives both the exit result and the key, allowing for flexible TTL policies based on success/failure state and key characteristics.
See
makefor a simpler cache constructor with a fixed time-to-live for all entries
Signature
declare function makeWith<
Key,
A,
E = never,
R = never,
ServiceMode extends "lookup" | "construction" = never,
>(
lookup: (key: Key) => Effect<A, E, R>,
options: {
readonly capacity: number;
readonly requireServicesAt?: ServiceMode;
readonly timeToLive?: (exit: Exit<A, E>, key: Key) => Input;
},
): Effect<
Cache<Key, A, E, "lookup" extends ServiceMode ? R : never>,
never,
"lookup" extends ServiceMode ? never : R
>;Models
A cache interface that provides a mutable key-value store with automatic TTL management, capacity limits, and lookup functions for cache misses.
Signature
interface Cache<in out Key, in out A, in out E = never, out R = never> extends Pipeable {
readonly "~effect/Cache": "~effect/Cache";
readonly capacity: number;
readonly lookup: (key: Key) => Effect<A, E, R>;
readonly map: MutableHashMap<Key, Entry<A, E>>;
readonly timeToLive: (exit: Exit<A, E>, key: Key) => Duration;
}Represents a low-level cache entry containing a deferred lookup result and an optional expiration timestamp.
When to use
Use when inspecting a Cache's low-level map and you need the stored deferred lookup result or expiration timestamp for a key.
Details
An expiresAt value of undefined means the entry does not expire.
See
Cachefor the public cache API that manages entries through combinators
Signature
interface Entry<A, E> {
awaiters: number;
expiresAt: number | undefined;
readonly fiber: Fiber<A, E>;
await(this: Entry<A, E>): Effect<A, E>;
}
Retrieves all key-value pairs from the cache as an iterable. This function only returns entries with successfully resolved values, filtering out any failed lookups or expired entries.
Gotchas
Expired entries are removed from the cache while
entriesfilters them out.See
keysfor retrieving only cached keysvaluesfor retrieving only cached values