Adds handler preparation step

Ensures handlers execute preparation tasks after configuration.

This step allows handlers to perform necessary setup,
such as cleaning up expired entries or stale resources,
before being used.

Author: AyronK

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

@@ -649,6 +649,30 @@ export class CacheHandler implements NextCacheHandler {
         "Successfully created CacheHandler configuration.",
       );
     }
+
+    const prepareResults = await Promise.allSettled(
+      handlersList.map((handler) => handler.prepare?.()),
+    );
+
+    if (CacheHandler.#debug) {
+      prepareResults.forEach((result, index) => {
+        if (result.status === "rejected") {
+          console.warn(
+            "[CacheHandler] [handler: %s] [method: %s] %s",
+            handlersList[index]?.name ?? `unknown-${index}`,
+            "prepare",
+            `Error: ${result.reason}`,
+          );
+        } else if (result.status === "fulfilled" && result.value !== undefined) {
+          console.info(
+            "[CacheHandler] [handler: %s] [method: %s] %s",
+            handlersList[index]?.name ?? `unknown-${index}`,
+            "prepare",
+            "Successfully completed preparation tasks.",
+          );
+        }
+      });
+    }
   }
 
   /**

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

@@ -173,6 +173,15 @@ export type Handler = {
    * @returns A Promise that resolves when the cache entry has been successfully deleted.
    */
   delete?: (key: string) => Promise<void>;
+
+  /**
+   * Prepares the handler for use, such as cleaning up expired entries or stale resources.
+   * This method is optional and will be automatically called by the `CacheHandler` class after handlers are configured.
+   * Handlers can use this to perform one-time setup tasks, remove stale entries, or prepare internal state.
+   *
+   * @returns A Promise that resolves when the preparation tasks have been completed.
+   */
+  prepare?: () => Promise<void>;
 };
 /**
  * Represents the parameters for Time-to-Live (TTL) configuration.

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

@@ -328,5 +328,8 @@ export default function createHandler({
           .hDel(keyPrefix + sharedTagsTtlKey, key),
       ]);
     },
+    async prepare() {
+      await revalidateSharedKeys();
+    },
   };
 }