@dee-wan/cache 2.0.6 → 2.1.0

package/README.md

@@ -347,7 +347,11 @@ Defaults are 48 targets per batch, 4 concurrent requests across all warmup batch
 
 `createIntentWarmup(cooldownMs?, now?)` warms reads on navigation intent, without storing response values. Call `setScope(siteAndActor)` before use and `warm(key, async isCurrent => ...)` on mouse hover or keyboard focus. One task runs; only the latest waiting intent remains. Check `isCurrent()` between sequential reads. Successful tasks cool for 60 seconds by default. Scope changes and `invalidate()` clear waiting tasks and cooldowns; old completions cannot warm a new scope. Use silent, bounded, read-only requests with the same URL, credentials and headers as normal reads. Do not adopt results into active editor stores or start a startup fanout.
 
-`cacheReadValue` from `@dee-wan/cache/scoped-read` provides a Cache API value cache without D1 or a Durable Object. Pass a nonempty `namespace`, a bounded structured `key`, and a `validate` type guard with the source loader. Include every authorization and result-varying scope in the key; do not put credentials in cached values. `ttlMs` defaults to 5000; it cannot exceed 5000 unless `maxTtlMs` explicitly raises the limit (up to 300000). `maxBytes` defaults to 1,500,000 and can be lowered. Optional `cache` and `now` allow a Cache API implementation and clock to be supplied. Cache failures, invalid values, and expired entries fall back to the loader; loader errors propagate. Expiry starts before the loader runs.
+`cacheReadValue` from `@dee-wan/cache/scoped-read` provides a Cache API value cache without D1 or a Durable Object. Pass a nonempty `namespace`, a bounded structured `key`, and a `validate` type guard with the source loader. Include every authorization and result-varying scope in the key; do not put credentials in cached values. `ttlMs` defaults to 5000; it cannot exceed 5000 unless `maxTtlMs` explicitly raises the limit (up to 300000). `maxBytes` defaults to 1,500,000 and can be lowered. Optional `cache` and `now` allow a Cache API implementation and clock to be supplied. Cache failures, invalid values, and expired entries fall back to the loader; loader errors propagate. Expiry starts before the loader runs. Optional `refresh: { aheadMs, waitUntil, load }` refreshes an eligible hit in the background without extending the existing entry; successful reloads receive a new TTL measured from their start.
+
+Refresh loader: read fresh source; close discarded response bodies. Failed or invalid refresh keeps
+the old expiry. Concurrent refreshes dedupe per key and cache. A foreground miss invalidates an older
+refresh; an already-started refresh put completes before the newer foreground put.
 
 ### D1 bookmark client transport
 

package/dist/scoped-read.d.ts

@@ -7,6 +7,11 @@ interface ScopedReadOptions<T> {
     maxBytes?: number;
     cache?: Pick<Cache, 'match' | 'put'>;
     now?: () => number;
+    refresh?: {
+        aheadMs: number;
+        waitUntil: (task: Promise<void>) => void;
+        load: () => Promise<T>;
+    };
 }
 declare function cacheReadValue<T>(options: ScopedReadOptions<T>, load: () => Promise<T>): Promise<T>;
 

package/dist/scoped-read.js

@@ -3,6 +3,9 @@ import { MAX_VALUE_BYTES, createRegionalCache } from './chunk-E6OZZ5UX.js';
 import './chunk-ZCMZJKGN.js';
 
 // src/scoped-read.ts
