Cache

Cache<K, E, V> = object

Defined in: Core/Cache.ts:34

A keyed store that reuses successful results and shares in-flight work.

Three policies govern every lookup:

• Freshness — a stored value younger than ttl is returned without calling the loader.
• Single flight — concurrent lookups for one key share a single load instead of starting their own.
• Reuse after expiry — with staleWhileRevalidate, an expired-but-recent value is returned immediately while one background refresh runs.

Only successful results are stored. A failed load removes its flight and leaves any older stored value in place, so a transient error does not poison later lookups. Because a stored value and a shared flight outlive the caller that started them, load takes no cancellation input.

Example

const users = Cache.make({
  load: (id: string) => Task.Result.tryCatch(() => directory.find(id), { onError: toLookupError })(),
  ttl: Duration.minutes(5),
  staleWhileRevalidate: Duration.minutes(1),
  maxSize: 500,
});

const user = await users.load("u_1");

Type Parameters

K

K

E

E

V

V

Properties

clear

readonly clear: () => void

Defined in: Core/Cache.ts:89

Drops every stored value and in-flight lookup.

Lookups already awaiting a load still receive its result, but nothing is stored afterwards.

Returns

void

See

Cache.invalidate to drop a single key.

---

flush

readonly flush: () => Deferred<void>

Defined in: Core/Cache.ts:101

Waits until no load is running.

A background refresh started by a stale lookup is included, and so is a load started while the flush is waiting, including one started by a loader that runs during the flush. The deferred stays pending while requests keep arriving, so use it before shutdown and in tests, not on a live stream of requests.

Returns

Deferred<void>

See

Cache.clear to drop entries without waiting for their loads.

---

invalidate

readonly invalidate: (key) => void

Defined in: Core/Cache.ts:79

Drops the stored value and any in-flight lookup for a key.

Callers already awaiting that lookup still receive its result, but the result is not stored afterwards.

Parameters

key

K

Returns

void

See

Cache.clear to drop every key at once.

---

load

readonly load: (key) => Deferred<Result<E, V>>

Defined in: Core/Cache.ts:51

Starts a lookup, reusing a stored value when one is fresh enough and joining an in-flight load when one is already running.

The lookup starts when load is called and takes no cancellation input: the load is shared and its value is retained, so cancelling one caller would either cancel work other callers need or report an error that is not an application error. A load must not throw and its deferred must not reject; encode expected failures in the returned Result.

Parameters

key

K

Returns

Deferred<Result<E, V>>

See

Cache.peek to read a stored value without starting a load.

Example

const settings = await cache.load("workspace:42");

---

peek

readonly peek: (key) => Maybe<V>

Defined in: Core/Cache.ts:69

Reads the last stored value for a key without starting a load.

A stale value is returned when one is still stored. This never refreshes the entry and never changes least-recently-used eviction order.

Parameters

key

K

Returns

Maybe<V>

See

Cache.load to load a missing or expired key.

Example

const cached = cache.peek("workspace:42");
if (Maybe.is.none(cached)) {
  console.log("Nothing loaded yet");
}

---

size

readonly size: () => number

Defined in: Core/Cache.ts:106

Returns the number of stored entries. An in-flight lookup is not counted.

Returns

number