fix: Deep equality check on cache parsing input

A change introduced in Next.js 15.0.0-canary.41 (precisely vercel/next.js#67105)
broke the referential stability that the cache.parse method was expecting to detect
`parse` being called with the same search params.

Now we're using a deep equality check by caching the serialized query string
that was parsed, and comparing it with the input when called again.

Author: franky47

Diff for: packages/nuqs/src/cache.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { createSearchParamsCache } from './cache'
+import { createSearchParamsCache, stringify } from './cache'
 import { parseAsString } from './parsers'
 
 // provide a simple mock for React cache
@@ -22,7 +22,7 @@ describe('cache', () => {
       string: "I'm a string"
     }
 
-    it('allows parsing same object multiple times in a request', () => {
+    it('allows parsing the same object multiple times in a request', () => {
       const cache = createSearchParamsCache({
         string: parseAsString
       })
@@ -37,6 +37,15 @@ describe('cache', () => {
       expect(cache.all()).toBe(all)
     })
 
+    it('allows parsing the same content with different references', () => {
+      const cache = createSearchParamsCache({
+        string: parseAsString
+      })
+      const copy = { ...input }
+      expect(cache.parse(input).string).toBe(input.string)
+      expect(cache.parse(copy).string).toBe(input.string)
+    })
+
     it('disallows parsing different objects in a request', () => {
       const cache = createSearchParamsCache({
         string: parseAsString
@@ -51,4 +60,16 @@ describe('cache', () => {
       expect(cache.all()).toBe(all)
     })
   })
+
+  describe('stringify', () => {
+    it('works on string values', () => {
+      expect(stringify({ foo: 'bar' })).toEqual('foo=bar')
+    })
+    it('works on array values', () => {
+      expect(stringify({ foo: ['bar', 'baz'] })).toEqual('foo=bar%2Cbaz')
+    })
+    it('works on undefined values', () => {
+      expect(stringify({ foo: undefined })).toEqual('foo=undefined')
+    })
+  })
 })

Diff for: packages/nuqs/src/cache.ts

@@ -21,7 +21,7 @@ export function createSearchParamsCache<
 
   type Cache = {
     searchParams: Partial<ParsedSearchParams>
-    [$input]?: SearchParams
+    [$input]?: string
   }
 
   // Why not use a good old object here ?
@@ -34,28 +34,23 @@ export function createSearchParamsCache<
   }))
   function parse(searchParams: SearchParams) {
     const c = getCache()
-
     if (Object.isFrozen(c.searchParams)) {
-      // parse has already been called
-      if (searchParams === c[$input]) {
-        // but we're being called with the identical object again, so we can safely return the same cached result
-        // (an example of when this occurs would be if parse was called in generateMetadata as well as the page itself).
-        // note that this simply checks for referential equality and will still fail if a different object with the
-        // same contents is passed. fortunately next.js uses the same object for search params in the same request.
+      // Parse has already been called...
+      if (stringify(searchParams) === c[$input]) {
+        // ...but we're being called with the same contents again,
+        // so we can safely return the same cached result (an example of when
+        // this occurs would be if parse was called in generateMetadata as well
+        // as the page itself).
         return all()
       }
-
-      // different input in the same request - fail
+      // Different inputs in the same request - fail
       throw new Error(error(501))
     }
-
     for (const key in parsers) {
       const parser = parsers[key]!
       c.searchParams[key] = parser.parseServerSide(searchParams[key])
     }
-
-    c[$input] = searchParams
-
+    c[$input] = stringify(searchParams)
     return Object.freeze(c.searchParams) as Readonly<ParsedSearchParams>
   }
   function all() {
@@ -80,3 +75,12 @@ export function createSearchParamsCache<
   }
   return { parse, get, all }
 }
+
+/**
+ * Internal function: reduce a SearchParams object to a string
+ * for internal comparison of inputs passed to the cache's `parse` function.
+ */
+export function stringify(searchParams: SearchParams) {
+  // @ts-expect-error - URLSearchParams is actually OK with array values
+  return new URLSearchParams(searchParams).toString()
+}

Diff for: packages/nuqs/src/index.server.ts

@@ -1,3 +1,3 @@
-export * from './cache'
+export { createSearchParamsCache, type SearchParams } from './cache'
 export * from './parsers'
 export { createSerializer } from './serializer'