95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# `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.
|