fix: make cache bypass actually refresh and stay uncached

[cursor]

Bug and impact

Two cache-bypass paths could serve or advertise the wrong content:

1. Custom key force string — Following the documented custom key shape [cacheKey, req.query.force], a request with ?force=true reported X-Cache-Status: BYPASS and Cache-Control: no-store but still returned the stale cached body without calling .get() again.
2. null/undefined .get() bypass — Documented as preventing caching (e.g. error/fallback responses), but responses still sent Cache-Control: public, max-age=…, so shared caches/CDNs could store that body for the default TTL.

Root cause

1. @keyvhq/memoize only treats forceExpiration === true as a forced refresh. Query-string values are strings ('true'), so memoize kept the hit while this package's header logic treated any truthy value as BYPASS.
2. setHeaders always built public cacheable headers unless forceExpiration was set; a storage bypass (raw == null) did not opt out of shared HTTP caching.

Fix

• Coerce the custom key's force flag with Boolean(forceExpiration) before passing it to memoize.
• When memoize produces no payload (raw == null), send private, no-cache, no-store, max-age=0 (status remains MISS).

Validation

• Added regression tests for custom-key ?force=true refresh and null-bypass Cache-Control.
• npm test: 29/29 passed.

  

---

Note

Medium Risk
Changes HTTP Cache-Control and memoize key semantics for bypass paths; behavior shifts for custom keys and null .get() responses but is covered by new tests.

Overview
Fixes two mismatches between HTTP cache headers/status and what @keyvhq/memoize actually does.

Custom key bypass: Array keys [cacheKey, forceFlag] now go through memoKey, which passes Boolean(forceFlag) into memoize so a truthy query value (e.g. ?force=true) triggers a real refresh instead of BYPASS headers with a stale body. README notes that any present force query value is truthy (including ?force=false); use an explicit boolean in key for value-based semantics.

Null/undefined .get(): When memoize returns no payload (raw == null), responses get private, no-cache, no-store, max-age=0 via a new preventCaching flag in setHeaders, so bypass/error paths are not advertised as publicly cacheable.

Regression tests cover null-bypass Cache-Control and custom-key force refresh behavior.

^{Reviewed by Cursor Bugbot for commit 1cc85ce. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit c427c12. Configure here.}