docs: add info about zod 4

[niba]

Add a note about zod 4. I think that at some point we can rewrite the entire doc about search-params because adapter becomes a special case only for zod 3

related: #4442

[schiller-manuel]

"native TanStack Router support" sounds a bit weird.

[niba]

true, maybe

"Zod v4.0.6 or higher is recommended for proper type inference"?

[KiwiKilian]

I think it would be great to have a few words on the difference of .default() and .default().catch().

Also, when the default is used already twice, should we recommend the pattern from the search middlewares of using an defaultValues object?

[niba]

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

I follow the same style as used in the rest of the adapters. I think that the choice about using defaultValues belongs to the developer and is not important here, especially since the values that you put into default and catch are checked by TypeScript

[LargatSeif]

in case you want to include any zod/v4-mini examples :
catch:

validateSearch:z.object({
    redirectTo: z.catch(z.string(), "")
})

default:

validateSearch:z.object({
    redirectTo: z.catch(z._default(z.string(), ""), ""),
})

[KiwiKilian]

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

But it doesn't explain why one would use default and catch on the some line which was quite confusing to me in the beginning.

[KiwiKilian]

While using the defaultValues is absolutely optional here, it's a required pattern for the search middleware default stripping to allow instance comparison. So I would think this would make the docs more aligned in recommending that patter subtly, but it's true other parts of the docs also don't use it.

[niba]

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

But it doesn't explain why one would use default and catch on the some line which was quite confusing to me in the beginning.

You’re right. I’ll add explanation. In general, it’s tricky because ⁠.catch() normally behaves like ⁠.default(), but its behaviour changes when you combine it with ⁠.optional(). It also produces a different type, since ⁠.default() makes the field optional.

[niba]

While using the defaultValues is absolutely optional here, it's a required pattern for the search middleware default stripping to allow instance comparison. So I would think this would make the docs more aligned in recommending that patter subtly, but it's true other parts of the docs also don't use it.

I can change all the examples to use defaultValues everywhere, I don't have a strong opinion about it

[KiwiKilian]

This should be more relaxed, as Zod v4 is now the opposite? Like "For some validation libraries..."?

[niba]

To be honest, I don’t understand the Adapters section. What are we trying to say here? I also tested the example in that section and it isn’t true. ⁠Link doesn’t require ⁠search to be defined, because all fields are optional (tested with Zod v3). Moreover, we already covered transforming search params with ⁠.default() in the previous section so I don't know why we write it like introduction to this topic.

So I think we should rewrite it or remove it, especially right now that we use the adapter only in Zod 3.

[KiwiKilian]

the docs earlier on this page explain when to use ⁠default and when to use ⁠catch.

But it doesn't explain why one would use default and catch on the some line which was quite confusing to me in the beginning.

[KiwiKilian]

While using the defaultValues is absolutely optional here, it's a required pattern for the search middleware default stripping to allow instance comparison. So I would think this would make the docs more aligned in recommending that patter subtly, but it's true other parts of the docs also don't use it.