@leejpsd/nextjs-cache-handler 0.3.4 → 0.4.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 export { CacheComponentsHandler, createCacheComponentsHandler, partitionEntry, shouldServeStale } from './cache-components/index.cjs';
 export { IncrementalCtx, IncrementalRedisCacheHandler, createIncrementalCacheHandler } from './incremental/index.cjs';
 export { getMetricSnapshot } from './ops/index.cjs';
-export { C as CacheComponentsEntry, b as CacheHandlerOptions, F as FallbackStrategy, I as IncrementalCacheData, L as Logger, M as MetricEmitter, c as MetricEvent, d as MetricEventType, a as RedisClientConfig, e as RedisClientFactory, R as RedisClientLike } from './types-Bl-rkLKX.cjs';
+export { C as CacheComponentsEntry, c as CacheHandlerOptions, F as FallbackStrategy, I as IncrementalCacheData, L as Logger, M as MetricEmitter, d as MetricEvent, e as MetricEventType, a as RedisClientConfig, b as RedisClientFactory, R as RedisClientLike } from './types-C1vJ_sED.cjs';
 
 /**
  * Timeout-bounded operation wrapper. Surrounds every Redis call so a hung

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { CacheComponentsHandler, createCacheComponentsHandler, partitionEntry, shouldServeStale } from './cache-components/index.js';
 export { IncrementalCtx, IncrementalRedisCacheHandler, createIncrementalCacheHandler } from './incremental/index.js';
 export { getMetricSnapshot } from './ops/index.js';
-export { C as CacheComponentsEntry, b as CacheHandlerOptions, F as FallbackStrategy, I as IncrementalCacheData, L as Logger, M as MetricEmitter, c as MetricEvent, d as MetricEventType, a as RedisClientConfig, e as RedisClientFactory, R as RedisClientLike } from './types-Bl-rkLKX.js';
+export { C as CacheComponentsEntry, c as CacheHandlerOptions, F as FallbackStrategy, I as IncrementalCacheData, L as Logger, M as MetricEmitter, d as MetricEvent, e as MetricEventType, a as RedisClientConfig, b as RedisClientFactory, R as RedisClientLike } from './types-C1vJ_sED.js';
 
 /**
  * Timeout-bounded operation wrapper. Surrounds every Redis call so a hung

package/dist/index.js

@@ -43,7 +43,40 @@ __export(adapter_redis_exports, {
   createRedisV5Client: () => createRedisV5Client
 });
 function adaptRedisV5(client) {
-  return client;
+  const like = client;
+  like.dispose = () => {
+    try {
+      client.destroy();
+    } catch {
+    }
+  };
+  like.subscribe = async (channel, onMessage, onDown) => {
+    const sub = client.duplicate();
+    const teardown = () => {
+      try {
+        sub.destroy();
+      } catch {
+      }
+    };
+    let down = false;
+    const markDown = () => {
+      if (down) return;
+      down = true;
+      teardown();
+      onDown?.();
+    };
+    sub.on("error", markDown);
+    sub.on("end", markDown);
+    try {
+      await sub.connect();
+      await sub.subscribe(channel, (message) => onMessage(message));
+    } catch (err) {
+      teardown();
+      throw err;
+    }
+    return async () => teardown();
+  };
+  return like;
 }
 function createRedisV5Client(config) {
   const { createClient } = nodeRequire("redis");
@@ -86,7 +119,12 @@ function adapt(client, isClusterClient = false) {
       }
     },
     get: (k) => client.get(k),
-    set: (k, v, opts) => opts?.EX !== void 0 ? client.set(k, v, "EX", opts.EX) : client.set(k, v),
+    set: (k, v, opts) => {
+      const args = [];
+      if (opts?.EX !== void 0) args.push("EX", opts.EX);
+      if (opts?.NX) args.push("NX");
+      return client.set(k, v, ...args);
+    },
     del: async (keys) => {
       const arr = Array.isArray(keys) ? keys : [keys];
       if (arr.length === 0) return 0;
@@ -157,6 +195,40 @@ function adapt(client, isClusterClient = false) {
       client.on(event, listener);
       return client;
     },
+    publish: (channel, message) => client.publish(channel, message),
+    ...isClusterClient ? {} : {
+      subscribe: async (channel, onMessage, onDown) => {
+        const sub = client.duplicate();
+        let down = false;
+        const markDown = () => {
+          if (down) return;
+          down = true;
+          try {
+            sub.disconnect();
+          } catch {
+          }
+          onDown?.();
+        };
+        sub.on("error", markDown);
+        sub.on("end", markDown);
+        try {
+          if (sub.status !== "ready" && sub.status !== "connecting") {
+            await sub.connect();
+          }
+          await sub.subscribe(channel);
+        } catch (err) {
+          markDown();
+          throw err;
+        }
+        sub.on("message", (ch, message) => {
+          if (ch === channel) onMessage(message);
+        });
+        return async () => {
+          down = true;
+          sub.disconnect();
+        };
+      }
+    },
     dispose: () => {
       client.disconnect();
     }
@@ -821,6 +893,7 @@ function init(opts) {
       hashTag: opts.hashTag ?? false,
       keyPrefix: opts.keyPrefix ?? DEFAULT_KEY_PREFIX,
       singleFlight: opts.singleFlight ?? false,
+      tagPubSub: opts.tagPubSub ?? false,
       singleFlightLockTtlSec: opts.singleFlightLockTtlSec ?? DEFAULT_LOCK_TTL_SEC,
       rest: opts
     },
@@ -831,6 +904,7 @@ function init(opts) {
     memTags: new MemorySetStore(opts.memoryMaxEntries),
     memTagExp: /* @__PURE__ */ new Map(),
     localTagTimestamps: /* @__PURE__ */ new Map(),
