Issue with using `Zod v4` as a parser in `v2.7.0`

[yWilliamLima]

Context

What's your version of nuqs?

"nuqs": "2.7.0"

What framework are you using?

• Next.js (app router)

Which version of your framework are you using?

"next": "15.5.4"
"zod": "4.1.11"

Description

There is an issue with using Zod v4 as a parser, where the problem started occurring in version 2.7.0. It was working fine in version 2.6.0.

Reproduction

Use any Zod schema as a parser in a useQueryState, example:

const [test, setTest] = useQueryState('test', z.string())

Error:

No overload matches this call.
  The last overload gave the following error.
    Type 'ZodString' has no properties in common with type 'Pick<UseQueryStateOptions<string>, keyof Options>'.

[franky47]

const [test, setTest] = useQueryState('test', z.string())

This worked before? It should not have.

[yWilliamLima]

const [test, setTest] = useQueryState('test', z.string())

This worked before? It should not have.

It worked perfectly and I thought it was amazing

[franky47]

I see the issue, z.string() does expose a parse function which could pass for a nuqs parser, and happens to work in this case because the lack of a serialize function in Zod schemas falls back to serialising with .toString, which is a no-op on a string type. I don't think this would work well for other Zod schema types.

As for why this was accepted by the type system before and is no longer the case, I think this comes from the change of UseQueryStateOptions from an interface to a type in #1134, but I'm not sure why. Maybe @TkDodo (who introduced the change) can help here?

In any case, z.string() is not necessary: by default everything is a string, you opt-into using parsers when you want to convert the query string into another data type (and you need one of the parseAsXyz parsers to do so, to handle the serialisation part). You can use codecs in Zod ^4.1 to do that, with a bit of API adaptation: https://nuqs.dev/docs/parsers/community/zod-codecs

So your example could be simply:

const [test, setTest] = useQueryState('test')

[yWilliamLima]

I understand, it might have been a coincidence that it worked due to a mistake I made. I was also using it for enums:

const [test, setTest] = useQueryState('test', z.enum(['One', 'Two']))

However, now upon reviewing, I can easily resolve it this way:

const [test, setTest] = useQueryState(
  'test',
  parseAsStringEnum(z.enum(['One', 'Two']).options)
)

[TkDodo]

I think this comes from the change of UseQueryStateOptions from an interface to a type in #1134, but I'm not sure why.

It was changed because we now extend GenericParser, which is a union type (it was a regular type before), and interfaces cannot extend union types. It errors with:

TS2312: An interface can only extend an object type or intersection of object types with statically known members.

I agree that it’s unfortunate that it worked before, but as @franky47 said, it was never intended to work that way - you have to provide a parser from nuqs or create one yourself with createParser or now createMultiParser.

[franky47]

Thanks @TkDodo, the "I'm not sure why" was more related to "why does passing a Zod schema fail now that UseQueryStateOptions is a type and passed before when it was an interface".

In any case, I'm going to close this as not planned, as it was a happy accident that it worked that way before, and one that could have been problematic if trying to use with a non-trivially serialisable schema.

An example:

// for ?test=banana, state is true. it would be false for parseAsBoolean.
const [state] = useQueryState('test', z.coerce.boolean())

//  and for this one, the state is never true because `parse` is always fed a string:
useQueryState('test', z.boolean())