[RFC] Zod integration

[franky47]

Draft PR: #448.

There's been a few requests for using Zod to validate parsed search params, both on the server and on the client.

This makes a lot of sense since:

1. Only basic validation is currently provided in the built-in parsers
2. Implementing custom parsers just to check that a number is in a particular range is not a great DX
3. Zod is popular and likely to already be present in the stack

A proposition is to add a new method to the parsers builder API, withValidation, that takes in a Zod schema .parse function:

const emailParser = parseAsString.withValidation(z.string().email().parse)
const posIntParser = parseAsInteger.withValidation(z.number().int().positive().parse)
// Works with compound parsers:
const arrayParser = parseAsArrayOf(parseAsString)
  .withValidation(z.array(z.union([z.literal('foo'), z.literal('bar')])).parse)
// or validate on each item:
const arrayParser = parseAsArrayOf(parseAsString
  .withValidation(z.union([z.literal('foo'), z.literal('bar')]).parse)
)

Since errors thrown in parsers result in null or the default value (if specified) being returned, this should work and would not actually introduce a peer dependency on Zod. It would accept any function that takes in an unknown argument and returns the parser output type. Technically we'd only call the validator if the query value has successfully been parsed / deserialized from a string, so T would also be a suitable input type for the validator.

Why not use Zod directly in place of parsers ?

Zod can behave like the parse method: take a string, hydrate it into a JS data type, and run some validation on top while doing so.

However, it does not provide the counterpart serialization function to transform that JS data type back into a string, which is necessary on query state updates.

Also, it would require all Zod schema definitions to be rooted in z.string().transform(s => whatever), which is not what existing application logic would define (schema definitions are likely to be reused or derived from domain-specific definitions).

Caveats & Limitations

Validation needs to happen synchronously. This is because the parsing + validation is done in each hook's internal state initialisation, (getting the correct value from the URL on mount), which must return a value synchronously.

Questions

1. Should the validation run on writes as well as reads ? Ie: should this fail:

const [positive, setPositive] = useQueryState(
  'pos',
  parseAsInteger.withValidation(z.number().positive().parse)
)

setPositive(-1) // Should this fail?

2. Should multiple calls to withValidation compose validations or reset them? Eg:

const dice = parseAsInteger
  .withValidation(z.number().gte(1).parse)
  .withValidation(z.number().lte(6).parse)

// What should be the result for trying to parse "0" here?
// - if compose validations, then `null`
// - if overriden, then `0`

[Talent30]

Is it possible to make this feature support multiple validators via TypeSchema?

[franky47]

I was going to say yes, by currying the schema into the assert function, but I just noticed that the output is a Promise, and validation needs to run synchronously here.

Edit: I added a caveat section to emphasize this, thanks for pointing it out!

[Talent30]

The reason I propose this is that soon people will be asking, 'Can you support X lib as the validator?

We can consider this options again once the author adds synchronous validation.

[franky47]

Some of the underlying validation libraries use async validation by default (Yup being the most popular one). Not much we can do there.

For any other synchronous APIs, as long as it conforms to the validator: (input: unknown) => T type, and throws on invalid inputs, it should work just fine.

[franky47]

I added some questions that are currently left open for discussion, and a draft PR.

[Talent30]

Re:questions

1. It should fail
2. Compose- changed my mind, I second allow only one

[tordans]

1: read+write
2: allow only one .withValidation and side step the issue.

General: i like the feature.

Curious: Did you compare this with how Tanstack Router ensures value safety?

[franky47]

I have yet to dive into the TanStack router, but from the preview I saw it looks super interesting.

I'd love to provide a similar DX with nuqs, though that would mean tighter integration with Next.js APIs (Link & router), and a way to scan the project for search param definitions to codegen the type-safety.

[franky47]

I'm exploring an alternative API: adding the validation method as an option.

const diceSchema = z.number().integer().min(1).max(6);

const [dice, roll] = useQueryState(
  'dice',
  parseAsInteger.withOptions({
    validate: diceSchema.parse
  })
)

It might not make much difference, but passing it this way allows for a few things:

1. We can use it for validating writes
2. It can also be used on the server cache
3. It solves the open question of compose vs override, by following the same pattern as other options (override).

One issue with this approach is that it makes the Option type generic over the data type, which we could consider a breaking change since it's exported. Though I doubt many people actually import it as-is, and instead infer usage from the hooks API (which does not change). So if going this way I'd be down to mark this as a minor update, with an explicit mention in the release notes.

[sp88011]

With this feature, would it be possible to pass an entire zod object to useQueryStates to initialize the keys, or is this intentionally not the way to go?

Passing an entire zod object would help with reusability because you probably use that same zod elsewhere (e.g. to validate function params). A practical example would be using one zod object to capture every param (pagination, column filters, sort, ...) for a (tanstack) table.

const tableParams = z.object({
page: z.coerce
    .number()
    .transform((v) => v - 1)
    .pipe(z.number().min(0))
    .catch(0),
    
  size: z.coerce
    .number()
    .transform((v) => v.toString())
    .pipe(z.enum(["10", "20", "50", "100"]))
    .transform((v) => Number(v))
    .catch(10),
  
  query: z.string().optional(),
   
   //... etc
   
   })
   
   
   const [tableState, setTableState] = useQueryStates({...parseAsJson.(tableParams.parse}) //something like this?
   

[franky47]

Zod schemas on their own lack the reverse transformation to turn the data type back into a string when writing to the URL, so they can only be used as runtime validators, not serializers/deserializers.

[MartinCura]

In working on this feature, would it benefit to accept any validation library which follows the new Standard Schema spec?

[franky47]

That would be nice, yes. Maybe the parsers should also conform to this standard.

The main issue with validation at the moment is that it should also run on updates (not just when parsing), and therefore updates would have to have some sort of error handling mechanism.