@ultimat3/cache 9.0.0 → 10.0.0

package/CLAUDE.md

@@ -252,6 +252,13 @@ Tier 1. Tagged caching + THE invalidation graph.
   and clears nothing, which is the one CDN failure no later read can catch.
 - `retryable` on `X_CACHE_PURGE_FAILED` is derived, never guessed: 408/409/425/429 and 5xx, plus
   any request that never got a status. That table lives in `purge-http.ts` and is edited there.
+  **It reaches `error.retry` too, `As of 2026-08-23`** — `CachePurgeFailedError` passes
+  `retry: input.retryable ? 'retryable' : 'terminal'`. Without it the constructor fell back to
+  `retryFor('X_CACHE_PURGE_FAILED')`, this package registers no retry class, and the default is
+  `terminal`: a 429 serialised as `{ "retry": "terminal", "meta": { "retryable": true } }` — one
+  error answering the retry question two ways, with `errorRetry()` (the one question a retry loop
+  asks) giving the wrong one. Per-INSTANCE, never `registerErrorRetry`: one code covers a 401 that
+  will never land and a 429 that will.
 - `X_CACHE_PURGE_FAILED` means a provider refused. A batch size that is not a positive integer is
   this package miswired, so `chunked()` raises `X_CACHE_DRIVER_UNAVAILABLE` instead — and it raises
   it *before* the loop, because a `0` spins forever and a `NaN` yields one empty batch, a purge that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cache",
-  "version": "9.0.0",
+  "version": "10.0.0",
   "description": "Tagged caching: request memo, LRU, Redis, CDN — one invalidation graph",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "9.0.0"
+    "@ultimat3/core": "10.0.0"
   }
 }

package/src/errors.ts

@@ -33,8 +33,6 @@ registerErrorCodes(
   Object.fromEntries(Object.entries(CACHE_ERROR_TITLES).map(([code, title]) => [code, { title }])),
 );
 
-const docsFor = (code: CacheErrorCode): string => `https://ultimate.dev/errors/${code}`;
-
 /** A tier's backing store is missing at runtime (no Redis binding, no CDN token). */
 export class CacheDriverUnavailableError extends UltimateError {
   constructor(input: { driver: string; cause: string; fix: string }) {
@@ -42,7 +40,6 @@ export class CacheDriverUnavailableError extends UltimateError {
       code: 'X_CACHE_DRIVER_UNAVAILABLE',
       cause: `cache tier "${input.driver}" is unavailable: ${input.cause}`,
       fix: input.fix,
-      docs: docsFor('X_CACHE_DRIVER_UNAVAILABLE'),
     });
   }
 }
@@ -59,7 +56,6 @@ export class CacheTagUnknownError extends UltimateError {
         input.known.length > 0 ? input.known.join(', ') : 'none'
       })`,
       fix: 'x manifest',
-      docs: docsFor('X_CACHE_TAG_UNKNOWN'),
     });
   }
 }
@@ -71,7 +67,6 @@ export class CacheTooLargeError extends UltimateError {
       code: 'X_CACHE_TOO_LARGE',
       cause: `entry "${input.key}" is ${input.bytes}B, over the ${input.tier} budget of ${input.maxBytes}B`,
       fix: `raise cache.${input.tier}.maxBytes in app.config.ts, or cache a projection instead of the row`,
-      docs: docsFor('X_CACHE_TOO_LARGE'),
     });
   }
 }
@@ -93,7 +88,6 @@ export class CacheTtlInvalidError extends UltimateError {
         input.ttlMs,
       )}; a TTL is a positive, finite number of milliseconds`,
       fix: `cache.write('${input.key}', value, { ttlMs: 60_000 })   # or drop the option for the tier default; a value you do not want held is one you do not write`,
-      docs: docsFor('X_CACHE_TTL_INVALID'),
       meta: { key: input.key, ttlMs: input.ttlMs, tier: input.tier },
     });
   }
@@ -116,7 +110,6 @@ export class CacheJitterInvalidError extends UltimateError {
         input.jitterFraction,
       )}; a jitter fraction is a finite number in [0, 1)`,
       fix: `set cache.${input.tier}.jitterFraction in app.config.ts to a value in [0, 1) — 0.05 is the default, 0 disables jitter`,
-      docs: docsFor('X_CACHE_JITTER_INVALID'),
       meta: { tier: input.tier, jitterFraction: input.jitterFraction },
     });
   }
@@ -141,7 +134,11 @@ export class CachePurgeFailedError extends UltimateError {
       code: 'X_CACHE_PURGE_FAILED',
       cause: `${input.driver} refused the purge${status}: ${input.detail}`,
       fix: input.fix,
-      docs: docsFor('X_CACHE_PURGE_FAILED'),
+      // Per-instance rather than `registerErrorRetry`, because one code covers both a 401 (never
+      // worth resending) and a 429 (worth resending unchanged). Without it every purge failure
+      // fell back to the registry's `terminal` while `meta.retryable` said otherwise — one error
+      // answering the retry question two ways.
+      retry: input.retryable ? 'retryable' : 'terminal',
       meta: {
         driver: input.driver,
         retryable: input.retryable,

package/src/purge-fastly.ts

@@ -61,7 +61,10 @@ const fixFor = (status: number): string => {
 function acceptedFrom(body: PurgeBody, batch: readonly string[]): string[] {
   const payload = body.json;
   if (!isRecord(payload)) return [...batch];
-  const named = batch.filter((key) => key in payload);
+  // `Object.hasOwn`, never `in`: a surrogate key named `constructor` or `toString` answered `true`
+  // out of a body that never mentioned it, so `InvalidationReport.tiers` listed keys nothing had
+  // purged — a partial bust reading as a clean one.
+  const named = batch.filter((key) => Object.hasOwn(payload, key));
   return named.length > 0 ? named : [...batch];
 }