feat(cache): add allowQuery option to filter query params in cache key

docs/1.docs/7.cache.md

@@ -223,6 +223,10 @@ The `defineCachedHandler` and `defineCachedFunction` functions accept the follow
   ::field{name="varies" type="string[]"}
     An array of request headers to be considered for the cache, [learn more](https://github.com/nitrojs/nitro/issues/1031). If utilizing in a multi-tenant environment, you may want to pass `['host', 'x-forwarded-host']` to ensure these headers are not discarded and that the cache is unique per tenant.
   ::
+  ::field{name="allowQuery" type="string[]"}
+    List of query parameter names to include in the cache key. If `undefined`, all query parameters are included. If an empty array `[]`, all query parameters are ignored (only the pathname is used for caching). Only applicable to cached event handlers. :br
+    Defaults to `undefined`.
+  ::
 ::
 
 ## Cache keys and invalidation

src/runtime/internal/cache.ts

@@ -201,7 +201,20 @@ export function defineCachedHandler(
         return escapeKey(customKey);
       }
       // Auto-generated key
-      const _path = event.url.pathname + event.url.search;
+      let _path: string;
+      if (opts.allowQuery) {
+        const params = new URLSearchParams();
+        for (const key of opts.allowQuery) {
+          const value = event.url.searchParams.get(key);
+          if (value !== null) {
+            params.set(key, value);
+          }
+        }
+        const search = params.size > 0 ? `?${params.toString()}` : "";
+        _path = event.url.pathname + search;
+      } else {
+        _path = event.url.pathname + event.url.search;
+      }
       let _pathname: string;
       try {
         _pathname = escapeKey(decodeURI(parseURL(_path).pathname)).slice(0, 16) || "index";

src/types/runtime/cache.ts

@@ -38,4 +38,11 @@ export interface CachedEventHandlerOptions extends Omit<
 > {
   headersOnly?: boolean;
   varies?: string[] | readonly string[];
+  /**
+   * List of query string parameter names that will be considered for caching.
+   * - If undefined, all query parameters are included in the cache key.
+   * - If an empty array `[]`, all query parameters are ignored (only pathname is used for caching).
+   * - If a list of parameter names, only those parameters are included in the cache key.
+   */
+  allowQuery?: string[];
 }

test/fixture/nitro.config.ts

@@ -90,6 +90,7 @@ export default defineConfig({
     },
     "/rules/dynamic": { cache: false, isr: false },
     "/rules/redirect": { redirect: "/base" },
+    "/rules/allow-query/**": { cache: { swr: true, maxAge: 60, allowQuery: ["q"] } },
     "/rules/isr/**": { isr: { allowQuery: ["q"] } },
     "/rules/isr-ttl/**": { isr: 60 },
     "/rules/swr/**": { swr: true },

test/fixture/server/routes/api/cached-allow-query.ts

@@ -0,0 +1,10 @@
+import { defineCachedHandler } from "nitro/cache";
+
+export default defineCachedHandler(
+  (event) => {
+    return {
+      timestamp: Date.now(),
+    };
+  },
+  { swr: true, maxAge: 60, allowQuery: ["q"] }
+);

test/tests.ts

@@ -692,6 +692,27 @@ export function testNitro(
         }
       }
     );
+
+    it.skipIf(ctx.isIsolated || (isWindows && ctx.preset === "nitro-dev"))(
+      "allowQuery should ignore unlisted query params in cache key",
+      async () => {
+        const { data: first } = await callHandler({
+          url: "/api/cached-allow-query?q=search&utm_source=email",
+        });
+
+        // Same q param, different unlisted param should hit cache
+        const { data: second } = await callHandler({
+          url: "/api/cached-allow-query?q=search&utm_source=twitter",
+        });
+        expect(second.timestamp).toBe(first.timestamp);
+
+        // Different q param should get a different cache entry
+        const { data: third } = await callHandler({
+          url: "/api/cached-allow-query?q=other&utm_source=email",
+        });
+        expect(third.timestamp).not.toBe(first.timestamp);
+      }
+    );
   });
 
   describe("scanned files", () => {