Skip to main content

Class: TypedCache<K, V>

Defined in: src/utils/cache.ts:141

Generic in-memory cache with optional TTL and LRU eviction.

Remarks​

The implementation uses a Map to store entries and maintains lastAccessed timestamps for LRU eviction. When maxSize is reached a single entry is evicted (the one with the oldest lastAccessed). This selection is O(n) over the number of entries.

Type Parameters​

K​

K

Type of cache keys.

V​

V

Type of cached values.

Constructors​

Constructor​

new TypedCache<K, V>(options?: CacheOptions): TypedCache<K, V>

Defined in: src/utils/cache.ts:195

Create a new cache instance.

Parameters​

options?​

CacheOptions = {}

Cache configuration. Accepts either CacheOptions or CACHE_CONFIG format.

Returns​

TypedCache<K, V>

Default Value​

An instance will use maxSize 100 and no default TTL when omitted.

Properties​

cache​

private readonly cache: Map<K, CacheEntry<V>>

Defined in: src/utils/cache.ts:151

Internal

Internal Map storing cache entries with metadata.

Remarks​

This map contains the actual cached data along with timing metadata used for TTL expiration and LRU eviction calculations.

generation​

private generation: number = 0

Defined in: src/utils/cache.ts:161

Cache generation counter.

Remarks​

Incremented whenever the cache is cleared. Used by higher-level helpers (for example getCachedOrFetch) to avoid caching values fetched before an invalidation/clear event.

defaultTtl​

private readonly defaultTtl: number | undefined

Defined in: src/utils/cache.ts:173

Internal

Default time-to-live for cache entries in milliseconds.

Remarks​

When set, all entries without an explicit TTL will expire after this duration. If undefined, entries persist until manually evicted or removed by LRU eviction.

maxSize​

private readonly maxSize: number

Defined in: src/utils/cache.ts:185

Internal

Maximum number of entries allowed in the cache.

Remarks​

When this limit is reached, the least recently used entry is evicted to make room for new entries. Defaults to 100 if not specified in constructor options.

Accessors​

size​

Get Signature​

get size(): number

Defined in: src/utils/cache.ts:219

Current number of entries in the cache.

Returns​

number

Number of stored entries.

Methods​

cleanup()​

cleanup(): void

Defined in: src/utils/cache.ts:234

Remove entries that have exceeded their TTL from this cache instance.

Returns​

void

Remarks​

Iterates the underlying Map and deletes expired items. This is a best-effort maintenance operation and safe to call periodically (for example from a scheduled timer). It does not return which keys were removed.

clear()​

clear(): void

Defined in: src/utils/cache.ts:252

Remove all entries from the cache.

Returns​

void

Remarks​

Clears the internal Map and resets the cache to empty.

getGeneration()​

getGeneration(): number

Defined in: src/utils/cache.ts:264

Returns the current cache generation.

Returns​

number

Remarks​

Consumers can capture this value before starting a long-running fetch and ensure the cache has not been invalidated before storing results.

delete()​

delete(key: K): boolean

Defined in: src/utils/cache.ts:277

Delete a specific key from the cache.

Parameters​

key​

K

The cache key to remove.

Returns​

boolean

True if the key existed and was removed; false otherwise.

get()​

get(key: K): V | undefined

Defined in: src/utils/cache.ts:291

Retrieve a value if present and not expired.

Parameters​

key​

K

The cache key to look up.

Returns​

V | undefined

The cached value, or undefined when the key does not exist or the entry has expired.

has()​

has(key: K): boolean

Defined in: src/utils/cache.ts:321

Check whether a non-expired entry exists for the given key.

Parameters​

key​

K

The cache key to test.

Returns​

boolean

true when a valid (non-expired) value exists; false otherwise.

set()​

set(key: K, value: V, ttl?: number): void

Defined in: src/utils/cache.ts:341

Insert or update an entry in the cache and optionally specify a per-entry TTL that overrides the cache's default TTL.

Parameters​

key​

K

The cache key to set.

value​

V

The value to store under the provided key.

ttl?​

number

Optional per-entry TTL in milliseconds; when omitted the cache's defaultTtl (if any) will apply.

Returns​

void

Remarks​

If the cache size would exceed CacheOptions.maxSize a single least-recently-used entry is evicted. LRU selection scans all entries and has O(n) cost.