@leejpsd/nextjs-cache-handler 0.4.1 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.0.0
+
+### Major Changes
+
+- [`3c064b5`](https://github.com/leejpsd/nextjs-cache-handler/commit/3c064b549778833a85e817885ff9fd6dde85d66e) Thanks [@leejpsd](https://github.com/leejpsd)! - 1.0 — the public API is now stable under semver.
+
+  Nothing changes for existing 0.4.x users: there are no breaking changes in this release. The version bump is a commitment, not a rewrite. From here, anything that would break a working setup waits for 2.0.
+
+  What that commitment covers:
+  - The eight entry points and everything they export, all of which are now documented in [`docs/api.md`](./docs/api.md) — including the SWR helpers (`partitionEntry`, `shouldServeStale`) that had been exported since 0.1 without being written down.
+  - `CacheHandlerOptions` and its twelve options.
+  - Redis key shapes and the tag-marker wire format, so mixed-version fleets stay readable in both directions during a rolling deploy.
+  - Metric event names.
+
+  Why now: the handler has been running against a real multi-instance deployment (24h live-traffic soak, plus a Redis-reboot drill with zero 5xx), both cache interfaces are exercised end-to-end against Next.js 16.3 stable, and the tag-invalidation semantics were re-derived from the Next.js source and corrected in 0.4.2. The remaining roadmap items (Vercel KV / Upstash adapters, `'use cache: remote'` multi-tier, a `neshClassicCache` equivalent) are additive and do not need a breaking change to land.
+
+## 0.4.2
+
+### Patch Changes
+
+- [`c165563`](https://github.com/leejpsd/nextjs-cache-handler/commit/c16556385a7fb3e8e95dfddc9015dde7a887311a) Thanks [@leejpsd](https://github.com/leejpsd)! - Align `'use cache'` tag invalidation exactly with upstream semantics.
+
+  **Fixed: hard/soft polarity was inverted for `updateTags` without durations.** Next.js calls `updateTags(tags)` with NO durations for hard invalidation (`updateTag()` server actions, single-arg `revalidateTag()`) and `updateTags(tags, { expire })` for profile-based soft invalidation (`revalidateTag(tag, "max")`). The handler treated no-durations as soft, so `updateTag()` — which must guarantee read-your-own-writes — could serve stale content. No-durations is now hard.
+
+  Also in this release:
+  - Soft invalidations now honor their hard deadline: entries serve stale until `durations.expire` seconds after the invalidation, then miss (`Infinity` = never). Tag markers store a `"<stale>|<expired>"` pair; 0.4.1 readers `parseInt` the same marker safely, and legacy bare-number markers are treated as hard-at-timestamp, so mixed-version fleets stay correct in both directions.
+  - Tag-stale entries are served with the truthful timestamp and `revalidate: -1` (the built-in handler's refresh signal) instead of a backdated timestamp, which could cross the `expire` boundary on tight profiles and confused the implicit-tags discard check.
+  - Soft invalidations serve-while-revalidating regardless of `staleWhileRevalidate` (that option now governs time-based staleness only, matching the upstream contract).
+  - `getExpiration` reports only the hard deadline, mirroring the built-in handler.
+  - `expire: 0` entries are no longer persisted in production (mirrors Next 16.3's built-in handler; they are regenerated on every read anyway).
+  - Verified end-to-end against Next.js 16.3.0 stable (both interfaces; build, serve, hard/soft invalidation, ISR SWR).
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -3,18 +3,21 @@
 [![npm](https://img.shields.io/npm/v/@leejpsd/nextjs-cache-handler.svg)](https://www.npmjs.com/package/@leejpsd/nextjs-cache-handler)
 [![license](https://img.shields.io/npm/l/@leejpsd/nextjs-cache-handler.svg)](./LICENSE)
 
-> **`v0.3.0`** — install with
-> `npm install @leejpsd/nextjs-cache-handler`. Production-validated against
-> AWS ECS Fargate with multi-instance Redis (v0.1: 24h live-traffic soak;
-> v0.3: fresh multi-instance verification incl. a live Redis-reboot drill
-> with zero 5xx — see
-> [`docs/staging-verification-2026-08-01.md`](./docs/staging-verification-2026-08-01.md)).
+> **`v1.0.0`** — install with
+> `npm install @leejpsd/nextjs-cache-handler`, or wire everything with
+> `npx nextjs-cache-handler init --yes`. Production-validated against
+> AWS ECS Fargate with multi-instance Redis (24h live-traffic soak and a
+> live Redis-reboot drill with zero 5xx — see
+> [`docs/staging-verification-2026-08-01.md`](./docs/staging-verification-2026-08-01.md)),
+> and exercised end-to-end against **Next.js 16.3** (both cache interfaces).
 >
-> v0.3 adds: **Next.js 15 support** (ISR handler), **reconnect with
-> exponential backoff** (no more permanent memory-only latch), **request-scoped
-> GET deduplication**, transparent **gzip/brotli compression**, **Redis
-> Sentinel** support, a built-in **OpenTelemetry emitter** at `/otel`, and an
-> LRU-bounded memory fallback.
+> v0.4 adds: **build-output cache seeding** (first request after deploy is a
+> HIT), **pub/sub tag propagation** (~3ms cross-instance), **Redis Cluster**
+> e2e in CI, a **CLI** (`init` / `doctor` / `seed`), and agent-native assets
+> (skill, rules, [MCP server](https://www.npmjs.com/package/@leejpsd/nextjs-cache-handler-mcp)).
+> 1.0 freezes the public API under semver — the eight entry points, the
+> `CacheHandlerOptions` surface, the Redis key shapes and tag-marker format,
+> and the metric event names. Upgrading from 0.4.x needs no changes.
 
 ## 🤖 For AI agents
 
@@ -87,7 +90,7 @@ plural interface as ❌ **"Not yet supported - Help needed"**:
 > [`nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache#features)
 > directly before relying on this comparison.
 
-| Feature | this (0.3.0) | @fortedigital 3.2.1 | nextjs-turbo-redis-cache 1.15 |
+| Feature | this (0.4.x) | @fortedigital 3.2.1 | nextjs-turbo-redis-cache 1.15 |
 |---|---|---|---|
 | `cacheHandlers` config (plural) | ✅ | ❌ Help needed | ✅ since 1.11 |
 | `'use cache'` directive | ✅ | ❌ Help needed | ✅ since 1.11 |
@@ -372,8 +375,25 @@ eventual implementation should converge on the same behavior.
 
 ---
 
+## Migrating from another cache handler
+
+Coming from `@neshca/cache-handler` (or its forks like
+`@jadkins89/next-cache-handler`)? There's a dedicated guide with a full
+API/concept mapping, config diff, and a seeding replacement:
+[docs/migrating-from-neshca.md](docs/migrating-from-neshca.md).
+
+---
+
 ## Compatibility
 
+> **Upgrading to Next.js 16.3?** Two behavioral notes: (1) 16.3 changed the
+> internal fetch-cache key format (`v3` → `v4`), so 16.2-era fetch entries
+> become unreadable orphans — deploy with a new `DEPLOYMENT_VERSION` and let
+> the old namespace age out via TTL. (2) An ISR entry found past its
+> `cacheLife` **expire** now triggers a blocking revalidation instead of
+> serving stale (matching `'use cache'` semantics); within
+> `revalidate..expire` stale-while-revalidate is unchanged.
+
 - **Next.js**: `>=15.0.0 <17`
   - `cacheHandler` (singular, ISR): Next **15 and 16** — the handler accepts
     both ctx shapes (Next 15's `ctx.revalidate` / `kindHint`, Next 16's
@@ -404,9 +424,18 @@ ESM and CJS dual-published, full TypeScript types, validated via
   permanent connect-failure latch), request-scoped GET deduplication,
   gzip/brotli compression, Redis Sentinel, built-in OpenTelemetry emitter
   (`/otel`), LRU-bounded memory fallback, ESM peer-loading fixes ✅
-- **v0.4.0** — Build-phase cache seeding (prepopulate prebuilt pages),
-  pub/sub-based tag propagation, Redis Cluster e2e validation, Vercel KV /
-  Upstash adapter, `'use cache: remote'` multi-tier setup
+- **v0.4.0** *(2026-08)* — Build-output cache seeding (`seed` CLI, NX-safe),
+  pub/sub tag propagation, Redis Cluster e2e in CI, `init`/`doctor` CLI,
+  agent assets (skill, rules, MCP server) ✅
+  - *0.4.1* — Buffer serialization fix (~2.8x smaller ISR payloads) ✅
+  - *0.4.2* — upstream-exact tag invalidation semantics: no-durations
+    `updateTags` is hard (`updateTag()` read-your-own-writes), profile
+    durations are soft with a real hard deadline; tag-stale entries are
+    served with `revalidate: -1` instead of a backdated timestamp ✅
+- **v1.0.0** *(2026-08)* — public API frozen under semver; every export
+  documented in [`docs/api.md`](./docs/api.md) ✅
+- **Next** — Vercel KV / Upstash adapters, `'use cache: remote'` multi-tier
+  setup, `neshClassicCache` equivalent. All additive; no 2.0 needed.
 
 ---
 

package/dist/cache-components/index.cjs

@@ -525,7 +525,7 @@ return 1
 `;
 
 // src/shared/lua/revalidate-hard.lua
-var revalidate_hard_default = "-- revalidate-hard.lua\n--\n-- Atomically remove every entry referenced by a tag and stamp the tag's\n-- expiration marker. Used by `updateTags(tags, { expire: 0 })` \u2014 the hard\n-- invalidation path triggered by `updateTag()` server actions in Next.js 16.\n--\n-- KEYS[1]   : tag set key (e.g. \"next-cache:tag:posts\")\n-- KEYS[2]   : tag-expiration marker key (e.g. \"next-cache:tag-expiration:posts\")\n-- ARGV[1]   : current timestamp in milliseconds\n-- ARGV[2]   : marker TTL in seconds (default: 1 day so cross-deployment\n--             readers can still observe the invalidation)\n--\n-- Returns: number of entries that were deleted.\n\nlocal tagKey = KEYS[1]\nlocal markerKey = KEYS[2]\nlocal nowMs = ARGV[1]\nlocal markerTtl = tonumber(ARGV[2])\n\nlocal entries = redis.call('SMEMBERS', tagKey)\nlocal deleted = 0\n\nif #entries > 0 then\n  -- DEL accepts varargs; unpack the entry list.\n  redis.call('DEL', unpack(entries))\n  deleted = #entries\nend\n\n-- Drop the tag set itself; on next SET it'll be recreated by set-with-tags.\nredis.call('DEL', tagKey)\n\n-- Stamp the invalidation timestamp. Readers compare this against an entry's\n-- timestamp inside `getExpiration` to decide whether soft-tag-only entries\n-- should be considered stale.\nredis.call('SET', markerKey, nowMs, 'EX', markerTtl)\n\nreturn deleted\n";
+var revalidate_hard_default = "-- revalidate-hard.lua\n--\n-- Atomically remove every entry referenced by a tag and stamp the tag's\n-- expiration marker. Used by the hard invalidation path \u2014 `updateTags(tags)`\n-- with no durations (updateTag(), single-arg revalidateTag()) or an explicit\n-- `{ expire: 0 }`.\n--\n-- KEYS[1]   : tag set key (e.g. \"next-cache:tag:posts\")\n-- KEYS[2]   : tag-expiration marker key (e.g. \"next-cache:tag-expiration:posts\")\n-- ARGV[1]   : marker value \"<staleMs>|<expiredMs>\" (hard: both equal)\n-- ARGV[2]   : marker TTL in seconds (default: 1 day so cross-deployment\n--             readers can still observe the invalidation)\n--\n-- Returns: number of entries that were deleted.\n\nlocal tagKey = KEYS[1]\nlocal markerKey = KEYS[2]\nlocal marker = ARGV[1]\nlocal markerTtl = tonumber(ARGV[2])\n\nlocal entries = redis.call('SMEMBERS', tagKey)\nlocal deleted = 0\n\nif #entries > 0 then\n  -- DEL accepts varargs; unpack the entry list.\n  redis.call('DEL', unpack(entries))\n  deleted = #entries\nend\n\n-- Drop the tag set itself; on next SET it'll be recreated by set-with-tags.\nredis.call('DEL', tagKey)\n\n-- Stamp the invalidation timestamp. Readers compare this against an entry's\n-- timestamp inside `getExpiration` to decide whether soft-tag-only entries\n-- should be considered stale.\nredis.call('SET', markerKey, marker, 'EX', markerTtl)\n\nreturn deleted\n";
 
 // src/shared/lua/refresh-tag-lock.lua
 var refresh_tag_lock_default = `-- refresh-tag-lock.lua
@@ -869,6 +869,23 @@ var DEFAULT_LOCK_TTL_SEC = 10;
 var ONE_YEAR_SEC = 60 * 60 * 24 * 365;
 var FALLBACK_TTL_SEC = 3600;
 var TAG_EXP_MARKER_TTL_SEC = 60 * 60 * 24 * 7;
+function encodeTagMarker(state) {
+  return `${state.s}|${state.e === Infinity ? "inf" : state.e}`;
+}
+function decodeTagMarker(raw) {
+  const s = Number.parseInt(raw, 10);
+  if (!Number.isFinite(s)) return null;
+  const sep = raw.indexOf("|");
+  if (sep === -1) return { s, e: s };
+  const tail = raw.slice(sep + 1);
+  if (tail === "inf") return { s, e: Infinity };
+  const e = Number.parseInt(tail, 10);
+  return { s, e: Number.isFinite(e) ? e : s };
+}
+function mergeTagState(map, tag, next) {
+  const prev = map.get(tag);
+  if (!prev || next.s > prev.s) map.set(tag, next);
+}
 function gateRedis(state) {
   const fb = state.opts.fallback;
   const ibp = state.opts.rest.isBuildPhase;
@@ -1053,21 +1070,17 @@ async function getImpl(state, cacheKey, softTags) {
   const freshnessTags = softTags.length > 0 ? [...softTags, ...envelope.tags] : envelope.tags;
   let tagStale = false;
   if (freshnessTags.length > 0) {
-    let mostRecent = 0;
+    const now = Date.now();
     for (const t of freshnessTags) {
-      const ts = Math.max(
-        state.localTagTimestamps.get(t) ?? 0,
-        state.memTagExp.get(t) ?? 0
-      );
-      if (ts > mostRecent) mostRecent = ts;
-    }
-    if (mostRecent > envelope.timestamp) {
-      if (state.opts.staleWhileRevalidate && partition.freshness !== "expired") {
-        tagStale = true;
-      } else {
+      const local = state.localTagTimestamps.get(t);
+      const mem = state.memTagExp.get(t);
+      const st = local && mem ? local.s >= mem.s ? local : mem : local ?? mem;
+      if (!st || st.s <= envelope.timestamp) continue;
+      if (now >= st.e || partition.freshness === "expired") {
         state.emit({ type: "cache.miss", meta: { reason: "tag-invalidated" } });
         return void 0;
       }
+      tagStale = true;
     }
   }
   const freshness = tagStale ? "stale" : partition.freshness;
@@ -1094,15 +1107,13 @@ async function getImpl(state, cacheKey, softTags) {
       meta: { freshness }
     });
   }
-  const revalidateMs = Math.max(0, envelope.revalidate) * 1e3;
-  const outTimestamp = tagStale ? Math.min(envelope.timestamp, Date.now() - revalidateMs - 1) : envelope.timestamp;
   return {
     value: bufferToStream(Buffer.from(envelope.value, "base64")),
     tags: envelope.tags,
     stale: envelope.stale,
-    timestamp: outTimestamp,
+    timestamp: envelope.timestamp,
     expire: envelope.expire,
-    revalidate: envelope.revalidate
+    revalidate: tagStale ? -1 : envelope.revalidate
   };
 }
 async function setImpl(state, cacheKey, pendingEntry) {
@@ -1116,6 +1127,10 @@ async function setImpl(state, cacheKey, pendingEntry) {
     state.emit({ type: "cache.set.failed", meta: { reason: "pending-rejected" } });
     return;
   }
+  if (entry.expire === 0 && !process.env.__NEXT_DEV_SERVER) {
+    state.emit({ type: "cache.set.skipped", meta: { reason: "dynamic-entry" } });
+    return;
+  }
   let buf;
   try {
     buf = await readStreamFully(entry.value);
@@ -1221,11 +1236,13 @@ async function ensureTagSubscription(state) {
         try {
           const parsed = JSON.parse(message);
           if (!Array.isArray(parsed.t) || typeof parsed.ts !== "number") return;
+          const incoming = {
+            s: parsed.ts,
+            e: typeof parsed.e === "number" ? parsed.e : Infinity
+          };
           for (const tag of parsed.t) {
-            const prev = state.localTagTimestamps.get(tag) ?? 0;
-            if (parsed.ts > prev) state.localTagTimestamps.set(tag, parsed.ts);
-            const prevMem = state.memTagExp.get(tag) ?? 0;
-            if (parsed.ts > prevMem) state.memTagExp.set(tag, parsed.ts);
+            mergeTagState(state.localTagTimestamps, tag, incoming);
+            mergeTagState(state.memTagExp, tag, incoming);
           }
           pruneOldestByTimestamp(state.localTagTimestamps, MAX_LOCAL_TAG_ENTRIES);
           pruneOldestByTimestamp(state.memTagExp, MAX_LOCAL_TAG_ENTRIES);
@@ -1277,17 +1294,17 @@ async function refreshTagsImpl(state) {
           for (let i = 0; i < keys.length; i += 1) {
             const v = values[i];
             if (!v) continue;
-            const ts = Number.parseInt(v, 10);
-            if (!Number.isFinite(ts)) continue;
+            const st = decodeTagMarker(v);
+            if (!st) continue;
             const key = keys[i];
             if (key === void 0) continue;
             const tag = stripExpPrefix(state, key);
-            if (tag) fresh.set(tag, ts);
+            if (tag) fresh.set(tag, st);
           }
         }
-        for (const [tag, ts] of state.localTagTimestamps) {
-          if (ts >= scanStartMs && (fresh.get(tag) ?? 0) < ts) {
-            fresh.set(tag, ts);
+        for (const [tag, st] of state.localTagTimestamps) {
+          if (st.s >= scanStartMs && (fresh.get(tag)?.s ?? 0) < st.s) {
+            fresh.set(tag, st);
           }
         }
         state.localTagTimestamps = fresh;
@@ -1305,7 +1322,7 @@ function escapeMatch(s) {
 var MAX_LOCAL_TAG_ENTRIES = 1e4;
 function pruneOldestByTimestamp(map, maxEntries) {
   if (map.size <= maxEntries) return;
-  const byAge = [...map.entries()].sort((a, b) => a[1] - b[1]);
+  const byAge = [...map.entries()].sort((a, b) => a[1].s - b[1].s);
   const drop = map.size - maxEntries;
   for (let i = 0; i < drop; i += 1) {
     const entry = byAge[i];
@@ -1322,9 +1339,9 @@ async function getExpirationImpl(state, tags) {
   let max = 0;
   for (const t of tags) {
     const local = state.localTagTimestamps.get(t);
-    if (local !== void 0 && local > max) max = local;
+    if (local && Number.isFinite(local.e) && local.e > max) max = local.e;
     const mem = state.memTagExp.get(t);
-    if (mem !== void 0 && mem > max) max = mem;
+    if (mem && Number.isFinite(mem.e) && mem.e > max) max = mem.e;
   }
   if (max > 0) {
     state.emit({ type: "tag.expiration.read", meta: { source: "local", count: tags.length } });
@@ -1345,8 +1362,8 @@ async function getExpirationImpl(state, tags) {
         let m = 0;
         for (const v of values) {
           if (!v) continue;
-          const n = Number.parseInt(v, 10);
-          if (Number.isFinite(n) && n > m) m = n;
+          const st = decodeTagMarker(v);
+          if (st && Number.isFinite(st.e) && st.e > m) m = st.e;
         }
         return m;
       }
@@ -1357,11 +1374,14 @@ async function getExpirationImpl(state, tags) {
 }
 async function updateTagsImpl(state, tags, durations) {
   if (tags.length === 0) return;
-  const isHardExpire = durations?.expire === 0;
+  const isHardExpire = durations === void 0 || durations.expire === 0;
   const now = Date.now();
+  const deadline = isHardExpire ? now : durations.expire !== void 0 && Number.isFinite(durations.expire) ? now + durations.expire * 1e3 : Infinity;
+  const tagState = { s: now, e: deadline };
+  const marker = encodeTagMarker(tagState);
   for (const t of tags) {
-    state.localTagTimestamps.set(t, now);
-    state.memTagExp.set(t, now);
+    mergeTagState(state.localTagTimestamps, t, tagState);
+    mergeTagState(state.memTagExp, t, tagState);
   }
   pruneOldestByTimestamp(state.memTagExp, MAX_LOCAL_TAG_ENTRIES);
   if (!gateRedis(state)) {
@@ -1399,8 +1419,8 @@ async function updateTagsImpl(state, tags, durations) {
               client,
               "revalidateHard",
               [tagKey(state, t), tagExpKey(state, t)],
-              [String(now), String(TAG_EXP_MARKER_TTL_SEC)]
-            ) : client.set(tagExpKey(state, t), String(now), {
+              [marker, String(TAG_EXP_MARKER_TTL_SEC)]
+            ) : client.set(tagExpKey(state, t), marker, {
               EX: TAG_EXP_MARKER_TTL_SEC
             })
           )
@@ -1416,7 +1436,9 @@ async function updateTagsImpl(state, tags, durations) {
         const client = await state.conn.getOrConnect();
         await client?.publish?.(
           invalChannel(state),
-          JSON.stringify({ t: tags, ts: now })
+          JSON.stringify(
+            deadline === Infinity ? { t: tags, ts: now } : { t: tags, ts: now, e: deadline }
+          )
         );
       } catch {
       }