feat: Key isolation

packages/e2e/react-router/v6/cypress/e2e/shared/key-isolation.cy.ts

@@ -0,0 +1,11 @@
+import { testKeyIsolation } from 'e2e-shared/specs/key-isolation.cy'
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryState',
+  hook: 'useQueryState'
+})
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/react-router/v6/src/react-router.tsx

@@ -41,6 +41,8 @@ const router = createBrowserRouter(
       <Route path="form/useQueryStates"                   lazy={load(import('./routes/form.useQueryStates'))} />
       <Route path="referential-stability/useQueryState"   lazy={load(import('./routes/referential-stability.useQueryState'))} />
       <Route path="referential-stability/useQueryStates"  lazy={load(import('./routes/referential-stability.useQueryStates'))} />
+      <Route path="key-isolation/useQueryState"           lazy={load(import('./routes/key-isolation.useQueryState'))} />
+      <Route path="key-isolation/useQueryStates"          lazy={load(import('./routes/key-isolation.useQueryStates'))} />
 
       <Route path="render-count/:hook/:shallow/:history/:startTransition/no-loader"     lazy={load(import('./routes/render-count.$hook.$shallow.$history.$startTransition.no-loader'))} />
       <Route path="render-count/:hook/:shallow/:history/:startTransition/sync-loader"   lazy={load(import('./routes/render-count.$hook.$shallow.$history.$startTransition.sync-loader'))} />

packages/e2e/react-router/v6/src/routes/key-isolation.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryState } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryState

packages/e2e/react-router/v6/src/routes/key-isolation.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryStates } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryStates

packages/e2e/react-router/v7/app/routes.ts

@@ -24,6 +24,8 @@ export default [
     route('/form/useQueryStates',                   './routes/form.useQueryStates.tsx'),
     route('/referential-stability/useQueryState',   './routes/referential-stability.useQueryState.tsx'),
     route('/referential-stability/useQueryStates',  './routes/referential-stability.useQueryStates.tsx'),
+    route('/key-isolation/useQueryState',           './routes/key-isolation.useQueryState.tsx'),
+    route('/key-isolation/useQueryStates',          './routes/key-isolation.useQueryStates.tsx'),
     route('/render-count/:hook/:shallow/:history/:startTransition/no-loader',    './routes/render-count.$hook.$shallow.$history.$startTransition.no-loader.tsx'),
     route('/render-count/:hook/:shallow/:history/:startTransition/sync-loader',  './routes/render-count.$hook.$shallow.$history.$startTransition.sync-loader.tsx'),
     route('/render-count/:hook/:shallow/:history/:startTransition/async-loader', './routes/render-count.$hook.$shallow.$history.$startTransition.async-loader.tsx'),

packages/e2e/react-router/v7/app/routes/key-isolation.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryState } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryState

packages/e2e/react-router/v7/app/routes/key-isolation.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryStates } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryStates

packages/e2e/react-router/v7/cypress/e2e/shared/key-isolation.cy.ts

@@ -0,0 +1,11 @@
+import { testKeyIsolation } from 'e2e-shared/specs/key-isolation.cy'
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryState',
+  hook: 'useQueryState'
+})
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/react/cypress/e2e/shared/key-isolation.cy.ts

@@ -0,0 +1,11 @@
+import { testKeyIsolation } from 'e2e-shared/specs/key-isolation.cy'
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryState',
+  hook: 'useQueryState'
+})
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/react/src/routes.tsx

@@ -21,6 +21,8 @@ const routes: Record<string, React.LazyExoticComponent<() => JSX.Element>> = {
   '/form/useQueryStates':                   lazy(() => import('./routes/form.useQueryStates')),
   '/referential-stability/useQueryState':   lazy(() => import('./routes/referential-stability.useQueryState')),
   '/referential-stability/useQueryStates':  lazy(() => import('./routes/referential-stability.useQueryStates')),
+  '/key-isolation/useQueryState':           lazy(() => import('./routes/key-isolation.useQueryState')),
+  '/key-isolation/useQueryStates':          lazy(() => import('./routes/key-isolation.useQueryStates')),
 
   '/render-count/useQueryState/true/replace/false':   lazy(() => import('./routes/render-count')),
   '/render-count/useQueryState/true/replace/true':    lazy(() => import('./routes/render-count')),

packages/e2e/react/src/routes/key-isolation.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryState } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryState

packages/e2e/react/src/routes/key-isolation.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryStates } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryStates

packages/e2e/remix/app/routes/key-isolation.useQueryState.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryState } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryState

packages/e2e/remix/app/routes/key-isolation.useQueryStates.tsx

@@ -0,0 +1,3 @@
+import { KeyIsolationUseQueryStates } from 'e2e-shared/specs/key-isolation'
+
+export default KeyIsolationUseQueryStates

packages/e2e/remix/cypress/e2e/shared/key-isolation.cy.ts

