feat: Callback to process merged URLSearchParams on update

[franky47]

Let's move the discussion from #1066 here.

The idea is to introduce a callback as an adapter prop that will be called after the URLSearchParams have been merged:

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

Lines 177 to 183 in 97390a5

	for (const [key, value] of items) {
	if (value === null) {
	search.delete(key)
	} else {
	search.set(key, value)
	}
	}

It should run before the URLSearchParams object is sent to the adapter for updating the URL.

This can be used to implement a few interesting behaviours:

• Sorting the search params in some way (eg: alphabetically by key)
• Injecting / removing values
• Other kinds of processing

Example API:

<NuqsAdapter 
  processUrlSearchParams={(search) => {
    const entries = Array.from(params.entries())
    entries.sort(([a], [b]) => a.localeCompare(b))
    return new URLSearchParams(entries)
  }}
>
  { children }
</NuqsAdapter>

Message history

(like a callback function to process URLSearchParams after applying updates for alphabetical sorting).

Is this feature planned? We're definitely looking for this feature specifically. (alphabetical sorting of parameters)
Edit: or a callback where we can do it ourselves.

Originally posted by @Multiply in #1066 (comment)

---

@Multiply would you like to try your hand at a PR?

Was already looking into the recent introduction of global default config.
Do you have a preference for where the middleware should be called?

Originally posted by @Multiply in #1066 (comment)

Related discussions

• Sorting of query string keys #634
• Maintain URL Parameter Order #777
• Is it possible to sort search params alphabetically with Nuqs? #1053

[Multiply]

I have a functional prototype now, but I am not sure the prop drilling I have going on is desired: #1110

[franky47]

That looks good, unfortunately since the throttle queue lives outside of the React context, prop drilling is the only way to get the callback there.

Could you add some unit tests please? And it should be good for a preview build.

[Multiply]

2 simple tests have been added.

[Multiply]

Should it be an option instead, so we get per useQueryStates middleware support?

[franky47]

Should it be an option instead, so we get per useQueryStates middleware support?

That would require a way to combine them like the other options, which may not be trivial (override vs compose, with order of arrival in the queue being a factor). Plus since it applies at the global update level, having one hook sort keys alphabetically and another not doing so would be very head-scratching for users and devs alike.

[Multiply]

I've also added a test for useQueryStates now.

[github-actions]

🎉 This issue has been resolved in version 2.6.0-beta.2 🎉

The release is available on:

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

Your semantic-release bot 📦🚀