perf: bail out of state updates for equal values

[TkDodo]

When useQueryStates receives an event that should update its internal state. we should bail out of that update if we already store the same value.

This is what React’s useState does per default (by comparing with Object.is), however, it doesn’t work to delegate this to React because the internal state of useQueryStates is an object. When an event comes in, we only update a single value of that object:

stateRef.current = {
  ...stateRef.current,
  [stateKey as keyof KeyMap]: state ?? defaultValue ?? null
}

so we can optimize ourselves by comparing the current state for that key with the new state that comes in from the emit and skip calling setInternalState for those cases.

---

This perf fix will be helpful for the writeDefaults feature:

• feat: writeDefaults #1159

because writing the default value to the url upon rendering should not trigger another render, as the states are already equal.

[vercel]

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

A member of the Team first needs to authorize it.

[pkg-pr-new]

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

commit: 5976fb4

[franky47]

Could this be a solution to #924 (comment) ?

[TkDodo]

Could this be a solution to #924 (comment) ?

Hm, I don't think so. The bailout happens later, only for setting component state. And with clearOnDefault: false, we might actually need to write to the url even though we set to the same value in state if it's equal to the default.

[TkDodo]

@franky47 do you know what I can do against the react-router v7 test failure? I think this is a shared test, but it seems that we have one fewer re-renders now (which is a good thing)

[franky47]

I'll run it again, the render test can be flaky sometimes, I don't like it but it has been useful in detecting major re-render changes in the past.

[TkDodo]

I also need to add another test that calls setState(v => v) to confirm the behaviour compared to main

[franky47]

The one change I see that could happen here is that a setState(v => v, { shallow: false }) could have been used before to refresh server-side data, but there might be better (more explicit) ways to do this in userland.

[TkDodo]

I actually messed up the last refactoring and the test showed it 🎉

Should be good now: f17fe59

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
nuqs	Ready	Preview	Comment	Oct 6, 2025 2:21pm

[franky47]

I think there was a place in the docs or the playground (need to dig) where I explored a pattern to collect state changes locally, without updating the URL (to avoid polluting the global history), and submit all in one go by using this setState(v => v) trick.

To be fair, the throttleMs: Infinity trick to disengage the URL update is likely to cause some more issues with writeDefaults, and the pattern described above is a form, really. #UseThePlatform

[TkDodo]

hmm I 'm not seeing that anywhere 🤔

[franky47]

Found it, it's the deferred test in the e2e-next environment (which could be a shared one), and it still passes apparently:
https://github.com/47ng/nuqs/blob/next/packages/e2e/next/src/app/app/deferred/page.tsx

[github-actions]

🎉 This PR is included in version 2.7.1 🎉

The release is available on:

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

Your semantic-release bot 📦🚀