@leejpsd/nextjs-cache-handler 0.1.0 → 0.2.0

package/dist/ops/index.d.cts

@@ -1,4 +1,4 @@
-import { d as MetricEventType } from '../types-CgriT7My.cjs';
+import { d as MetricEventType } from '../types-Dq1q6qXd.cjs';
 
 /**
  * Process-local metric counters with an optional emit hook.

package/dist/ops/index.d.ts

@@ -1,4 +1,4 @@
-import { d as MetricEventType } from '../types-CgriT7My.js';
+import { d as MetricEventType } from '../types-Dq1q6qXd.js';
 
 /**
  * Process-local metric counters with an optional emit hook.

package/dist/shared/client/adapter-ioredis.d.cts

@@ -1,5 +1,5 @@
 import { Cluster, Redis } from 'ioredis';
-import { R as RedisClientLike, a as RedisClientConfig } from '../../types-CgriT7My.cjs';
+import { R as RedisClientLike, a as RedisClientConfig } from '../../types-Dq1q6qXd.cjs';
 
 /**
  * Adapter for `ioredis` (and `ioredis.Cluster`).

package/dist/shared/client/adapter-ioredis.d.ts

@@ -1,5 +1,5 @@
 import { Cluster, Redis } from 'ioredis';
-import { R as RedisClientLike, a as RedisClientConfig } from '../../types-CgriT7My.js';
+import { R as RedisClientLike, a as RedisClientConfig } from '../../types-Dq1q6qXd.js';
 
 /**
  * Adapter for `ioredis` (and `ioredis.Cluster`).

package/dist/shared/client/adapter-redis.d.cts

@@ -1,5 +1,5 @@
 import { RedisClientType } from 'redis';
-import { R as RedisClientLike, a as RedisClientConfig } from '../../types-CgriT7My.cjs';
+import { R as RedisClientLike, a as RedisClientConfig } from '../../types-Dq1q6qXd.cjs';
 
 /**
  * Adapter for `redis@5` (the official `node-redis` client).

package/dist/shared/client/adapter-redis.d.ts

@@ -1,5 +1,5 @@
 import { RedisClientType } from 'redis';
-import { R as RedisClientLike, a as RedisClientConfig } from '../../types-CgriT7My.js';
+import { R as RedisClientLike, a as RedisClientConfig } from '../../types-Dq1q6qXd.js';
 
 /**
  * Adapter for `redis@5` (the official `node-redis` client).

package/dist/{types-CgriT7My.d.cts → types-Dq1q6qXd.d.cts}

@@ -71,7 +71,7 @@ type FallbackStrategy = "auto" | "always" | "never";
  * Optional — when not provided, only the process-local counters in
  * `src/shared/metrics.ts` are updated.
  */
-type MetricEventType = "cache.hit" | "cache.miss" | "cache.stale" | "cache.set" | "cache.set.failed" | "tag.invalidate.soft" | "tag.invalidate.hard" | "tag.expiration.read" | "redis.connect.failed" | "redis.timeout" | "fallback.activated" | "build_phase.skip";
+type MetricEventType = "cache.hit" | "cache.miss" | "cache.stale" | "cache.stale.refresh.leader" | "cache.stale.refresh.follower" | "cache.stale.refresh.skipped" | "cache.set" | "cache.set.failed" | "tag.invalidate.soft" | "tag.invalidate.hard" | "tag.expiration.read" | "redis.connect.failed" | "redis.timeout" | "fallback.activated" | "build_phase.skip";
 interface MetricEvent {
     type: MetricEventType;
     /** Operation latency in milliseconds, when measurable. */
@@ -141,6 +141,28 @@ interface CacheHandlerOptions {
      * Default: `true`. Set to `false` to revert to "expire on revalidate" behavior.
      */
     staleWhileRevalidate?: boolean;
+    /**
+     * Single-flight refresh lock for the SWR boundary.
+     *
+     * When enabled, only one handler instance per cache key attempts a
+     * background refresh during the stale window. Other instances continue
+     * serving the same stale entry until the leader publishes a fresh one or
+     * the lock TTL expires. Prevents N parallel refreshes (cache stampede)
+     * when many instances cross the `revalidate` boundary at the same time.
+     *
+     * Default: `false`. The marginal benefit at small scale is small because
+     * Next.js already serializes per-cacheKey refresh per process; turn this
+     * on when you have many instances and observe duplicate origin work
+     * around the revalidate boundary.
+     */
+    singleFlight?: boolean;
+    /**
+     * Lock TTL in seconds for `singleFlight` mode. Default: 10.
+     *
+     * Long enough that a normal refresh can complete (most are sub-second),
+     * short enough that a crashed leader doesn't block followers for long.
+     */
+    singleFlightLockTtlSec?: number;
     /**
      * Override the build-phase detector. Default checks
      * `process.env.NEXT_PHASE === "phase-production-build"`.

package/dist/{types-CgriT7My.d.ts → types-Dq1q6qXd.d.ts}

@@ -71,7 +71,7 @@ type FallbackStrategy = "auto" | "always" | "never";
  * Optional — when not provided, only the process-local counters in
  * `src/shared/metrics.ts` are updated.
  */
-type MetricEventType = "cache.hit" | "cache.miss" | "cache.stale" | "cache.set" | "cache.set.failed" | "tag.invalidate.soft" | "tag.invalidate.hard" | "tag.expiration.read" | "redis.connect.failed" | "redis.timeout" | "fallback.activated" | "build_phase.skip";
+type MetricEventType = "cache.hit" | "cache.miss" | "cache.stale" | "cache.stale.refresh.leader" | "cache.stale.refresh.follower" | "cache.stale.refresh.skipped" | "cache.set" | "cache.set.failed" | "tag.invalidate.soft" | "tag.invalidate.hard" | "tag.expiration.read" | "redis.connect.failed" | "redis.timeout" | "fallback.activated" | "build_phase.skip";
 interface MetricEvent {
     type: MetricEventType;
     /** Operation latency in milliseconds, when measurable. */
@@ -141,6 +141,28 @@ interface CacheHandlerOptions {
      * Default: `true`. Set to `false` to revert to "expire on revalidate" behavior.
      */
     staleWhileRevalidate?: boolean;
+    /**
+     * Single-flight refresh lock for the SWR boundary.
+     *
+     * When enabled, only one handler instance per cache key attempts a
+     * background refresh during the stale window. Other instances continue
+     * serving the same stale entry until the leader publishes a fresh one or
+     * the lock TTL expires. Prevents N parallel refreshes (cache stampede)
+     * when many instances cross the `revalidate` boundary at the same time.
+     *
+     * Default: `false`. The marginal benefit at small scale is small because
+     * Next.js already serializes per-cacheKey refresh per process; turn this
+     * on when you have many instances and observe duplicate origin work
+     * around the revalidate boundary.
+     */
+    singleFlight?: boolean;
+    /**
+     * Lock TTL in seconds for `singleFlight` mode. Default: 10.
+     *
+     * Long enough that a normal refresh can complete (most are sub-second),
+     * short enough that a crashed leader doesn't block followers for long.
+     */
+    singleFlightLockTtlSec?: number;
     /**
      * Override the build-phase detector. Default checks
      * `process.env.NEXT_PHASE === "phase-production-build"`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leejpsd/nextjs-cache-handler",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
@@ -127,7 +127,9 @@
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run",
     "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:integration:up": "docker compose -f docker-compose.test.yml up -d --wait",
+    "test:integration:down": "docker compose -f docker-compose.test.yml down",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "format": "prettier --write \"src/**/*.{ts,tsx}\" \"tests/**/*.{ts,tsx}\"",