feat: Add processUrlSearchParams middleware as adapter prop

[Multiply]

• Add tests
• Add docs
• Add test to verify that useQueryStates picks up a callback change

Closes #1109.

[vercel]

@Multiply is attempting to deploy a commit to the 47ng Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
nuqs	Ready	Preview	Comment	Sep 1, 2025 8:13pm

[franky47]

There are some linting errors, is your Prettier not set to format on save?

[Multiply]

I generally don't use prettier in my own projects, but I've run it now. 🚀

[pkg-pr-new]

pnpm add https://pkg.pr.new/nuqs@1110

commit: 9221815

[franky47]

LGTM, thanks! I'll add a section in the docs (we could also have a demo component for this 👀)

[Multiply]

LGTM, thanks! I'll add a section in the docs (we could also have a demo component for this 👀)

If you can give some pointers, I can add it when I get home, later tonight.

[franky47]

I was thinking of reusing the same technique I used in the nuqs-2.5 blog post (for the key isolation demo): wrapping a part of the tree with the React SPA adapter, to scope the effect to search params updates happening in its children.

Location-wise, it would probably be best to add a new heading to the options page ("Adapter props"), have the defaultOptions live in there too, and showcase the alphabetical sorting as both a code block for copy-paste and a demo.

The demo could have three buttons updating counters in keys "a", "b", and "c", with a toggle to enable/disable the sorting (ie: switching the processUrlSearchParams between actual sorting and a no-op). Which makes me realise the state updater function's useCallback might need to have processUrlSearchParams in its dependency array for proper tracking.

[Multiply]

@franky47 most likely not exactly as you requested, but I hope it's a good starting point.

[franky47]

Looks good, thanks! I'll do some minor wording tweaks and this should be good to merge.

[Multiply]

Looks good, thanks! I'll do some minor wording tweaks and this should be good to merge.

Let me know if you need anything else. Happy to test the final changes in our project.
Thanks. :)

[franky47]

Feel free to try the pkg.pr.new link in your app, I added reactivity for a change in the callback in useQueryStates, just need to find a clean way to test that.

[Multiply]

Feel free to try the pkg.pr.new link in your app, I added reactivity for a change in the callback in useQueryStates, just need to find a clean way to test that.

I don't have a need for the reactivity bit, but it definitely works as is, if it's static at least.

[Copilot]

Pull Request Overview

This PR adds support for processing URL search parameters through a middleware function. The feature allows users to provide a callback that modifies the URLSearchParams before they are sent to the adapter for URL updates.

• Introduces processUrlSearchParams prop to adapters for transforming search parameters
• Updates the throttle queue system to accept and apply the processing function
• Adds comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
turbo.json	Increases build concurrency to 11
packages/nuqs/src/useQueryStates.ts	Integrates processUrlSearchParams from adapter context
packages/nuqs/src/useQueryStates.test.ts	Adds tests for the new search params processing feature
packages/nuqs/src/lib/queues/throttle.ts	Updates queue to accept and apply processUrlSearchParams callback
packages/nuqs/src/lib/queues/throttle.test.ts	Adds unit tests for throttle queue processing functionality
packages/nuqs/src/adapters/testing.ts	Adds processUrlSearchParams support to testing adapter
packages/nuqs/src/adapters/lib/context.ts	Defines processUrlSearchParams in adapter context and exports hook
packages/docs/content/docs/options.mdx	Documents the new processUrlSearchParams feature with examples
packages/docs/content/docs/options.client.tsx	Provides interactive demos for the documentation

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[franky47]

Thanks for your help! I have a few things I need to work on before this lands in 2.6.0 (likely by the end of the week).

[github-actions]

🎉 This PR is included in version 2.6.0-beta.2 🎉

The release is available on:

• npm package (@beta dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[hugotiger]

Was it considered to recommend the usage of the native sort() function on URLSearchParams?

Something along the lines of:

Suggested change

	processUrlSearchParams={(search) => {
	const entries = Array.from(search.entries())
	entries.sort(([a], [b]) => a.localeCompare(b))
	return new URLSearchParams(entries)
	}}
	processUrlSearchParams={(search) => {
	const clone = new URLSearchParams(search)
	clone.sort()
	return clone
	}}

Whilst it isn't the exact same sorting algorithm, I was thinking maybe it'd be preferable to recommend following the standard by default!

I can update the docs if you agree 😄

[Multiply]

If we don't care about immutability, simply call search.sort() and returning search directly could also do.

[franky47]

Imagine building an entire library around URLSearchParams and only discovering the .sort function now 😅

Yes standards would be better to advertise in the docs. It's a shame it doesn't return itself though, that could have been a one-liner.

[Multiply]

#1113