@@ -0,0 +1,11 @@
+import { testKeyIsolation } from 'e2e-shared/specs/key-isolation.cy'
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryState',
+  hook: 'useQueryState'
+})
+
+testKeyIsolation({
+  path: '/key-isolation/useQueryStates',
+  hook: 'useQueryStates'
+})

packages/e2e/shared/cypress/support/log-spy.ts

@@ -0,0 +1,13 @@
+export const stubConsoleLog = {
+  onBeforeLoad(window: any) {
+    cy.stub(window.console, 'log').as('consoleLog')
+  }
+}
+
+export function assertLogCount(message: string, expectedCount: number) {
+  cy.get('@consoleLog').then(spy => {
+    // @ts-ignore
+    const matchingLogs = spy.args.filter(args => args[0] === message)
+    expect(matchingLogs.length).to.equal(expectedCount)
+  })
+}

packages/e2e/shared/specs/key-isolation.cy.ts

@@ -0,0 +1,34 @@
+import { createTest } from '../create-test'
+import { assertLogCount, stubConsoleLog } from '../cypress/support/log-spy'
+
+export const testKeyIsolation = createTest('Key isolation', ({ path }) => {
+  it('does not render b when updating a', () => {
+    cy.visit(path, stubConsoleLog)
+    cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+    cy.get('#trigger-a').click()
+    cy.get('#state-a').should('have.text', 'pass')
+    cy.location('search').should('eq', '?a=pass')
+    assertLogCount('render a', 3) // 1 at mount + 2 at update
+    assertLogCount('render b', 1) // only 1 at mount
+  })
+  it('does not render a when updating b', () => {
+    cy.visit(path, stubConsoleLog)
+    cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+    cy.get('#trigger-b').click()
+    cy.get('#state-b').should('have.text', 'pass')
+    cy.location('search').should('eq', '?b=pass')
+    assertLogCount('render b', 3) // 1 at mount + 2 at update
+    assertLogCount('render a', 1) // only 1 at mount
+  })
+  it('does not render a again when updating b after a', () => {
+    cy.visit(path, stubConsoleLog)
+    cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
+    cy.get('#trigger-a').click()
+    cy.get('#state-a').should('have.text', 'pass')
+    cy.get('#trigger-b').click()
+    cy.get('#state-b').should('have.text', 'pass')
+    cy.location('search').should('eq', '?a=pass&b=pass')
+    assertLogCount('render a', 3) // 1 at mount + 2 at update
+    assertLogCount('render b', 3) // 1 at mount + 2 at update
+  })
+})

packages/e2e/shared/specs/key-isolation.tsx

@@ -0,0 +1,51 @@
+import { parseAsString, useQueryState, useQueryStates } from 'nuqs'
+
+type TestComponentProps = {
+  id: string
+}
+
+export function KeyIsolationUseQueryState() {
+  return (
+    <>
+      <TestComponentUseQueryState id="a" />
+      <TestComponentUseQueryState id="b" />
+    </>
+  )
+}
+
+export function KeyIsolationUseQueryStates() {
+  return (
+    <>
+      <TestComponentUseQueryStates id="a" />
+      <TestComponentUseQueryStates id="b" />
+    </>
+  )
+}
+
+function TestComponentUseQueryState({ id }: TestComponentProps) {
+  const [state, setState] = useQueryState(id)
+  console.log(`render ${id}`)
+  return (
+    <>
+      <button id={`trigger-${id}`} onClick={() => setState('pass')}>
+        Test {id}
+      </button>
+      <pre id={`state-${id}`}>{state}</pre>
+    </>
+  )
+}
+
+function TestComponentUseQueryStates({ id }: TestComponentProps) {
+  const [state, setState] = useQueryStates({
+    [id]: parseAsString
+  })
+  console.log(`render ${id}`)
+  return (
+    <>
+      <button id={`trigger-${id}`} onClick={() => setState({ [id]: 'pass' })}>
+        Test {id}
+      </button>
+      <pre id={`state-${id}`}>{state[id]}</pre>
+    </>
+  )
+}

packages/e2e/shared/specs/render-count.cy.ts

@@ -1,4 +1,5 @@
 import { createTest, type TestConfig } from '../create-test'
