feat: Allow remapping keys in useQueryStates (#671)

* feat: Allow remapping keys in useQueryStates

While it was possible to do it via speading & remapping variable names
in userland, this makes it more declarative and should help decouple
business/domain logic in variable names vs short URL search param keys.

* chore: Fix useEffect loop due to referential inconsistency of default value

* chore: Fix dependency arrays

* doc: Adding docs on key remapping in useQueryStates

Author: franky47

Diff for: packages/docs/content/docs/batching.mdx

@@ -111,3 +111,36 @@ This will clear `lat` & `lng`, and leave other search params untouched.
 
 </Callout>
 
+### Shorter search params keys
+
+One issue with tying the parsers object keys to the search params keys was that
+you had to trade-off between variable names that make sense for your domain
+or business logic, and short, URL-friendly keys.
+
+In `nuqs@1.20.0` and later, you can use a `urlKeys` object in the hook options
+to remap the variable names to shorter keys:
+
+```ts
+const [{ latitude, longitude }, setCoordinates] = useQueryStates(
+  {
+    // Use variable names that make sense in your codebase
+    latitude: parseAsFloat.withDefault(45.18),
+    longitude: parseAsFloat.withDefault(5.72)
+  },
+  {
+    urlKeys: {
+      // And remap them to shorter keys in the URL
+      latitude: 'lat',
+      longitude: 'lng'
+    }
+  }
+)
+
+// No changes in the setter API, but the keys are remapped to:
+// ?lat=45.18&lng=5.72
+setCoordinates({
+  latitude: 45.18,
+  longitude: 5.72
+})
+```
+

Diff for: packages/e2e/cypress/e2e/remapped-keys.cy.js

@@ -0,0 +1,11 @@
+/// <reference types="cypress" />
+
+it('Remapped keys', () => {
+  cy.visit('/app/remapped-keys')
+  cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+  cy.get('#search').type('a')
+  cy.get('#page').clear().type('42')
+  cy.get('#react').check()
+  cy.get('#nextjs').check()
+  cy.location('search').should('eq', '?q=a&page=42&tags=react,next.js')
+})

Diff for: packages/e2e/src/app/app/remapped-keys/page.tsx

@@ -0,0 +1,92 @@
+'use client'
+
+import {
+  parseAsArrayOf,
+  parseAsInteger,
+  parseAsString,
+  useQueryStates
+} from 'nuqs'
+import { Suspense } from 'react'
+
+export default function Page() {
+  return (
+    <Suspense>
+      <Client />
+    </Suspense>
+  )
+}
+
+function Client() {
+  const [{ searchQuery, pageNumber, activeTags }, setURLState] = useQueryStates(
+    {
+      searchQuery: parseAsString.withDefault(''),
+      pageNumber: parseAsInteger.withDefault(1),
+      activeTags: parseAsArrayOf(parseAsString).withDefault([])
+    },
+    {
+      clearOnDefault: true,
+      urlKeys: {
+        searchQuery: 'q',
+        pageNumber: 'page',
+        activeTags: 'tags'
+      }
+    }
+  )
+
+  return (
+    <>
+      <label style={{ display: 'block' }}>
+        <input
+          id="search"
+          value={searchQuery}
+          onChange={e => setURLState({ searchQuery: e.target.value })}
+        />
+        <span>Search</span>
+      </label>
+      <label style={{ display: 'block' }}>
+        <input
+          id="page"
+          type="number"
+          min={1}
+          max={5}
+          step={1}
+          value={pageNumber}
+          onChange={e => setURLState({ pageNumber: e.target.valueAsNumber })}
+        />
+        <span>Page</span>
+      </label>
+      <label style={{ display: 'block' }}>
+        <label>
+          <input
+            id="react"
+            type="checkbox"
+            checked={activeTags.includes('react')}
+            onChange={e =>
+              setURLState(old => ({
+                activeTags: e.target.checked
+                  ? [...old.activeTags, 'react']
+                  : old.activeTags.filter(tag => !tag.includes('react'))
+              }))
+            }
+          />
+          React SPA
+        </label>
+        <label>
+          <input
+            id="nextjs"
+            type="checkbox"
+            checked={activeTags.includes('next.js')}
+            onChange={e =>
+              setURLState(old => ({
+                activeTags: e.target.checked
+                  ? [...old.activeTags, 'next.js']
+                  : old.activeTags.filter(tag => !tag.includes('next.js'))
+              }))
+            }
+          />
+          Next.js
+        </label>
+      </label>
+    </>
+  )
+}

Diff for: packages/nuqs/src/tests/useQueryStates.test-d.ts

@@ -1,4 +1,4 @@
-import { expectNotAssignable, expectType } from 'tsd'
+import { expectError, expectNotAssignable, expectType } from 'tsd'
 import {
   parseAsBoolean,
   parseAsFloat,
@@ -77,3 +77,44 @@ import {
     bin: Buffer
   }>(states)
 }
+
+// Remapped keys
+{
+  const [states, setStates] = useQueryStates(
+    {
+      foo: parseAsString,
+      bar: parseAsString
+    },
+    {
+      urlKeys: {
+        foo: 'f'
+        // bar: 'b' // allows partial remapping
+      }
+    }
+  )
+  expectType<{
+    foo: string | null
+    bar: string | null
+  }>(states)
+  setStates({
+    foo: 'baz',
+    bar: 'qux'
+  })
+}
+
+// Remapped keys
+{
+  expectError(() => {
+    useQueryStates(
+      {
+        foo: parseAsString,
+        bar: parseAsString
+      },
+      {
+        urlKeys: {
+          notInTheList: 'f'
+        }
+      }
+    )
+  })
+}