feat(redis-strings): optional valueSerializer for custom wire format (#211)

Made-with: Cursor

Author: VladBo

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

@@ -1,7 +1,10 @@
 import { REVALIDATED_TAGS_KEY } from "../constants";
 import { isImplicitTag } from "../helpers/isImplicitTag";
 import { CacheHandlerValue, Handler } from "./cache-handler.types";
-import { CreateRedisStringsHandlerOptions } from "./redis-strings.types";
+import {
+  type CacheValueSerializer,
+  type CreateRedisStringsHandlerOptions,
+} from "./redis-strings.types";
 import {
   convertStringsToBuffers,
   parseBuffersToStrings,
@@ -10,6 +13,19 @@ import type { RedisClientType } from "@redis/client";
 import { RedisClusterCacheAdapter } from "../helpers/redisClusterAdapter";
 import { withAbortSignalProxy } from "../helpers/withAbortSignalProxy";
 
+export type { CacheValueSerializer } from "./redis-strings.types";
+
+export const jsonCacheValueSerializer: CacheValueSerializer = {
+  serialize(value) {
+    return JSON.stringify(value);
+  },
+  deserialize(stored) {
+    return JSON.parse(
+      typeof stored === "string" ? stored : String(stored),
+    ) as CacheHandlerValue | null;
+  },
+};
+
 /**
  * Creates a Handler for handling cache operations using Redis strings.
  *
@@ -33,6 +49,7 @@ export default function createHandler({
   timeoutMs = 5_000,
   keyExpirationStrategy = "EXPIREAT",
   revalidateTagQuerySize = 10_000,
+  valueSerializer = jsonCacheValueSerializer,
 }: CreateRedisStringsHandlerOptions<
   RedisClientType | RedisClusterCacheAdapter
 >): Handler {
@@ -176,7 +193,7 @@ export default function createHandler({
         return null;
       }
 
-      const cacheValue = JSON.parse(result) as CacheHandlerValue | null;
+      const cacheValue = valueSerializer.deserialize(result);
 
       if (!cacheValue) {
         return null;
@@ -237,7 +254,7 @@ export default function createHandler({
         parseBuffersToStrings({ ...cacheHandlerValue, value: valueForStorage });
       }
 
-      const serializedValue = JSON.stringify({
+      const serializedValue = valueSerializer.serialize({
         ...cacheHandlerValue,
         value: valueForStorage,
       });

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

@@ -1,5 +1,15 @@
 import type { RedisClientType } from "@redis/client";
 import { RedisClusterCacheAdapter } from "../helpers/redisClusterAdapter";
+import type { CacheHandlerValue } from "./cache-handler.types";
+
+/**
+ * Pluggable wire-format codec for Redis string values (JSON, compression, encryption, etc.).
+ * Default behavior is JSON.stringify / JSON.parse (see `jsonCacheValueSerializer` export).
+ */
+export type CacheValueSerializer = {
+  serialize(value: CacheHandlerValue): string;
+  deserialize(stored: string): CacheHandlerValue | null;
+};
 
 export type RedisCompliantCachedRouteValue = {
   // See: https://github.com/vercel/next.js/blob/f5444a16ec2ef7b82d30048890b613aa3865c1f1/packages/next/src/server/response-cache/types.ts#L97
@@ -72,4 +82,11 @@ export type CreateRedisStringsHandlerOptions<
    * @default 'EXPIREAT'
    */
   keyExpirationStrategy?: "EXAT" | "EXPIREAT";
+  /**
+   * Optional codec for values stored in Redis (`SET`/`GET`).
+   * Implement compression, encryption, or custom formats in your app; this package stays dependency-free.
+   *
+   * @default JSON.stringify / JSON.parse (same as previous releases)
+   */
+  valueSerializer?: CacheValueSerializer;
 };