+import { assertLogCount, stubConsoleLog } from '../cypress/support/log-spy'
 
 type TestRenderCountConfig = TestConfig & {
   props: {
@@ -13,20 +14,6 @@ type TestRenderCountConfig = TestConfig & {
   }
 }
 
-const stubConsoleLog = {
-  onBeforeLoad(window: any) {
-    cy.stub(window.console, 'log').as('consoleLog')
-  }
-}
-
-function assertLogCount(message: string, expectedCount: number) {
-  cy.get('@consoleLog').then(spy => {
-    // @ts-ignore
-    const matchingLogs = spy.args.filter(args => args[0] === message)
-    expect(matchingLogs.length).to.equal(expectedCount)
-  })
-}
-
 export function testRenderCount({
   props,
   expected,
@@ -63,9 +50,9 @@ export function testRenderCount({
           if (props.delay) {
             cy.wait(props.delay)
           }
-          assertLogCount('render', expected.mount + expected.update)
           cy.get('#state').should('have.text', 'pass')
           cy.location('search').should('contain', 'test=pass')
+          assertLogCount('render', expected.mount + expected.update)
         }
       )
     }

packages/nuqs/src/adapters/lib/context.ts

@@ -30,10 +30,10 @@ export function createAdapterProvider(useAdapter: UseAdapterHook) {
     )
 }
 
-export function useAdapter() {
+export function useAdapter(watchKeys: string[]) {
   const value = useContext(context)
   if (!('useAdapter' in value)) {
     throw new Error(error(404))
   }
-  return value.useAdapter()
+  return value.useAdapter(watchKeys)
 }

packages/nuqs/src/adapters/lib/defs.ts

@@ -7,7 +7,7 @@ export type UpdateUrlFunction = (
   options: Required<AdapterOptions>
 ) => void
 
-export type UseAdapterHook = () => AdapterInterface
+export type UseAdapterHook = (watchKeys: string[]) => AdapterInterface
 
 export type AdapterInterface = {
   searchParams: URLSearchParams

packages/nuqs/src/adapters/lib/key-isolation.ts

@@ -0,0 +1,49 @@
+import { debug } from '../../debug'
+
+export function applyChange(
+  newValue: URLSearchParams,
+  keys: string[],
+  copy: boolean
+) {
+  return (oldValue: URLSearchParams) => {
+    const hasChanged =
+      keys.length === 0
+        ? true
+        : keys.some(key => oldValue.get(key) !== newValue.get(key))
+    if (!hasChanged) {
+      debug(
+        '[nuqs `%s`] no change, returning previous',
+        keys.join(','),
+        oldValue
+      )
+      return oldValue
+    }
+    const filtered = filterSearchParams(newValue, keys, copy)
+    debug(
+      `[nuqs \`%s\`] subbed search params change
+  from %O
+  to   %O`,
+      keys.join(','),
+      oldValue,
+      filtered
+    )
+    return filtered
+  }
+}
+
+export function filterSearchParams(
+  search: URLSearchParams,
+  keys: string[],
+  copy: boolean
+) {
+  if (keys.length === 0) {
+    return search
+  }
+  const filtered = copy ? new URLSearchParams(search) : search
+  for (const key of search.keys()) {
+    if (!keys.includes(key)) {
+      filtered.delete(key)
+    }
+  }
+  return filtered
+}

packages/nuqs/src/adapters/lib/react-router.ts

@@ -2,6 +2,7 @@ import mitt from 'mitt'
 import { startTransition, useCallback, useEffect, useState } from 'react'
 import { renderQueryString } from '../../url-encoding'
 import type { AdapterInterface, AdapterOptions } from './defs'
+import { applyChange, filterSearchParams } from './key-isolation'
 import {
   historyUpdateMarker,
   patchHistory,
@@ -20,7 +21,6 @@ type NavigateOptions = {
 }
 type NavigateFn = (url: NavigateUrl, options: NavigateOptions) => void
 type UseNavigate = () => NavigateFn
-
 type UseSearchParams = () => [URLSearchParams, {}]
 
 // --
@@ -31,9 +31,11 @@ export function createReactRouterBasedAdapter(
   useSearchParams: UseSearchParams
 ) {
   const emitter: SearchParamsSyncEmitter = mitt()
-  function useNuqsReactRouterBasedAdapter(): AdapterInterface {
+  function useNuqsReactRouterBasedAdapter(
+    watchKeys: string[]
+  ): AdapterInterface {
     const navigate = useNavigate()
-    const searchParams = useOptimisticSearchParams()
+    const searchParams = useOptimisticSearchParams(watchKeys)
     const updateUrl = useCallback(
       (search: URLSearchParams, options: AdapterOptions) => {
         startTransition(() => {
@@ -77,15 +79,21 @@ export function createReactRouterBasedAdapter(
       updateUrl
     }
   }
-  function useOptimisticSearchParams() {
+  function useOptimisticSearchParams(watchKeys: string[] = []) {
     const [serverSearchParams] = useSearchParams()
-    const [searchParams, setSearchParams] = useState(serverSearchParams)
+    const [searchParams, setSearchParams] = useState(() => {
+      // Make a copy to avoid modifying the original search params
+      return filterSearchParams(serverSearchParams, watchKeys, true)
+    })
+
     useEffect(() => {
       function onPopState() {
-        setSearchParams(new URLSearchParams(location.search))
+        setSearchParams(
+          applyChange(new URLSearchParams(location.search), watchKeys, false)
+        )
       }
       function onEmitterUpdate(search: URLSearchParams) {
-        setSearchParams(search)
+        setSearchParams(applyChange(search, watchKeys, true))
       }
       emitter.on('update', onEmitterUpdate)
       window.addEventListener('popstate', onPopState)