feat: Debounce (#900)

Author: franky47

packages/docs/content/docs/options.mdx

@@ -130,43 +130,145 @@ useQueryState('foo', { scroll: true })
 ```
 
 
-## Throttling URL updates
+## Rate-limiting URL updates
 
 Because of browsers rate-limiting the History API, updates **to the
 URL** are queued and throttled to a default of 50ms, which seems to satisfy
 most browsers even when sending high-frequency query updates, like binding
 to a text input or a slider.
 
-Safari's rate limits are much higher and require a throttle of 120ms (320ms for older
-versions of Safari).
+Safari's rate limits are much higher and use a default throttle of 120ms
+(320ms for older versions of Safari).
 
-If you want to opt-in to a larger throttle time -- for example to reduce the amount
+<Callout title="Note">
+the state returned by the hook is always updated **instantly**, to keep UI responsive.
+Only changes to the URL, and server requests when using `shallow: false{:ts}`, are throttled.
+</Callout>
+
+This throttle time is configurable, and also allows you to debounce updates
+instead.
+
+<Callout title="Which one should I use?">
+Throttle will emit the first update immediately, then batch updates at a slower
+pace **regularly**. This is recommended for most low-frequency updates.
+
+Debounce will push back the moment when the URL is updated when you set your state,
+making it **eventually consistent**. This is recommended for high-frequency
+updates where the last value is more interesting than the intermediate ones,
+like a search input or moving a slider.
+
+Read more about [debounce vs throttle](https://kettanaito.com/blog/debounce-vs-throttle).
+</Callout>
+
+### Throttle
+
+If you want to increase the throttle time -- for example to reduce the amount
 of requests sent to the server when paired with `shallow: false{:ts}` -- you can
-specify it under the `throttleMs` option:
+specify it under the `limitUrlUpdates` option:
 
-```tsx
-// [!code word:throttleMs]
+```ts /limitUrlUpdates/
 useQueryState('foo', {
   // Send updates to the server maximum once every second
   shallow: false,
-  throttleMs: 1000
+  limitUrlUpdates: {
+    method: 'throttle',
+    timeMs: 1000
+  }
 })
-```
 
-<Callout title="Note">
-the state returned by the hook is always updated **instantly**, to keep UI responsive.
-Only changes to the URL, and server requests when using `shallow: false{:ts}`, are throttled.
-</Callout>
+// or using the shorthand:
+import { throttle } from 'nuqs'
+
+useQueryState('foo', {
+  shallow: false,
+  limitUrlUpdates: throttle(1000)
+})
+```
 
 If multiple hooks set different throttle values on the same event loop tick,
 the highest value will be used. Also, values lower than 50ms will be ignored,
 to avoid rate-limiting issues.
 [Read more](https://francoisbest.com/posts/2023/storing-react-state-in-the-url-with-nextjs#batching--throttling).
 
-Specifying a `+Infinity{:ts}` value for `throttleMs{:ts}` will **disable** updates to the
+Specifying a `+Infinity{:ts}` value for throttle time will **disable** updates to the
 URL or the server, but all `useQueryState(s)` hooks will still update their
 internal state and stay in sync with each other.
 
+<Callout title="Deprecation notice">
+The `throttleMs` option has been deprecated in `nuqs@2.4.0` and will be removed
+in a later major upgrade.
+
+To migrate:
+1. `import { throttle } from 'nuqs' {:ts}`
+2.  Replace `{ throttleMs: 100 }{:ts}` with `{ limitUrlUpdates: throttle(100) }{:ts}` in your options.
+</Callout>
+
+### Debounce
+
+In addition to throttling, you can apply a debouncing mechanism to state updates,
+to delay the moment where the URL gets updated with the latest value.
+
+This can be useful for high frequency state updates where you only care about
+the final value, not all the intermediary ones while typing in a search input
+or moving a slider.
+
+We recommend you opt-in to debouncing on specific state updates, rather than
+defining it for the whole search param.
+
+Let's take the example of a search input. You'll want to update it:
+
+1. When the user is typing text, with debouncing
+2. When the user clears the input, by sending an immediate update
+3. When the user presses Enter, by sending an immediate update
+
+You can see the debounce case is the outlier here, and actually conditioned on
+the set value, so we can specify it using the state updater function:
+
+```tsx
+import { useQueryState, parseAsString, debounce } from 'nuqs';
+
+function Search() {
+  const [search, setSearch] = useQueryState(
+    'q',
+    parseAsString.withDefault('').withOptions({ shallow: false })
+  )
+
+  return (
+    <input
+      value={search}
+      onChange={(e) =>
+        setSearch(e.target.value, {
+          // Send immediate update if resetting, otherwise debounce at 500ms
+          limitUrlUpdates: e.target.value === '' ? undefined : debounce(500)
+        })
+      }
+      onKeyPress={(e) => {
+        if (e.key === 'Enter') {
+          // Send immediate update
+          setSearch(e.target.value)
+        }
+      }}
+    />
+  )
+}
+```
+
+### Resetting
+
+You can use the `defaultRateLimit{:ts}` import to reset debouncing or throttling to
+the default:
+
+```ts /defaultRateLimit/
+import { debounce, defaultRateLimit } from 'nuqs'
+
+const [, setState] = useQueryState('foo', {
+  limitUrlUpdates: debounce(1000)
+})
+
+// This state update isn't debounced
+setState('bar', { limitUrlUpdates: defaultRateLimit })
+```
+
 
 ## Transitions
 

packages/docs/package.json

@@ -52,7 +52,6 @@
     "recharts": "^2.15.2",
     "remark-smartypants": "^3.0.2",
     "res": "workspace:*",
-    "semver": "^7.7.1",
     "server-only": "^0.0.1",
     "tailwind-merge": "^2.6.0",
     "tailwindcss": "^3.4.17",
@@ -64,7 +63,6 @@
     "@types/mdx": "^2.0.13",
     "@types/react": "catalog:react19",
     "@types/react-dom": "catalog:react19",
-    "@types/semver": "^7.7.0",
     "autoprefixer": "^10.4.21",
     "hast-util-to-jsx-runtime": "^2.3.6",
     "postcss": "^8.5.3",

packages/e2e/next/cypress.config.ts

@@ -1,27 +1,11 @@
 import { defineConfig } from 'e2e-shared/cypress.config'
-import fs from 'node:fs'
-import semver from 'semver'
 
 const basePath =
   process.env.BASE_PATH === '/' ? '' : (process.env.BASE_PATH ?? '')
 
-const nextJsVersion = readNextJsVersion()
-
 export default defineConfig({
   baseUrl: `http://localhost:3001${basePath}`,
   env: {
-    basePath,
-    supportsShallowRouting: supportsShallowRouting(nextJsVersion),
-    nextJsVersion
+    basePath
   }
 })
