feat: Expose shorthand helpers for limitUrlUpdates

Author: franky47

packages/e2e/next/src/app/app/debounce/client.tsx

@@ -1,16 +1,20 @@
 'use client'
 
-import { parseAsInteger, useQueryState, useQueryStates } from 'nuqs'
+import {
+  debounce,
+  parseAsInteger,
+  throttle,
+  useQueryState,
+  useQueryStates
+} from 'nuqs'
 import { searchParams, urlKeys } from './search-params'
 
 export function Client() {
   const [timeMs, setTimeMs] = useQueryState(
     'debounceTime',
     parseAsInteger.withDefault(100).withOptions({
-      limitUrlUpdates: {
-        method: 'throttle',
-        timeMs: 200
-      }
+      // No real need to throttle this one, but it showcases usage:
+      limitUrlUpdates: throttle(200)
     })
   )
   const [{ search, pageIndex }, setSearchParams] = useQueryStates(
@@ -28,30 +32,23 @@ export function Client() {
           setSearchParams(
             { search: e.target.value },
             {
-              limitUrlUpdates: {
-                method: e.target.value === '' ? 'throttle' : 'debounce',
-                timeMs: e.target.value === '' ? 50 : timeMs
-              }
+              // Instant update when clearing the input, otherwise debounce
+              limitUrlUpdates:
+                e.target.value === '' ? undefined : debounce(timeMs)
             }
           )
         }
+        onKeyDown={e => {
+          if (e.key === 'Enter') {
+            // Send the search immediately when pressing Enter
+            setSearchParams({ search: e.currentTarget.value })
+          }
+        }}
       />
       <button onClick={() => setSearchParams({ pageIndex: pageIndex + 1 })}>
         Next Page
       </button>
-      <button
-        onClick={() => {
-          setTimeMs(null)
-          setSearchParams(null, {
-            limitUrlUpdates: {
-              method: 'throttle',
-              timeMs: 50
-            }
-          })
-        }}
-      >
-        Reset
-      </button>
+      <button onClick={() => setSearchParams(null)}>Reset</button>
       <div style={{ marginTop: '1rem' }}>
         <label style={{ display: 'flex', alignItems: 'center', gap: '0.5rem' }}>
           <input

packages/e2e/next/src/app/app/debounce/search-params.ts

@@ -6,9 +6,7 @@ import {
 } from 'nuqs/server'
 
 export const searchParams = {
-  search: parseAsString.withDefault('').withOptions({
-    limitUrlUpdates: { method: 'debounce', timeMs: 2000 }
-  }),
+  search: parseAsString.withDefault(''),
   pageIndex: parseAsInteger.withDefault(0)
 }
 export const urlKeys: UrlKeys<typeof searchParams> = {

packages/nuqs/src/defs.ts

@@ -2,6 +2,9 @@ import type { TransitionStartFunction } from 'react'
 
 export type SearchParams = Record<string, string | string[] | undefined>
 export type HistoryOptions = 'replace' | 'push'
+export type LimitUrlUpdates =
+  | { method: 'debounce'; timeMs: number }
+  | { method: 'throttle'; timeMs: number }
 
 export type Options = {
   /**
@@ -55,10 +58,7 @@ export type Options = {
    * If both `throttleMs` and `limitUrlUpdates` are set, `limitUrlUpdates` will
    * take precedence.
    */
-  limitUrlUpdates?: {
-    method: 'debounce' | 'throttle'
-    timeMs: number
-  }
+  limitUrlUpdates?: LimitUrlUpdates
 
   /**
    * In RSC frameworks, opt-in to observing Server Component loading states when

packages/nuqs/src/index.server.ts

@@ -6,6 +6,11 @@ export type {
   SearchParams,
   UrlKeys
 } from './defs'
+export {
+  debounce,
+  defaultRateLimit,
+  throttle
+} from './lib/queues/rate-limiting'
 export {
   createLoader,
   type LoaderFunction,

packages/nuqs/src/index.ts

@@ -5,6 +5,11 @@ export type {
   SearchParams,
   UrlKeys
 } from './defs'
+export {
+  debounce,
+  defaultRateLimit,
+  throttle
+} from './lib/queues/rate-limiting'
 export {
   createLoader,
   type LoaderFunction,

packages/nuqs/src/lib/queues/rate-limiting.ts

@@ -0,0 +1,28 @@
+import type { LimitUrlUpdates } from '../../defs'
+
+// edit: Safari 17 now allows 100 calls per 10 seconds, a bit better.
+function getDefaultThrottle() {
+  if (typeof window === 'undefined') return 50
+  // https://stackoverflow.com/questions/7944460/detect-safari-browser
+  // @ts-expect-error
+  const isSafari = Boolean(window.GestureEvent)
+  if (!isSafari) {
+    return 50
+  }
+  try {
+    const match = navigator.userAgent?.match(/version\/([\d\.]+) safari/i)
+    return parseFloat(match![1]!) >= 17 ? 120 : 320
+  } catch {
+    return 320
+  }
+}
+
+export function throttle(timeMs: number): LimitUrlUpdates {
+  return { method: 'throttle', timeMs }
+}
+
+export function debounce(timeMs: number): LimitUrlUpdates {
+  return { method: 'debounce', timeMs }
+}
+
+export const defaultRateLimit = throttle(getDefaultThrottle())

packages/nuqs/src/lib/queues/throttle.ts

@@ -7,30 +7,7 @@ import { compose } from '../compose'
 import { debug } from '../debug'
 import { error } from '../errors'
 import { withResolvers, type Resolvers } from '../with-resolvers'
-
-// edit: Safari 17 now allows 100 calls per 10 seconds, a bit better.
-export function getDefaultThrottle() {
-  if (typeof window === 'undefined') return 50
-  // https://stackoverflow.com/questions/7944460/detect-safari-browser
-  // @ts-expect-error
-  const isSafari = Boolean(window.GestureEvent)
-  if (!isSafari) {
-    return 50
-  }
-  try {
-    const match = navigator.userAgent?.match(/version\/([\d\.]+) safari/i)
-    return parseFloat(match![1]!) >= 17 ? 120 : 320
-  } catch {
-    return 320
-  }
-}
-
-export const defaultRateLimit: NonNullable<Options['limitUrlUpdates']> = {
-  method: 'throttle',
-  timeMs: getDefaultThrottle()
-}
-
-// --
+import { defaultRateLimit } from './rate-limiting'
 
 type UpdateMap = Map<string, string | null>
 type TransitionSet = Set<React.TransitionStartFunction>

packages/nuqs/src/useQueryState.ts

@@ -3,8 +3,8 @@ import { useAdapter } from './adapters/lib/context'
 import type { Options } from './defs'
 import { debug } from './lib/debug'
 import { debounceController } from './lib/queues/debounce'
+import { defaultRateLimit } from './lib/queues/rate-limiting'
 import {
-  defaultRateLimit,
   globalThrottleQueue,
   type UpdateQueuePushArgs
 } from './lib/queues/throttle'

packages/nuqs/src/useQueryStates.ts

@@ -3,8 +3,8 @@ import { useAdapter } from './adapters/lib/context'
 import type { Nullable, Options, UrlKeys } from './defs'
 import { debug } from './lib/debug'
 import { debounceController } from './lib/queues/debounce'
+import { defaultRateLimit } from './lib/queues/rate-limiting'
 import {
-  defaultRateLimit,
   globalThrottleQueue,
   type UpdateQueuePushArgs
 } from './lib/queues/throttle'