chore: Shallow-compare objects rather than stringifying

While the searchParams object is not referentially stable,
its values are, so we can do a simple shallow comparison.
Adding a test case in the e2e test to make sure this holds
with array of values (repeated keys in the query string).

Author: franky47

packages/e2e/cypress/e2e/cache.cy.js

@@ -2,7 +2,7 @@
 
 describe('cache', () => {
   it('works in app router', () => {
-    cy.visit('/app/cache?str=foo&num=42&bool=true')
+    cy.visit('/app/cache?str=foo&num=42&bool=true&multi=foo&multi=bar')
     cy.get('#parse-str').should('have.text', 'foo')
     cy.get('#parse-num').should('have.text', '42')
     cy.get('#parse-bool').should('have.text', 'true')

packages/nuqs/src/cache.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { createSearchParamsCache, stringify } from './cache'
+import { compareSearchParams, createSearchParamsCache } from './cache'
 import { parseAsString } from './parsers'
 
 // provide a simple mock for React cache
@@ -61,15 +61,29 @@ describe('cache', () => {
     })
   })
 
-  describe('stringify', () => {
-    it('works on string values', () => {
-      expect(stringify({ foo: 'bar' })).toEqual('foo=bar')
+  describe('compareSearchParams', () => {
+    it('works on empty search params', () => {
+      expect(compareSearchParams({}, {})).toBe(true)
     })
-    it('works on array values', () => {
-      expect(stringify({ foo: ['bar', 'baz'] })).toEqual('foo=bar%2Cbaz')
+    it('rejects different lengths', () => {
+      expect(compareSearchParams({ a: 'a' }, { a: 'a', b: 'b' })).toBe(false)
     })
-    it('works on undefined values', () => {
-      expect(stringify({ foo: undefined })).toEqual('foo=undefined')
+    it('rejects different values', () => {
+      expect(compareSearchParams({ x: 'a' }, { x: 'b' })).toBe(false)
+    })
+    it('does not care about order', () => {
+      expect(compareSearchParams({ x: 'a', y: 'b' }, { y: 'b', x: 'a' })).toBe(
+        true
+      )
+    })
+    it('supports array values (referentially stable)', () => {
+      const array = ['a', 'b']
+      expect(compareSearchParams({ x: array }, { x: array })).toBe(true)
+    })
+    it('does not do deep comparison', () => {
+      expect(compareSearchParams({ x: ['a', 'b'] }, { x: ['a', 'b'] })).toBe(
+        false
+      )
     })
   })
 })

packages/nuqs/src/cache.ts

@@ -21,7 +21,7 @@ export function createSearchParamsCache<
 
   type Cache = {
     searchParams: Partial<ParsedSearchParams>
-    [$input]?: string
+    [$input]?: SearchParams
   }
 
   // Why not use a good old object here ?
@@ -36,7 +36,7 @@ export function createSearchParamsCache<
     const c = getCache()
     if (Object.isFrozen(c.searchParams)) {
       // Parse has already been called...
-      if (stringify(searchParams) === c[$input]) {
+      if (c[$input] && compareSearchParams(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
@@ -50,7 +50,7 @@ export function createSearchParamsCache<
       const parser = parsers[key]!
       c.searchParams[key] = parser.parseServerSide(searchParams[key])
     }
-    c[$input] = stringify(searchParams)
+    c[$input] = searchParams
     return Object.freeze(c.searchParams) as Readonly<ParsedSearchParams>
   }
   function all() {
@@ -76,11 +76,17 @@ 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()
+export function compareSearchParams(a: SearchParams, b: SearchParams) {
+  if (a === b) {
+    return true
+  }
+  if (Object.keys(a).length !== Object.keys(b).length) {
+    return false
+  }
+  for (const key in a) {
+    if (a[key] !== b[key]) {
+      return false
+    }
+  }
+  return true
 }