[Proposal] Add an API to clear all search params

[mwskwong]

I noticed there are use cases where I simply want to clear all search params with no logic involved. E.g., reset all search filters.

I would propose making the 1st argument of useQueryStates (i.e. keyMap) optional. Omitting/passing undefined to keyMap denote it should subscribe to all search params.

This also allows us to specify separate configs from that individual search param subscription.

i.e.

const [isResetPending, startResetTransition] = useTransition();
const [, setQueryStates] = useQueryStates(undefined, { startTransition: startResetTransition  }); // subscribe to everything

const [searchPending, searchStartTransition] = useTransition();
const [search, setSearch] = useQueryState(
  "search"
  { startTransition: searchStartTransition }
);

const [anotherPending, anotherStartTransition] = useTransition();
const [another, setAnother] = useQueryState(
  "anotherSearchParam"
  { startTransition: anotherStartTransition }
);

setQueryStates(null); // reset everything to default value
isResetPending // can be used to show loading UI for reset action only

searchPending; anotherPending; // can be used to show loading UI for their corresponding field update action

[franky47]

Omitting/passing undefined to keyMap denote it should subscribe to all search params.

How would that work with type safety?

The strength of nuqs hooks is that they are declaratively scoped to specific search params keys, stitch updates automatically, and scale by composing them together.

Resetting all search params is a navigation: you could do so with a router call, routing to whatever usePathname is currently set to (and wrapping that in a transition):

function useResetSearchParams() {
  const pathname = usePathname()
  const router = useRouter()
  const [isPending, startTransition] = useTransition()
  const reset = useCallback(() => {
    startTransition(() => {
      // or replace, whichever makes sense
      router.push(pathname)
    })
  }, [router, pathname, startTransition])
  return [isPending, reset] as const
}

On the subject of transitions, you can specify them when calling the state updater function rather than at the hook definition, allowing you to trigger different ones from a single useQueryStates hook:

function useMultipleTransitionsDemo() {
  const [isFooPending, startFooTransition] = useTransition()
  const [isBarPending, startBarTransition] = useTransition()
  const [, setSearchParams] = useQueryStates({
    foo: parseAsString,
    bar: parseAsInteger
  })

  setSearchParams({ foo: 'a' }, { startTransition: startFooTransition })
  setSearchParams({ bar: 42 }, { startTransition: startBarTransition })
}

Edit: duplicate of #610, #684.