feat: add non-destructive cache hydration support via isInitialHydrat… (#181)

* feat: add non-destructive cache hydration support via isInitialHydration context

- Add SetContext type with isInitialHydration flag
- Update Handler interface to accept optional SetContext in set()
- Implement NX behavior in redis-strings handler when isInitialHydration is true
- Update all handlers (local-lru, composite) to accept ctx parameter
- Propagate isInitialHydration flag from registerInitialCache to handlers
- Prevents runtime cache overwrites during app restarts and horizontal scaling

Addresses #23

* refactor: align initial cache write behavior with review feedback

Make non-destructive cache writes opt-in, improve naming, handler behavior, and documentation following review comments.

Author: zto-sbenning

README.md

@@ -99,6 +99,29 @@ export async function register() {
 }
 ```
 
+## Instrumentation
+
+### Initial cache registration
+
+By default, `registerInitialCache` populates the cache by overwriting any existing
+entries with values generated from build-time artifacts (fetch calls, pages, routes).
+
+#### Initial cache write strategy
+
+If you want to preserve values that may already exist in the cache (for example,
+entries written at runtime by another instance), you can enable the
+`setOnlyIfNotExists` option:
+
+```ts
+await registerInitialCache(CacheHandler, {
+  setOnlyIfNotExists: true,
+});
+```
+
+When enabled, cache writes performed during the initial cache registration will only
+occur if the corresponding cache key does not already exist. This allows you to
+explicitly choose the cache population strategy instead of enforcing a single default.
+
 ## Handlers
 
 ### `redis-strings`

packages/nextjs-cache-handler/src/handlers/cache-handler.ts

@@ -13,6 +13,7 @@ import {
   Handler,
   OnCreationHook,
   Revalidate,
+  SetContext,
 } from "./cache-handler.types";
 import { PrerenderManifest } from "next/dist/build";
 import {
@@ -579,10 +580,10 @@ export class CacheHandler implements NextCacheHandler {
 
         return null;
       },
-      async set(key, cacheHandlerValue) {
+      async set(key, cacheHandlerValue, ctx) {
         const operationsResults = await Promise.allSettled(
           handlersList.map((handler) =>
-            handler.set(key, { ...cacheHandlerValue }),
+            handler.set(key, { ...cacheHandlerValue }, ctx),
           ),
         );
 
@@ -721,7 +722,7 @@ export class CacheHandler implements NextCacheHandler {
       internal_lastModified?: number;
       tags?: string[];
       revalidate?: Revalidate;
-    },
+    } & SetContext,
   ): Promise<void> {
     await CacheHandler.#ensureConfigured();
 
@@ -773,7 +774,9 @@ export class CacheHandler implements NextCacheHandler {
       value: value,
     };
 
-    await CacheHandler.#mergedHandler.set(cacheKey, cacheHandlerValue);
+    await CacheHandler.#mergedHandler.set(cacheKey, cacheHandlerValue, {
+      setOnlyIfNotExists: ctx?.setOnlyIfNotExists,
+    });
 
     if (
       process.env.NEXT_PHASE === PHASE_PRODUCTION_BUILD &&

packages/nextjs-cache-handler/src/handlers/cache-handler.types.ts

@@ -46,6 +46,21 @@ export type CacheHandlerParametersGetWithTags = [
   string[],
 ];
 
+/**
+ * Context information provided during cache set operations.
+ */
+export type SetContext = {
+
+  /**
+   * When true, the cache write should only occur if the key does not already exist.
+   * Cache handlers should use non-destructive write operations (e.g., Redis NX)
+   * to avoid overwriting existing or fresher cache entries.
+   *
+   * @default false
+   */
+  setOnlyIfNotExists?: boolean;
+};
+
 /**
  * Represents an internal Next.js metadata for a `get` method.
  * This metadata is available in the `get` method of the cache handler.
@@ -125,6 +140,8 @@ export type Handler = {
    *
    * @param value - The value to be stored in the cache. See {@link CacheHandlerValue}.
    *
+   * @param ctx - Optional context information for the set operation. See {@link SetContext}.
+   *
    * @returns A Promise that resolves when the value has been successfully set in the cache.
    *
    * @remarks
@@ -137,7 +154,7 @@ export type Handler = {
    *
    * Use the absolute time (`expireAt`) to set and expiration time for the cache entry in your cache store to be in sync with the file system cache.
    */
-  set: (key: string, value: CacheHandlerValue) => Promise<void>;
+  set: (key: string, value: CacheHandlerValue, ctx?: SetContext) => Promise<void>;
   /**
    * Deletes all cache entries that are associated with the specified tag.
    * See [fetch `options.next.tags` and `revalidateTag` ↗](https://nextjs.org/docs/app/building-your-application/caching#fetch-optionsnexttags-and-revalidatetag)

packages/nextjs-cache-handler/src/handlers/composite.ts

@@ -37,10 +37,10 @@ export default function createHandler({
       return null;
     },
 
-    async set(key, data) {
+    async set(key, data, ctx) {
       const index = strategy?.(data) ?? 0;
       const handler = handlers[index] ?? handlers[0]!;
-      await handler.set(key, data);
+      await handler.set(key, data, ctx);
     },
 
     async revalidateTag(tag) {

packages/nextjs-cache-handler/src/handlers/local-lru.ts

@@ -99,7 +99,12 @@ export default function createHandler({
 
       return Promise.resolve(cacheValue);
     },
-    set(key, cacheHandlerValue) {
+    set(key, cacheHandlerValue, ctx) {
+      // LRU cache is in-memory and ephemeral, but we can still honor "setOnlyIfNotExists"
+      // by checking whether the key is already present before writing.
+      if (ctx?.setOnlyIfNotExists && lruCacheStore.has(key)) {
+        return Promise.resolve();
+      }
       lruCacheStore.set(key, cacheHandlerValue);
 
       return Promise.resolve();

packages/nextjs-cache-handler/src/handlers/redis-strings.ts

@@ -221,7 +221,7 @@ export default function createHandler({
 
       return cacheValue;
     },
-    async set(key, cacheHandlerValue) {
+    async set(key, cacheHandlerValue, ctx) {
       assertClientIsReady();
 
       let setOperation: Promise<string | null>;
@@ -260,23 +260,28 @@ export default function createHandler({
 
       switch (keyExpirationStrategy) {
         case "EXAT": {
+          const hasExpireAt = typeof lifespan?.expireAt === "number";
+          const isNX = ctx?.setOnlyIfNotExists === true;
+
+          const setOptions =
+            hasExpireAt || isNX
+              ? {
+                  ...(hasExpireAt && { EXAT: lifespan.expireAt }),
+                  ...(isNX && { NX: true }),
+                }
+              : undefined;
+
           setOperation = client
             .withAbortSignal(AbortSignal.timeout(timeoutMs))
-            .set(
-              keyPrefix + key,
-              serializedValue,
-              typeof lifespan?.expireAt === "number"
-                ? {
-                    EXAT: lifespan.expireAt,
-                  }
-                : undefined,
-            );
+            .set(keyPrefix + key, serializedValue, setOptions);
           break;
         }
         case "EXPIREAT": {
+          const setOptions = ctx?.setOnlyIfNotExists ? { NX: true } : undefined;
+
           setOperation = client
             .withAbortSignal(AbortSignal.timeout(timeoutMs))
-            .set(keyPrefix + key, serializedValue);
+            .set(keyPrefix + key, serializedValue, setOptions);
 
           expireOperation = lifespan
             ? client

packages/nextjs-cache-handler/src/instrumentation/register-initial-cache.ts

@@ -57,6 +57,16 @@ export type RegisterInitialCacheOptions = {
    * @default .next
    */
   buildDir?: string;
+  /**
+   * When true, cache writes performed during the initial cache population
+   * will only occur if the key does not already exist.
+   *
+   * This allows you to choose a strategy: either always overwrite entries,
+   * or preserve any values that may have been written at runtime.
+   *
+   * @default false
+   */
+  setOnlyIfNotExists?: boolean;
   /**
    * The maximum number of concurrent operations.
    * This speeds up the initial cache population because routes are read and processed in parallel.
@@ -121,6 +131,7 @@ export async function registerInitialCache(
   const populateFetch = options.fetch ?? true;
   const populatePages = options.pages ?? true;
   const populateRoutes = options.routes ?? true;
+  const setOnlyIfNotExists = options.setOnlyIfNotExists ?? false;
 
   let prerenderManifest: PrerenderManifest | undefined;
 
@@ -236,6 +247,7 @@ export async function registerInitialCache(
         revalidate,
         internal_lastModified: lastModified,
         tags: getTagsFromHeaders(meta.headers),
+        setOnlyIfNotExists: setOnlyIfNotExists,
       });
     } catch (error) {
       if (debug) {
@@ -376,6 +388,7 @@ export async function registerInitialCache(
       await cacheHandler.set(cachePath, value, {
         revalidate,
         internal_lastModified: lastModified,
+        setOnlyIfNotExists: setOnlyIfNotExists,
       });
 
       if (debug) {
@@ -490,6 +503,7 @@ export async function registerInitialCache(
         revalidate,
         internal_lastModified: lastModified,
         tags: fetchCache.tags,
+        setOnlyIfNotExists: setOnlyIfNotExists,
       });
     } catch (error) {
       if (debug) {