@leejpsd/nextjs-cache-handler 0.1.0-rc.1 → 0.1.1

package/CHANGELOG.md

@@ -6,6 +6,61 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.1.1] - 2026-05-10
+
+Documentation-only patch released alongside the first round of external
+write-ups. No code changes.
+
+### Changed
+
+- **Compatibility matrix** now carries an explicit verification date and a
+  `nextjs-turbo-redis-cache` column, so readers can spot-check the comparison
+  against the upstream READMEs as both packages evolve. The previous
+  two-column shape didn't make it obvious which competitors are tracked.
+- **Production checklist** gains an explicit Redis Cluster row: cluster
+  deployments must set `hashTag: true` to avoid `CROSSSLOT` errors from
+  the multi-key Lua scripts. Also notes that cluster support is
+  unit-tested but not yet load-tested at scale.
+- **Compatibility table for Redis-protocol services** (ElastiCache,
+  Upstash, DragonflyDB, KeyDB, Vercel KV) added to the production
+  section, separating "validated" from "expected to work via the
+  standard Redis protocol".
+- **`docs/architecture.md`** now documents two memory-fallback caveats
+  that previously required reading the source: per-process isolation
+  (cross-instance correctness degrades during Redis outages) and the
+  32-bit `setTimeout` clamp (TTLs above ≈24.85 days fire the eviction
+  timer early, though `get()`'s lazy `expiresAt` check still honors the
+  configured expiration).
+
+## [0.1.0] - 2026-05-10
+
+First stable release. Promoted from `0.1.0-rc.1` after a 24-hour live-traffic
+soak on AWS ECS Fargate (multi-instance, ElastiCache Redis): 0 errors, 0
+entry leaks, Redis ping stable at 2ms, namespace isolation confirmed in
+runtime cache key shapes.
+
+### Verified during dogfood
+
+- Library wrapper modules require'd successfully on every staging task
+  (CloudWatch `[lib-incremental]` / `[lib-cache-components]` startup
+  signals)
+- Cache entries written with `BUILD_NAMESPACE` prefix
+  (`next-cache:entry:<sha>:...`) — confirms deployment isolation
+- `revalidateAccepted: 1` round-trip latency 193ms across the ALB; Server
+  Action `revalidateTag` propagates without errors
+- Static chunks resolve 200 across both `/dashboard` and `/experiments`
+  routes — the static-chunk-404 incident remediation is live
+
+### Pre-1.0 caveats
+
+- Released under 0.1.x — APIs may receive small adjustments before 1.0
+- Single-flight refresh lock is bundled (`refresh-tag-lock.lua`) but the
+  handler-side wiring lands in v0.2
+- Provenance attestation is disabled for the local-publish flow; v0.2
+  will switch to GitHub Actions OIDC publish
+
+
+
 ### Added — `cacheHandlers` (plural) for `'use cache'`
 
 - `createCacheComponentsHandler(opts)` factory implementing the full

package/README.md

@@ -1,7 +1,12 @@
 # @leejpsd/nextjs-cache-handler
 
