@leejpsd/nextjs-cache-handler 0.4.2 → 1.0.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.0.1
+
+### Patch Changes
+
+- [`199d7d8`](https://github.com/leejpsd/nextjs-cache-handler/commit/199d7d853c5a57973d344066b495bd8b00417560) Thanks [@leejpsd](https://github.com/leejpsd)! - Docs: describe the 24h staging run and the Redis-reboot drill as separate checks in the README.
+
+## 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

package/README.md

@@ -3,20 +3,22 @@
 [![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.4.2`** — install with
+> **`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).
+> `npx nextjs-cache-handler init --yes`. Validated on a staging demo
+> deployment (AWS ECS Fargate, two instances, ElastiCache Redis): a 24h
+> observation run on `0.1.0-rc.1` with 0 errors, and a Redis-reboot drill
+> under ~14 req/s with zero 5xx across 2,550 requests
+> ([`docs/staging-verification-2026-08-01.md`](./docs/staging-verification-2026-08-01.md)).
+> Exercised end-to-end against **Next.js 16.3** (both cache interfaces).
 >
 > 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)).
-> 0.4.2 aligns tag invalidation exactly with upstream semantics
-> (`updateTag()` hard vs `revalidateTag(tag, "max")` soft — see CHANGELOG).
+> 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
 
@@ -109,7 +111,7 @@ plural interface as ❌ **"Not yet supported - Help needed"**:
 | Redis Sentinel | ✅ (local failover drill) | ❌ | ❌ |
 | OpenTelemetry | ✅ built-in `/otel` emitter + `onMetric` hook | ❌ | ❌ |
 | Reconnect strategy | ✅ exponential backoff | client-level | error-threshold restart |
-| Live-traffic dogfood (24h+) | ✅ AWS ECS Fargate | not published | not published |
+| Staging dogfood (24h observation) | ✅ AWS ECS Fargate | not published | not published |
 
 PR [#207](https://github.com/fortedigital/nextjs-cache-handler/pull/207) on
 `@fortedigital` (their `cacheHandlers` attempt) was held up in review over
@@ -269,7 +271,7 @@ Full reference: [`docs/api.md`](./docs/api.md).
 
 | Service | How to use | Tested? |
 |---|---|---|
-| **Self-hosted Redis 7+** | `{ type: "redis", url }` or `{ type: "ioredis", url }` | ✅ AWS ElastiCache 24h soak |
+| **Self-hosted Redis 7+** | `{ type: "redis", url }` or `{ type: "ioredis", url }` | ✅ AWS ElastiCache (staging, 24h observation) |
 | **Redis Cluster** | `{ type: "cluster", nodes }` + `hashTag: true` | ✅ e2e-tested against a real 3-master cluster (CI); 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 (re-verified 2026-08-01, Seoul) |
@@ -431,8 +433,10 @@ ESM and CJS dual-published, full TypeScript types, validated via
     `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 ✅
-- **v0.5** — Vercel KV / Upstash adapter, `'use cache: remote'` multi-tier
-  setup, `neshClassicCache` equivalent
+- **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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejpsd/nextjs-cache-handler",
-  "version": "0.4.2",
+  "version": "1.0.1",
   "description": "Redis cache handler for Next.js 15/16 — the only one shipping both cacheHandler (ISR) and cacheHandlers ('use cache') with built-in compression, Redis Sentinel, and OpenTelemetry. Production-validated on multi-instance AWS: reconnect backoff, cross-instance tag invalidation, zero-downtime Redis failover.",
   "keywords": [
     "next",