feat: multi-parsers

[TkDodo]

note: Description by @franky47

MultiParsers allow key repetition in the URL.

E.g.: with the built-in parseAsNativeArrayOf:

const [state] = useQueryState('key', parseAsNativeArrayOf(parseAsInteger))
// url:   /?key=1&key=2&key=3
// state: [1, 2, 3]

Creating custom multi-parsers allow reducing the array of query values into more complex objects:

// /?kv=foo:bar&kv=baz:qux
{
  foo: 'bar',
  baz: 'qux'
}

[vercel]

@TkDodo 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 26, 2025 9:05pm

[TkDodo]

size-limit fails, and this runs right after build, so before any tests are running or even type-checking is done. I don’t think that’s the best workflow. yes size-check is important and should block a merge, but not tests from running 😅

[franky47]

Yeah I agree, feel free to bump it high enough (in nuqs' package.json) for it to pass and I'll see how to move it cleanly to another step (the docs build needs the actual size to display it on the landing page).

[TkDodo]

I’ve increased the relevant size-limit for now a bit:

db3c11e

[TkDodo]

cachedQueries now contain Iterable<string>, so we can’t really compare them with triple equals.

I’m wondering why the eq method of the parser isn’t used for comparison here?

But, we could also extract this “shallow equals” array comparison to a shared util:

nuqs/packages/nuqs/src/parsers.ts

Lines 484 to 492 in e8af136

	eq(a, b) {
	if (a === b) {
	return true // Referentially stable
	}
	if (a.length !== b.length) {
	return false
	}
	return a.every((value, index) => itemEq(value, b[index]!))
	}

[franky47]

I’m wondering why the eq method of the parser isn’t used for comparison here?

We're comparing serialised versions here (the eq function compares state types), so yeah we'd likely have to branch for string comparison with === vs array comparison for iterables.

[TkDodo]

I looked into this a bit more, but I’m a bit confused which types get stored where:

const query =
  queuedQuery === undefined
    ? parser.type === 'multi'
      ? (searchParams?.getAll(urlKey) ?? [])
      : (searchParams?.get(urlKey) ?? null)
   : queuedQuery

now when we read the Query from the searchParams, it can only be string | null | Array<string> - I’ve extracted that to its own type:

export type SearchParamQuery = string | Array<string>

but when I look at queuedQuery, it seems that we store whatever parser.serialize has returned, which used to only be strings, but now it can be Iterable<string>, so I’ve also made type for that:

export type SerializedQuery = string | Iterable<string>

now when trying to compare the two:

compareQuery(cachedQuery[urlKey] ?? null, query)

cachedQuery contains a SerializedQuery, and query can contain that too when we get it from queuedQuery, but if we read it directly from the searchParams, it will be a SearchParamQuery.

I don’t see how we could effectively compare the result of searchParams.getAll() with the result of a serialized Query, so maybe we need to run that trough parser.serialize before?

[franky47]

I see, if .getAll() returns a Array<string>, that is already an Iterable<string>, so maybe we could have a comparison function dedicated to serialised representations (either read from the URL or serialised before an update)

so maybe we need to run that trough parser.serialize before?

The input of serialize being a state ("hydrated"/deserialised) data type, that wouldn't work, what we get from searchParams.get{,All}() is already in a serialised form.

The issue might be from the ?? null part in cachedQuery[urlKey] ?? null, as this makes sense for a single parser, but not much for a multi one (where we'd default to an empty array).

[TkDodo]

so maybe we could have a comparison function dedicated to serialised representations (either read from the URL or serialised before an update)

yeah can try that.

The issue might be from the ?? null

does it even make sense to call the comparison function if cachedQuery[urlKey] doesn’t exist? this would never yield a cache hit imo...

[TkDodo]

untested, but here is an attempt at that:

e0021b1

[franky47]

One thing to look out for with cached queries is that null and undefined have different meanings: undefined means there is no cache in memory, but null here means we requested to remove that key from the URL when setting the state.

If you have suggestions for a better internal way of encoding these intents, I'm very much open to suggestions (maybe symbols?)

[TkDodo]

yeah I kept that intent the same now (I think), and only fallback to ?? defaultValue instead of ?? null, where defaultValue = parser.type === 'multi' ? [] : null

[TkDodo]

but note that ?? will use the fallback for both null and undefined, so I’m not sure if that differentiation between null and undefined was there before in all places 🤔

[TkDodo]

As I was trying to add some end-to-end tests, I’m stumbling over some issues I’m not quite sure how to fix / debug:

1. when multi-parsers are used, it would be great if useQueryState wouldn’t yield null, but always empty array instead. With searchParams.getAll(), it’s not possible to get null back.

I can see that parseAsArray also returns Array<T> | null so maybe that’s fine for multi parsers too, but I think when working with arrays, null is a bit annoying.

2. I’m not quite sure as to why yet, but when calling setState([1, 2]) the url updates correctly but the state in the component reverts back to what it was from before the state update. It’s like it’s lagging behind or immediately gets re-set. Just leaving this here in case this sounds familiar to you :) I can commit the failing e2e test if you like.

[franky47]

I think when working with arrays, null is a bit annoying.

I agree, in a lot of cases .withDefault([]) makes it easier. There have been cases where having a non-empty array as a default made sense for the domain, but then the URL would contain ?key= for the empty array case, which is ugly and counter-intuitive (same as parseAsBoolean.withDefault(true))

[TkDodo]

react-router v7 seems to fail because of this key isolation that does a !== check directly on searchParams.get:

nuqs/packages/nuqs/src/adapters/lib/key-isolation.ts

Line 12 in 4897248

: keys.some(key => oldValue.get(key) !== newValue.get(key))

not sure if we can switch this conditionally to getAll because there’s no parser available anywhere 🤔

[franky47]

@TkDodo I added utilities to test bijectivity of custom multi-parsers. The overloads should take care of retro-compatibility, but if you see some issue, let me know.

[franky47]

LGTM, go for beta! 🚀

[github-actions]

🎉 This PR is included in version 2.7.0-beta.1 🎉

The release is available on:

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

Your semantic-release bot 📦🚀

[github-actions]

🎉 This PR is included in version 2.7.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