-> **Pre-alpha (v0.0.0).** Working toward v0.1.0 publish. Production dogfood
-> on AWS ECS Fargate is in progress. APIs may change before v0.1.0.
+[![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)
+
+> **Stable `v0.1.0`** — install with
+> `npm install @leejpsd/nextjs-cache-handler`. Production-validated against
+> AWS ECS Fargate with multi-instance Redis (24h live-traffic soak: 0
+> errors, 0 leaks, 2ms Redis ping, namespace isolation working).
 
 The Redis cache handler for **Next.js 16** that ships **both** `cacheHandler`
 (ISR / Pages Router) **and** `cacheHandlers` (`'use cache'` directive,
@@ -44,21 +49,29 @@ As of 2026-05, the leading OSS Redis handler `@fortedigital/nextjs-cache-handler
 declares `peerDependencies.next: ">=16.1.5"` but the README marks the new
 plural interface as ❌ **"Not yet supported - Help needed"**:
 
-| Next 16 feature | @fortedigital | this |
-|---|---|---|
-| `cacheHandlers` config (plural) | ❌ Help needed | ✅ |
-| `'use cache'` directive | ❌ Help needed | ✅ |
-| `'use cache: remote'` | ❌ Help needed | ✅ |
-| `'use cache: private'` | n/a (uncustomizable) | n/a |
-| `cacheComponents: true` | ❌ Help needed | ✅ |
-| Build-phase skip (`PHASE_PRODUCTION_BUILD`) | ✅ | ✅ |
-| Auto deploy isolation (`BUILD_NAMESPACE`) | manual | ✅ auto |
-| Lua-atomic SET+tag | partial (MULTI) | ✅ |
-| AbortSignal timeout | ✅ | ✅ |
-| Redis Cluster | ✅ | ✅ |
-| ioredis support | ✅ | ✅ |
-| In-memory fallback (TTL-aware) | partial | ✅ |
-| OpenTelemetry hook | ❌ | ✅ (`onMetric`) |
+> 📅 **Compatibility matrix verified 2026-05-10.** The OSS Next.js cache
+> handler ecosystem moves quickly — please verify
+> [`@fortedigital`](https://github.com/fortedigital/nextjs-cache-handler#compatibility)
+> and
+> [`nextjs-turbo-redis-cache`](https://github.com/trieb-work/nextjs-turbo-redis-cache#features)
+> directly before relying on this comparison.
+
+| Next 16 feature | this | @fortedigital 3.2.0 | nextjs-turbo-redis-cache 1.13 |
+|---|---|---|---|
+| `cacheHandlers` config (plural) | ✅ | ❌ Help needed | ✅ since 1.11 |
+| `'use cache'` directive | ✅ | ❌ Help needed | ✅ since 1.11 |
+| `'use cache: remote'` | ✅ | ❌ Help needed | partial |
+| `'use cache: private'` | n/a (uncustomizable) | n/a | n/a |
+| `cacheComponents: true` | ✅ | ❌ Help needed | ✅ |
+| Build-phase skip (`PHASE_PRODUCTION_BUILD`) | ✅ | ✅ (singular only) | ✅ |
+| Auto deploy isolation | ✅ `BUILD_NAMESPACE` env-resolved | manual | ✅ `BUILD_ID` since 1.13 |
+| Lua-atomic SET+tag | ✅ Lua scripts | partial (MULTI) | partial |
+| AbortSignal timeout | ✅ per-op | ✅ Proxy-wrapped | ❌ |
+| Redis Cluster | ✅ (cluster adapter, see Production checklist) | ✅ | ✅ |
+| ioredis support | ✅ | ✅ | ✅ |
+| In-memory fallback (TTL-aware) | ✅ | partial | ✅ L1 + Redis L2 |
+| OpenTelemetry hook | ✅ `onMetric` | ❌ | ❌ |
+| Live-traffic dogfood (24h+) | ✅ AWS ECS Fargate | not published | not published |
 
 PR [#207](https://github.com/fortedigital/nextjs-cache-handler/pull/207) on
 `@fortedigital` has been stalled for 3+ months on the same issue: the
@@ -191,6 +204,13 @@ Full reference: [`docs/api.md`](./docs/api.md) (auto-generated).
       to avoid static-chunk-404 issues during a deploy.
 - [ ] **`abortTimeoutMs: 1500`** (default) — protects against a stuck Redis
       connection from hanging the request thread.
+- [ ] **Redis Cluster: set `hashTag: true`** — multi-key Lua scripts
+      (`set-with-tags.lua`, `revalidate-hard.lua`) require all KEYS to land
+      on the same hash slot. Without `hashTag`, cluster deployments will hit
+      `CROSSSLOT Keys in request don't hash to the same slot`. The flag wraps
+      the namespace in `{}` so every key for a given deploy hashes together.
+      Cluster support is implemented but **not yet load-tested at production
+      scale**; PRs welcome.
 - [ ] **Redis `maxmemory-policy: allkeys-lru` or `noeviction`** — if you need
       bounded memory, choose `allkeys-lru`. Otherwise `noeviction` keeps
       tag indices intact.
@@ -200,6 +220,17 @@ Full reference: [`docs/api.md`](./docs/api.md) (auto-generated).
       (separate from the handler) so a Redis outage surfaces in your
       monitoring without inducing 5xx in user requests.
 
+### Compatibility with Redis-protocol services
+
+| Service | How to use | Tested? |
+|---|---|---|
+| **Self-hosted Redis 7+** | `{ type: "redis", url }` or `{ type: "ioredis", url }` | ✅ AWS ElastiCache 24h soak |
+| **Redis Cluster** | `{ type: "cluster", nodes }` + `hashTag: true` | unit-tested, not yet load-tested at scale |
+| **Upstash Redis** | `{ type: "redis", url: "rediss://..." }` (TLS auto-detected) | not yet validated, expected to work via the standard Redis protocol |
+| **AWS ElastiCache (replication group)** | `{ type: "redis", url: "rediss://..." }` | ✅ reference deployment |
+| **Vercel KV** | not yet supported — `@vercel/kv` adapter ships in v0.3 | — |
+| **DragonflyDB / KeyDB** | Redis-protocol compatible — `{ type: "redis", url }` should work | not validated |
+
 ---
 
 ## How it differs from `@fortedigital/nextjs-cache-handler`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejpsd/nextjs-cache-handler",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.1",
   "description": "The only Redis cache handler for Next.js 16 that ships both cacheHandler (ISR) and cacheHandlers ('use cache') — production-validated for multi-instance deployments where @fortedigital lists 'Help needed'.",
   "keywords": [
     "next",