TimedCache

TimedCache is a generic, TTL-based in-memory cache. Items are fetched lazily via a getter delegate on first access, then served from cache until they expire. When the cache exceeds its size limit, expired entries are automatically evicted.

Import

import crate.TimedCache;

Creating a Cache

The constructor takes a getter delegate, an optional TTL duration, and an optional maximum size:

// Getter that fetches the value for a given key
string fetchFromDb(string id) {
    return db.find(id);
}

// Default: 1 second TTL, 200 items max
auto cache = new TimedCache!string(&fetchFromDb);

// Custom: 30 second TTL, 500 items max
auto cache = new TimedCache!string(&fetchFromDb, 30.seconds, 500);

The getter delegate signature is T delegate(string) — it receives a key and returns the cached value type.

API

get(string key)

Returns the cached value for key. If the key is missing or expired, the getter delegate is called and the result is stored before returning.

auto value = cache.get("item-42");

Accessing a cached item extends its lifetime slightly (by 10ms), so frequently accessed items stay warm.

When get causes the cache to exceed storedSize, a reindex is triggered automatically to evict expired entries.

exists(string key)

Returns true if key is in the cache and has not expired.

if (cache.exists("item-42")) {
    // still cached
}

reindex()

Manually removes all expired entries from the cache. This is called automatically when the cache exceeds its size limit, but you can also call it explicitly.

cache.reindex();

Constructor Parameters

Parameter	Type	Default	Description
getter	T delegate(string)	required	Called to fetch the value when a key is missing or expired
validationTime	Duration	1.seconds	How long items remain valid after last access
storedSize	size_t	200	Maximum number of entries before auto-eviction

Example

import crate.TimedCache;
import std.datetime;

int dbCalls;

string loadUser(string id) {
    dbCalls++;
    return "user-" ~ id;
}

auto cache = new TimedCache!string(&loadUser, 5.seconds, 100);

cache.get("alice");  // calls loadUser, dbCalls == 1
cache.get("alice");  // served from cache, dbCalls == 1

cache.exists("alice");  // true
cache.exists("bob");    // false