+    pubsub: { active: false, disabled: false, attempting: false, lastAttempt: 0 },
     resolveNs: () => resolveBuildNamespace(opts.buildNamespace),
     instanceId: process.env.HOSTNAME || process.env.ECS_TASK_ID || `pid-${process.pid}`
   };
@@ -908,6 +982,7 @@ function resolveTtlSeconds(entry) {
 async function getImpl(state, cacheKey, softTags) {
   const start = Date.now();
   const useRedis = gateRedis(state);
+  if (useRedis) void ensureTagSubscription(state);
   if (!useRedis && state.opts.fallback === "never") {
     state.emit({ type: "cache.miss", meta: { reason: "no-redis" } });
     return void 0;
@@ -984,8 +1059,11 @@ async function getImpl(state, cacheKey, softTags) {
   if (freshnessTags.length > 0) {
     let mostRecent = 0;
     for (const t of freshnessTags) {
-      const ts = state.localTagTimestamps.get(t);
-      if (ts !== void 0 && ts > mostRecent) mostRecent = ts;
+      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") {
@@ -1118,10 +1196,68 @@ async function luaSetWithTags(client, state, eKey, payload, ttl, tags) {
     [payload, String(ttl), String(ttl), String(tags.length)]
   );
 }
+function invalChannel(state) {
+  const ns = state.opts.hashTag ? `{${state.resolveNs()}}` : state.resolveNs();
+  return `${state.opts.keyPrefix}inval:${ns}`;
+}
+var SUBSCRIBE_RETRY_MS = 5e3;
+async function ensureTagSubscription(state) {
+  if (!state.opts.tagPubSub || state.pubsub.active || state.pubsub.disabled || state.pubsub.attempting) {
+    return;
+  }
+  const now = Date.now();
+  if (now - state.pubsub.lastAttempt < SUBSCRIBE_RETRY_MS) return;
+  state.pubsub.lastAttempt = now;
+  state.pubsub.attempting = true;
+  try {
+    const client = await state.conn.getOrConnect();
+    if (!client) return;
+    if (typeof client.subscribe !== "function") {
+      state.pubsub.disabled = true;
+      state.logger.warn(
+        "tagPubSub unavailable on this client (no subscribe support, e.g. Cluster) \u2014 falling back to scan-based propagation"
+      );
+      return;
+    }
+    const stop = await client.subscribe(
+      invalChannel(state),
+      (message) => {
+        try {
+          const parsed = JSON.parse(message);
+          if (!Array.isArray(parsed.t) || typeof parsed.ts !== "number") return;
+          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);
+          }
+          pruneOldestByTimestamp(state.localTagTimestamps, MAX_LOCAL_TAG_ENTRIES);
+          pruneOldestByTimestamp(state.memTagExp, MAX_LOCAL_TAG_ENTRIES);
+        } catch {
+        }
+      },
+      () => {
+        state.pubsub.active = false;
+      }
+    );
+    state.pubsub.active = true;
+    state.pubsub.stop = async () => {
+      state.pubsub.active = false;
+      await stop();
+    };
+  } catch (err) {
+    state.logger.warn("tagPubSub subscribe failed \u2014 will retry", {
+      message: err.message
+    });
+  } finally {
+    state.pubsub.attempting = false;
+  }
+}
 async function refreshTagsImpl(state) {
   if (!gateRedis(state)) {
     return;
   }
+  void ensureTagSubscription(state);
   try {
     await withAbortSignal(
       "cacheHandlers.refreshTags",
@@ -1279,6 +1415,16 @@ async function updateTagsImpl(state, tags, durations) {
       type: isHardExpire ? "tag.invalidate.hard" : "tag.invalidate.soft",
       meta: { count: tags.length, backend: "redis" }
     });
+    if (state.opts.tagPubSub) {
+      try {
+        const client = await state.conn.getOrConnect();
+        await client?.publish?.(
+          invalChannel(state),
+          JSON.stringify({ t: tags, ts: now })
+        );
+      } catch {
+      }
+    }
   } catch (err) {
     if (err instanceof CacheTimeoutError) {
       state.emit({ type: "redis.timeout", meta: { op: "updateTags" } });
@@ -1470,7 +1616,9 @@ async function readTagStates(state, tags) {
       async () => {
         const client = await state.conn.getOrConnect();
         if (!client) return tags.map((t) => state.memTagStates.get(t) ?? null);
-        const values = await client.mGet(tags.map((t) => tagMetaKey(state, t)));
+        const values = await Promise.all(
+          tags.map((t) => client.get(tagMetaKey(state, t)))
+        );
         return values.map((v) => {
           if (!v) return null;
           try {