first commit

docs/security-stack/security/hibp/src/cache/cache.md

@@ -0,0 +1,94 @@
+# `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.