ref: remove debounce + shallow: true warning

Author: franky47

errors/NUQS-422.md

@@ -1,11 +1,17 @@
 # Invalid Options Combination.
 
-This warning will show up if you combine `shallow: true` (the default) and `limitUrlUpdates: debounce` options.
+This warning did show up between versions `nuqs@>=2.6.0 && nuqs@<=2.7.2` if you combined `shallow: true` (the default) and `limitUrlUpdates: debounce` options.
 
-Debounce only makes sense for server-side data fetching, the returned client state is always updated **immediately**, so combining `limitUrlUpdates: debounce` with `shallow: true` will not work as expected.
+The initial argument was that:
 
-If you are fetching client-side, you’ll want to debounce the state returned by the hooks instead (using a 3rd party `useDebounce` utility hook).
+> Debounce only made sense for server-side data fetching, the returned client state is always updated **immediately**, so combining `limitUrlUpdates: debounce` with `shallow: true` will not work as expected.
+>
+> If you are fetching client-side, you’ll want to debounce the state returned by the hooks instead (using a 3rd party `useDebounce` utility hook).
 
-## Solution
+However, debounce _does_ have a purpose even in shallow routing: **reducing history bloat**.
 
-- Set `shallow: false` to allow debounce to work properly, check the [documentation](https://nuqs.dev/docs/options#debounce) for more information.
+While nuqs uses `history: replace` by default to avoid polluting your history **stack** (the one you navigate with the Back & Forward browser buttons), every URL update is recorded in the browser's **global history** (that you access via a menu, like `⌘ Y`).
+
+Debouncing gives you finer control over how this global history is populated, with the trade-off of a less reactive URL.
+
+Regardless, debounce only applies to URL updates, so the recommendation for client-side fetching still stands: you'll likely want to debounce the returned state in userland before feeding it to TanStack Query, SWC, tRPC or other tools.

packages/nuqs/src/adapters/next/impl.app.ts

@@ -61,7 +61,7 @@ export function NavigationSpy() {
 
 export function useNuqsNextAppRouterAdapter(): AdapterInterface {
   const router = useRouter()
-  const searchParams = useSearchParams() ?? new URLSearchParams()
+  const searchParams = useSearchParams()
   const [optimisticSearchParams, setOptimisticSearchParams] =
     useOptimistic<URLSearchParams>(searchParams)
   const updateUrl: UpdateUrlFunction = useCallback((search, options) => {

packages/nuqs/src/lib/errors.ts

@@ -3,7 +3,6 @@ export const errors = {
   404: 'nuqs requires an adapter to work with your framework.',
   409: 'Multiple versions of the library are loaded. This may lead to unexpected behavior. Currently using `%s`, but `%s` (via the %s adapter) was about to load on top.',
   414: 'Max safe URL length exceeded. Some browsers may not be able to accept this URL. Consider limiting the amount of state stored in the URL.',
-  422: 'Invalid options combination: `limitUrlUpdates: debounce` should be used in SSR scenarios, with `shallow: false`',
   429: 'URL update rate-limited by the browser. Consider increasing `throttleMs` for key(s) `%s`. %O',
   500: "Empty search params cache. Search params can't be accessed in Layouts.",
   501: 'Search params cache already populated. Have you called `parse` twice?'

packages/nuqs/src/useQueryStates.ts

@@ -7,7 +7,6 @@ import {
 import type { Nullable, Options, UrlKeys } from './defs'
 import { compareQuery } from './lib/compare'
 import { debug } from './lib/debug'
-import { error } from './lib/errors'
 import { debounceController } from './lib/queues/debounce'
 import { defaultRateLimit } from './lib/queues/rate-limiting'
 import {
@@ -323,9 +322,6 @@ export function useQueryStates<KeyMap extends UseQueryStatesKeysMap>(
           limitUrlUpdates?.method === 'debounce' ||
           parser.limitUrlUpdates?.method === 'debounce'
         ) {
-          if (update.options.shallow === true) {
-            console.warn(error(422))
-          }
           const timeMs =
             callOptions?.limitUrlUpdates?.timeMs ??
             limitUrlUpdates?.timeMs ??