# `cache/cache.ts`

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - lru — `LruHibpCache<V>` is the default cache for `H…
- [lru](./lru.md) — `LruHibpCache<V>` is the default cache for `HibpClient`. It holds up to `LRU_DEFAULT_CAPACITY` entries (10 000) with `L…
- [null](./null.md) — `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](./lru.md) — `LruHibpCache<V>` is the default cache for `HibpClient`. It holds up to `LRU_DEFAULT_CAPACITY` entries (10 000) with `L…
- [null](./null.md) — `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](./lru.md) — `LruHibpCache<V>` is the default cache for `HibpClient`. It holds up to `LRU_DEFAULT_CAPACITY` entries (10 000) with `L…
- [null](./null.md) — `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](./lru.md) — `LruHibpCache<V>` is the default cache for `HibpClient`. It holds up to `LRU_DEFAULT_CAPACITY` entries (10 000) with `L…
- [null](./null.md) — `NullHibpCache<V>` is the always-miss adapter used by `HibpClient` when the caller explicitly opts out of caching (`cac…
- [lru](./lru.md) — `LruHibpCache<V>` is the default cache for `HibpClient`. It holds up to `LRU_DEFAULT_CAPACITY` entries (10 000) with `L…
- [null](./null.md) — `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

```ts
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

```ts
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.