-
-function readNextJsVersion() {
-  const pkgPath = new URL('./node_modules/next/package.json', import.meta.url)
-  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
-  return pkg.version
-}
-
-function supportsShallowRouting(nextVersion: string) {
-  return semver.gte(nextVersion, '14.1.0')
-}

packages/e2e/next/cypress/e2e/persist-across-navigation.cy.js renamed to packages/e2e/next/cypress/e2e/persist-across-navigation.cy.ts

@@ -1,15 +1,12 @@
-/// <reference types="cypress" />
+import { expectPathname } from 'e2e-shared/lib/assertions'
 
 it('Persists search params across navigation using a generated Link href', () => {
   cy.visit('/app/persist-across-navigation/a')
   cy.contains('#hydration-marker', 'hydrated').should('be.hidden')
   cy.get('input[type=text]').type('foo', { delay: 0 })
   cy.get('input[type=checkbox]').check()
   cy.get('a').click()
-  cy.location('pathname').should(
-    'eq',
-    `${Cypress.env('basePath')}/app/persist-across-navigation/b`
-  )
+  expectPathname('/app/persist-across-navigation/b')
   cy.location('search').should('eq', '?q=foo&checked=true')
   cy.get('input[type=text]').should('have.value', 'foo')
   cy.get('input[type=checkbox]').should('be.checked')