first commit

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

@@ -0,0 +1,54 @@
+# `cache/null.ts`
+
+## Purpose
+
+`NullHibpCache<V>` is the always-miss adapter used by `HibpClient` when
+the caller explicitly opts out of caching (`cache: null`). It satisfies
+the `HibpCacheLike<V>` shape so the orchestrator code stays branch-free —
+every cache call goes through the same interface, but the null adapter
+makes every lookup a miss and every store a no-op.
+
+## Features
+
+- `get` always returns `undefined`.
+- `set` is a no-op.
+- `delete` always returns `false`.
+- `size` is always `0`.
+- Zero allocation per call — instances are stateless beyond the JS class
+  identity.
+
+## Usage: Basic Example
+
+```ts
+import { HibpClient, NullHibpCache } from "@suaveplan/hibp";
+
+const client = new HibpClient({ cache: new NullHibpCache() });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { HibpClient } from "@suaveplan/hibp";
+
+// Shorthand: passing `null` resolves to NullHibpCache internally.
+const client = new HibpClient({ cache: null });
+```
+
+## API Reference
+
+- `new NullHibpCache<V>()` — generic, no options.
+- All `HibpCacheLike<V>` methods present and conformant.
+
+## Implementation Notes
+
+Using a dedicated class instead of an inline conditional avoids a
+property branch on every `HibpClient.checkPassword` call. It also keeps
+the public type system honest: a `HibpCacheLike` is always a real cache,
+never `undefined`. Callers who want caching disabled make that intention
+explicit by constructing or asking for `NullHibpCache`. The class is
+generic so consumers of typed cache values (e.g. `Breach[]` caches
+layered on top of the package) still get the right type for their
+`get()` returns when they inject a `NullHibpCache<Breach[]>` instead.
+Tests benefit too — running `checkPassword` against a `NullHibpCache`
+guarantees every call exercises the full fetch+parse path, with no
+hidden cache hits hiding behaviour bugs.