`cache/lru.ts`

Purpose

LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with LRU_DEFAULT_TTL_MS (24 h) expiry, keyed by the uppercase 5-hex SHA-1 prefix. The TTL clock is the injectable Clock from @suaveplan/types so tests can advance virtual time without timers. Eviction policy is least-recently-used at capacity plus eager TTL eviction on read.

Features

O(1) get/set/delete over a Map<string, CacheEntry<V>> with recency tracked by insertion order — re-inserting on read bumps the key to the tail.
TTL eviction at access time: stale entries are dropped and reported as cache misses; no background timer is required.
Constructor-time overrides for capacity, ttlMs, and clock so the same class powers production caches, deterministic tests, and experimental tunings.
Key normalisation to uppercase hex on every operation — case-insensitive reads and writes share the same slot.

Usage: Basic Example

import { LruHibpCache } from "@suaveplan/hibp";

const cache = new LruHibpCache<{ pwned: boolean; count: number }>();
cache.set("F3BBB", { pwned: true, count: 1 });
cache.get("f3bbb"); // case-insensitive hit

Usage: Advanced Example

import { LruHibpCache } from "@suaveplan/hibp";

let now = 0;
const cache = new LruHibpCache<number>({
    capacity: 50,
    ttlMs: 5_000,
    clock: () => now,
});
cache.set("A", 1);
now = 4_999;
cache.get("A"); // 1
now = 5_001;
cache.get("A"); // undefined (TTL-evicted)

API Reference

new LruHibpCache<V>(options?) — capacity, ttlMs, clock.
LRU_DEFAULT_CAPACITY = 10_000.
LRU_DEFAULT_TTL_MS = 24 * 60 * 60 * 1000.

Implementation Notes

Insertion-order tracking via JavaScript Map is the canonical O(1) LRU implementation in pure JS. The class avoids setInterval-based eviction because that would require timer cleanup on disposal and add jitter to TTL behaviour; on-read TTL is cheap and deterministic. The capacity loop guards against capacity: 0 by evicting immediately after the insert.

2.1 KiB Raw Blame History

cache/lru.ts