`cache/cache.ts`

(no submodules)

- lru — `LruHibpCache` is the default cache for `H…

lru — LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with `L…
null — NullHibpCache<V> is the always-miss adapter used by HibpClient when the caller explicitly opts out of caching (`cac…
lru — LruHibpCache<V> is the default cache for `H…
lru — LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with `L…
null — NullHibpCache<V> is the always-miss adapter used by HibpClient when the caller explicitly opts out of caching (`cac…
lru — LruHibpCache<V> is the default cache for `H…
lru — LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with `L…
null — NullHibpCache<V> is the always-miss adapter used by HibpClient when the caller explicitly opts out of caching (`cac…
lru — LruHibpCache<V> is the default cache for `H…
lru — LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with `L…
null — NullHibpCache<V> is the always-miss adapter used by HibpClient when the caller explicitly opts out of caching (`cac…
lru — LruHibpCache<V> is the default cache for HibpClient. It holds up to LRU_DEFAULT_CAPACITY entries (10 000) with `L…
null — NullHibpCache<V> is the always-miss adapter used by HibpClient when the caller explicitly opts out of caching (`cac…

Purpose

Declares the HibpCacheLike<V> interface — the universal contract every cache backend implements. The HibpClient orchestrator is parametric in this type, so swapping LruHibpCache for a Redis-backed adapter is a constructor option, not a refactor. Living at this layer means downstream storage choices stay isolated from the range-API logic.

Features

Four-method surface: get, set, delete, size.
Generic over value type V so a cache of PwnedResult, a cache of raw range bodies, and a cache of typed Breach[] all use the same shape.
Synchronous semantics — async backends adapt by buffering or by resolving the cache outside the request critical path.
Zero runtime — purely a TypeScript interface.

Usage: Basic Example

import type { HibpCacheLike } from "@suaveplan/hibp";

class MapCache implements HibpCacheLike<{ pwned: boolean; count: number }> {
    private store = new Map<string, { pwned: boolean; count: number }>();
    get(k: string) { return this.store.get(k); }
    set(k: string, v: { pwned: boolean; count: number }) { this.store.set(k, v); }
    delete(k: string) { return this.store.delete(k); }
    get size() { return this.store.size; }
}

Usage: Advanced Example

import type { HibpCacheLike } from "@suaveplan/hibp";

export class CountingCache<V> implements HibpCacheLike<V> {
    public hits = 0;
    public misses = 0;
    public constructor(private inner: HibpCacheLike<V>) {}
    get(k: string) {
        const v = this.inner.get(k);
        if (v === undefined) this.misses++;
        else this.hits++;
        return v;
    }
    set(k: string, v: V) { this.inner.set(k, v); }
    delete(k: string) { return this.inner.delete(k); }
    get size() { return this.inner.size; }
}

API Reference

HibpCacheLike<V> — interface with get, set, delete, size.

Implementation Notes

The interface is synchronous on purpose: every documented HIBP cache backend is in-memory or microsecond-bound, so the simpler shape is worth it. If a future use case requires an async cache, the HibpClient will need a parallel HibpAsyncCacheLike rather than mutating this contract and breaking every existing implementation. The size field is deliberately a getter rather than a method so adapters wrapping an underlying Map can return the map's size directly; method-style would force an extra function call per probe. Consumers wiring exotic backends — Redis, IndexedDB, OPFS — typically wrap their async client in a write-through cache that buffers writes and lazily refreshes reads, exposing this synchronous shape to HibpClient while preserving durability behind the scenes.

4.4 KiB Raw Blame History

cache/cache.ts