+var defaultPending = /* @__PURE__ */ new Map();
+var cachePending = /* @__PURE__ */ new WeakMap();
+var pendingCount = 0;
 async function cacheReadValue(options, load) {
   const { namespace, key, validate, ttlMs = 5e3, maxTtlMs = 5e3, maxBytes = MAX_VALUE_BYTES, cache, now = () => Date.now() } = options;
   if (!Number.isSafeInteger(maxTtlMs) || maxTtlMs < 1 || maxTtlMs > 3e5 || !Number.isSafeInteger(ttlMs) || ttlMs < 1 || ttlMs > maxTtlMs) return load();
@@ -10,17 +13,56 @@ async function cacheReadValue(options, load) {
   const regional = createRegionalCache(maxTtlMs, maxBytes, { cache: cache ? () => cache : void 0, now });
   const cacheKey = await regional.regionalKey(ttlMs, ["scoped-read-value-v1", namespace, key]);
   const cached = await regional.regionalRead(cacheKey, ttlMs);
+  let pending = defaultPending;
+  if (cache) {
+    const existing = cachePending.get(cache);
+    if (existing) pending = existing;
+    else {
+      pending = /* @__PURE__ */ new Map();
+      cachePending.set(cache, pending);
+    }
+  }
   try {
     if (cached && validate(cached.value)) {
       limitRegionalDataUntil(cached.expires);
+      const refresh = options.refresh;
+      if (cacheKey && refresh && Number.isSafeInteger(refresh.aheadMs) && refresh.aheadMs > 0 && refresh.aheadMs <= ttlMs && cached.expires - now() <= refresh.aheadMs && !pending.has(cacheKey) && pendingCount < 1024) {
+        const owner = { valid: true };
+        pending.set(cacheKey, owner);
+        pendingCount++;
+        let accepted = false;
+        const task = Promise.resolve().then(async () => {
+          if (!accepted) return;
+          const started2 = now();
+          const value2 = await refresh.load();
+          if (owner.valid && validate(value2)) {
+            owner.put = regional.regionalWrite(cacheKey, ttlMs, started2, value2);
+            await owner.put;
+          }
+        }).catch(() => {
+        }).finally(() => {
+          if (pending.get(cacheKey) === owner) pending.delete(cacheKey);
+          pendingCount--;
+        });
+        try {
+          refresh.waitUntil(task);
+          accepted = true;
+        } catch {
+        }
+      }
       return cached.value;
     }
   } catch {
   }
+  const older = cacheKey ? pending.get(cacheKey) : void 0;
+  if (older) older.valid = false;
   const started = now();
   const value = await load();
   try {
-    if (validate(value)) await regional.regionalWrite(cacheKey, ttlMs, started, value);
+    if (validate(value)) {
+      if (older?.put) await older.put;
+      await regional.regionalWrite(cacheKey, ttlMs, started, value);
+    }
   } catch {
   }
   return value;

package/dist/scoped-read.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/scoped-read.ts"],"names":[],"mappings":";;;;;AAcA,eAAsB,cAAA,CAAkB,SAA+B,IAAA,EAAoC;AACzG,EAAA,MAAM,EAAE,SAAA,EAAW,GAAA,EAAK,QAAA,EAAU,KAAA,GAAQ,KAAM,QAAA,GAAW,GAAA,EAAM,QAAA,GAAW,eAAA,EAAiB,OAAO,GAAA,GAAM,MAAM,IAAA,CAAK,GAAA,IAAM,GAAI,OAAA;AAC/H,EAAA,IAAI,CAAC,MAAA,CAAO,aAAA,CAAc,QAAQ,CAAA,IAAK,QAAA,GAAW,KAAK,QAAA,GAAW,GAAA,IAAW,CAAC,MAAA,CAAO,aAAA,CAAc,KAAK,CAAA,IAAK,KAAA,GAAQ,KAAK,KAAA,GAAQ,QAAA,SAAiB,IAAA,EAAK;AACxJ,EAAA,IAAI,OAAO,SAAA,KAAc,QAAA,IAAY,CAAC,SAAA,CAAU,MAAK,IAAK,CAAC,MAAA,CAAO,aAAA,CAAc,QAAQ,CAAA,IAAK,QAAA,IAAY,KAAK,QAAA,GAAW,eAAA,SAAwB,IAAA,EAAK;AACtJ,EAAA,MAAM,QAAA,GAAW,mBAAA,CAAoB,QAAA,EAAU,QAAA,EAAU,EAAE,KAAA,EAAO,KAAA,GAAQ,MAAM,KAAA,GAAQ,MAAA,EAAW,GAAA,EAAK,CAAA;AACxG,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,CAAS,WAAA,CAAY,OAAO,CAAC,sBAAA,EAAwB,SAAA,EAAW,GAAG,CAAC,CAAA;AAC3F,EAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,YAAA,CAAa,UAAU,KAAK,CAAA;AAC1D,EAAA,IAAI;AACF,IAAA,IAAI,MAAA,IAAU,QAAA,CAAS,MAAA,CAAO,KAAK,CAAA,EAAG;AAAE,MAAA,sBAAA,CAAuB,OAAO,OAAO,CAAA;AAAG,MAAA,OAAO,MAAA,CAAO,KAAA;AAAA,IAAO;AAAA,EACvG,CAAA,CAAA,MAAQ;AAAA,EAAyD;AACjE,EAAA,MAAM,UAAU,GAAA,EAAI;AACpB,EAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,EAAA,IAAI;AACF,IAAA,IAAI,QAAA,CAAS,KAAK,CAAA,EAAG,MAAM,SAAS,aAAA,CAAc,QAAA,EAAU,KAAA,EAAO,OAAA,EAAS,KAAK,CAAA;AAAA,EACnF,CAAA,CAAA,MAAQ;AAAA,EAA8D;AACtE,EAAA,OAAO,KAAA;AACT","file":"scoped-read.js","sourcesContent":["import { createRegionalCache, MAX_VALUE_BYTES } from './d1/regional';\nimport { limitRegionalDataUntil } from './d1/regional-deadline';\n\nexport interface ScopedReadOptions<T> {\n  namespace: string;\n  key: unknown;\n  validate: (value: unknown) => value is T;\n  ttlMs?: number;\n  maxTtlMs?: number;\n  maxBytes?: number;\n  cache?: Pick<Cache, 'match' | 'put'>;\n  now?: () => number;\n}\n\nexport async function cacheReadValue<T>(options: ScopedReadOptions<T>, load: () => Promise<T>): Promise<T> {\n  const { namespace, key, validate, ttlMs = 5000, maxTtlMs = 5000, maxBytes = MAX_VALUE_BYTES, cache, now = () => Date.now() } = options;\n  if (!Number.isSafeInteger(maxTtlMs) || maxTtlMs < 1 || maxTtlMs > 300_000 || !Number.isSafeInteger(ttlMs) || ttlMs < 1 || ttlMs > maxTtlMs) return load();\n  if (typeof namespace !== 'string' || !namespace.trim() || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_VALUE_BYTES) return load();\n  const regional = createRegionalCache(maxTtlMs, maxBytes, { cache: cache ? () => cache : undefined, now });\n  const cacheKey = await regional.regionalKey(ttlMs, ['scoped-read-value-v1', namespace, key]);\n  const cached = await regional.regionalRead(cacheKey, ttlMs);\n  try {\n    if (cached && validate(cached.value)) { limitRegionalDataUntil(cached.expires); return cached.value; }\n  } catch { /* Invalid cache values fall through to the source. */ }\n  const started = now();\n  const value = await load();\n  try {\n    if (validate(value)) await regional.regionalWrite(cacheKey, ttlMs, started, value);\n  } catch { /* Validation failure must not change the source result. */ }\n  return value;\n}\n"]}
+{"version":3,"sources":["../src/scoped-read.ts"],"names":["started","value"],"mappings":";;;;;AAgBA,IAAM,cAAA,uBAAqB,GAAA,EAA4B;AACvD,IAAM,YAAA,uBAAmB,OAAA,EAA6C;AACtE,IAAI,YAAA,GAAe,CAAA;AAEnB,eAAsB,cAAA,CAAkB,SAA+B,IAAA,EAAoC;AACzG,EAAA,MAAM,EAAE,SAAA,EAAW,GAAA,EAAK,QAAA,EAAU,KAAA,GAAQ,KAAM,QAAA,GAAW,GAAA,EAAM,QAAA,GAAW,eAAA,EAAiB,OAAO,GAAA,GAAM,MAAM,IAAA,CAAK,GAAA,IAAM,GAAI,OAAA;AAC/H,EAAA,IAAI,CAAC,MAAA,CAAO,aAAA,CAAc,QAAQ,CAAA,IAAK,QAAA,GAAW,KAAK,QAAA,GAAW,GAAA,IAAW,CAAC,MAAA,CAAO,aAAA,CAAc,KAAK,CAAA,IAAK,KAAA,GAAQ,KAAK,KAAA,GAAQ,QAAA,SAAiB,IAAA,EAAK;AACxJ,EAAA,IAAI,OAAO,SAAA,KAAc,QAAA,IAAY,CAAC,SAAA,CAAU,MAAK,IAAK,CAAC,MAAA,CAAO,aAAA,CAAc,QAAQ,CAAA,IAAK,QAAA,IAAY,KAAK,QAAA,GAAW,eAAA,SAAwB,IAAA,EAAK;AACtJ,EAAA,MAAM,QAAA,GAAW,mBAAA,CAAoB,QAAA,EAAU,QAAA,EAAU,EAAE,KAAA,EAAO,KAAA,GAAQ,MAAM,KAAA,GAAQ,MAAA,EAAW,GAAA,EAAK,CAAA;AACxG,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,CAAS,WAAA,CAAY,OAAO,CAAC,sBAAA,EAAwB,SAAA,EAAW,GAAG,CAAC,CAAA;AAC3F,EAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,YAAA,CAAa,UAAU,KAAK,CAAA;AAC1D,EAAA,IAAI,OAAA,GAAU,cAAA;AACd,EAAA,IAAI,KAAA,EAAO;AACT,IAAA,MAAM,QAAA,GAAW,YAAA,CAAa,GAAA,CAAI,KAAK,CAAA;AACvC,IAAA,IAAI,UAAU,OAAA,GAAU,QAAA;AAAA,SACnB;AAAE,MAAA,OAAA,uBAAc,GAAA,EAAI;AAAG,MAAA,YAAA,CAAa,GAAA,CAAI,OAAO,OAAO,CAAA;AAAA,IAAG;AAAA,EAChE;AACA,EAAA,IAAI;AACF,IAAA,IAAI,MAAA,IAAU,QAAA,CAAS,MAAA,CAAO,KAAK,CAAA,EAAG;AACpC,MAAA,sBAAA,CAAuB,OAAO,OAAO,CAAA;AACrC,MAAA,MAAM,UAAU,OAAA,CAAQ,OAAA;AACxB,MAAA,IAAI,QAAA,IAAY,OAAA,IAAW,MAAA,CAAO,aAAA,CAAc,OAAA,CAAQ,OAAO,CAAA,IAAK,OAAA,CAAQ,OAAA,GAAU,CAAA,IAAK,OAAA,CAAQ,OAAA,IAAW,SAAS,MAAA,CAAO,OAAA,GAAU,GAAA,EAAI,IAAK,OAAA,CAAQ,OAAA,IAAW,CAAC,OAAA,CAAQ,GAAA,CAAI,QAAQ,CAAA,IAAK,YAAA,GAAe,IAAA,EAAM;AACjN,QAAA,MAAM,KAAA,GAAwB,EAAE,KAAA,EAAM,IAAA,EAAK;AAC3C,QAAA,OAAA,CAAQ,GAAA,CAAI,UAAU,KAAK,CAAA;AAC3B,QAAA,YAAA,EAAA;AACA,QAAA,IAAI,QAAA,GAAW,KAAA;AACf,QAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,OAAA,EAAQ,CAAE,KAAK,YAAY;AAC9C,UAAA,IAAI,CAAC,QAAA,EAAU;AACf,UAAA,MAAMA,WAAU,GAAA,EAAI;AACpB,UAAA,MAAMC,MAAAA,GAAQ,MAAM,OAAA,CAAQ,IAAA,EAAK;AACjC,UAAA,IAAI,KAAA,CAAM,KAAA,IAAS,QAAA,CAASA,MAAK,CAAA,EAAG;AAClC,YAAA,KAAA,CAAM,MAAM,QAAA,CAAS,aAAA,CAAc,QAAA,EAAU,KAAA,EAAOD,UAASC,MAAK,CAAA;AAClE,YAAA,MAAM,KAAA,CAAM,GAAA;AAAA,UACd;AAAA,QACF,CAAC,CAAA,CAAE,KAAA,CAAM,MAAM;AAAA,QAAC,CAAC,CAAA,CAAE,OAAA,CAAQ,MAAM;AAC/B,UAAA,IAAI,QAAQ,GAAA,CAAI,QAAQ,MAAM,KAAA,EAAO,OAAA,CAAQ,OAAO,QAAQ,CAAA;AAC5D,UAAA,YAAA,EAAA;AAAA,QACF,CAAC,CAAA;AACD,QAAA,IAAI;AAAE,UAAA,OAAA,CAAQ,UAAU,IAAI,CAAA;AAAG,UAAA,QAAA,GAAW,IAAA;AAAA,QAAM,CAAA,CAAA,MAAQ;AAAA,QAAiD;AAAA,MAC3G;AACA,MAAA,OAAO,MAAA,CAAO,KAAA;AAAA,IAChB;AAAA,EACF,CAAA,CAAA,MAAQ;AAAA,EAAyD;AACjE,EAAA,MAAM,KAAA,GAAQ,QAAA,GAAW,OAAA,CAAQ,GAAA,CAAI,QAAQ,CAAA,GAAI,MAAA;AACjD,EAAA,IAAI,KAAA,QAAa,KAAA,GAAQ,KAAA;AACzB,EAAA,MAAM,UAAU,GAAA,EAAI;AACpB,EAAA,MAAM,KAAA,GAAQ,MAAM,IAAA,EAAK;AACzB,EAAA,IAAI;AACF,IAAA,IAAI,QAAA,CAAS,KAAK,CAAA,EAAG;AACnB,MAAA,IAAI,KAAA,EAAO,GAAA,EAAK,MAAM,KAAA,CAAM,GAAA;AAC5B,MAAA,MAAM,QAAA,CAAS,aAAA,CAAc,QAAA,EAAU,KAAA,EAAO,SAAS,KAAK,CAAA;AAAA,IAC9D;AAAA,EACF,CAAA,CAAA,MAAQ;AAAA,EAA8D;AACtE,EAAA,OAAO,KAAA;AACT","file":"scoped-read.js","sourcesContent":["import { createRegionalCache, MAX_VALUE_BYTES } from './d1/regional';\nimport { limitRegionalDataUntil } from './d1/regional-deadline';\n\nexport interface ScopedReadOptions<T> {\n  namespace: string;\n  key: unknown;\n  validate: (value: unknown) => value is T;\n  ttlMs?: number;\n  maxTtlMs?: number;\n  maxBytes?: number;\n  cache?: Pick<Cache, 'match' | 'put'>;\n  now?: () => number;\n  refresh?: { aheadMs: number; waitUntil: (task: Promise<void>) => void; load: () => Promise<T> };\n}\n\ntype PendingRefresh = { valid: boolean; put?: Promise<void> };\nconst defaultPending = new Map<string, PendingRefresh>();\nconst cachePending = new WeakMap<object, Map<string, PendingRefresh>>();\nlet pendingCount = 0;\n\nexport async function cacheReadValue<T>(options: ScopedReadOptions<T>, load: () => Promise<T>): Promise<T> {\n  const { namespace, key, validate, ttlMs = 5000, maxTtlMs = 5000, maxBytes = MAX_VALUE_BYTES, cache, now = () => Date.now() } = options;\n  if (!Number.isSafeInteger(maxTtlMs) || maxTtlMs < 1 || maxTtlMs > 300_000 || !Number.isSafeInteger(ttlMs) || ttlMs < 1 || ttlMs > maxTtlMs) return load();\n  if (typeof namespace !== 'string' || !namespace.trim() || !Number.isSafeInteger(maxBytes) || maxBytes <= 0 || maxBytes > MAX_VALUE_BYTES) return load();\n  const regional = createRegionalCache(maxTtlMs, maxBytes, { cache: cache ? () => cache : undefined, now });\n  const cacheKey = await regional.regionalKey(ttlMs, ['scoped-read-value-v1', namespace, key]);\n  const cached = await regional.regionalRead(cacheKey, ttlMs);\n  let pending = defaultPending;\n  if (cache) {\n    const existing = cachePending.get(cache);\n    if (existing) pending = existing;\n    else { pending = new Map(); cachePending.set(cache, pending); }\n  }\n  try {\n    if (cached && validate(cached.value)) {\n      limitRegionalDataUntil(cached.expires);\n      const refresh = options.refresh;\n      if (cacheKey && refresh && Number.isSafeInteger(refresh.aheadMs) && refresh.aheadMs > 0 && refresh.aheadMs <= ttlMs && cached.expires - now() <= refresh.aheadMs && !pending.has(cacheKey) && pendingCount < 1024) {\n        const owner: PendingRefresh = { valid:true };\n        pending.set(cacheKey, owner);\n        pendingCount++;\n        let accepted = false;\n        const task = Promise.resolve().then(async () => {\n          if (!accepted) return;\n          const started = now();\n          const value = await refresh.load();\n          if (owner.valid && validate(value)) {\n            owner.put = regional.regionalWrite(cacheKey, ttlMs, started, value);\n            await owner.put;\n          }\n        }).catch(() => {}).finally(() => {\n          if (pending.get(cacheKey) === owner) pending.delete(cacheKey);\n          pendingCount--;\n        });\n        try { refresh.waitUntil(task); accepted = true; } catch { /* A declined task never starts its loader. */ }\n      }\n      return cached.value;\n    }\n  } catch { /* Invalid cache values fall through to the source. */ }\n  const older = cacheKey ? pending.get(cacheKey) : undefined;\n  if (older) older.valid = false;\n  const started = now();\n  const value = await load();\n  try {\n    if (validate(value)) {\n      if (older?.put) await older.put;\n      await regional.regionalWrite(cacheKey, ttlMs, started, value);\n    }\n  } catch { /* Validation failure must not change the source result. */ }\n  return value;\n}\n"]}

package/docs/cache-contract.md

@@ -59,6 +59,10 @@ request flow. Fail to the database, never to stale cache.
 - Warm URLs: same origin, max 8192 characters. Consumer portability rules can set a lower limit.
 - Scoped value reads default to a 5-second TTL cap. Explicit `maxTtlMs` can raise the cap to
   300000 ms; `ttlMs` must fit that cap. Consumer owns scope, validation and accepted staleness.
+- Optional scoped `refresh`: ahead window, host `waitUntil`, explicit fresh loader. Hits return
+  immediately. Refreshes dedupe per cache and key; source-start TTL stays bounded. Failed or late
+  refresh leaves old expiry unchanged. Foreground misses invalidate older refreshes; an already
+  started refresh put completes before the newer foreground put. Loader owns unused body cleanup.
 - No cold-read, write or auth latency guarantee. Sub-200 ms is a measured warm-read acceptance target.
 
 ## Fences

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dee-wan/cache",
-  "version": "2.0.6",
+  "version": "2.1.0",
   "description": "Prisma read cache for Cloudflare Workers and D1, coordinated by a Durable Object",
   "license": "MIT",
   "type": "module",