standard-schema support for runtime validation with Zod, Valibot, etc.

[olsio]

ky currently simply casts your result to a type but it would be very useful if you could pass a schema to properly validate the received json before returning it.

https://github.com/standard-schema/standard-schema is a specification that allows support for a large number of validation libraries without tying the project to one specific.

I imagine it will be a fight to get the types correct but there are several fetch libraries that added support and might be a good source for inspiration.

https://github.com/L-Blondy/up-fetch
https://github.com/logione/rest-client

I could work on this but I think the project team needs to tell me how the api should look like to fit the vision of ky.

[sholladay]

Questions that come to mind for me:

• Where do we put this in the request lifecycle? Sometimes hooks are used to override the response. So should validation happen before or after our existing hooks? I'm thinking after, so hooks could still run their own validation on the original response and/or maybe modify the schema. Either way, we should probably add hooks related to validation.
• Should the schema itself be allowed to modify the data? In joi, this would be the difference between joi.assert() and joi.attempt(). I usually find myself using joi.attempt(), as the schema is a convenient place to normalize the data. Does Standard Schema provide for both approaches?
• Which pieces of the response should be validated against the schema? Only the body? What about headers?
• Should this only be allowed in ky().json() calls? Regular ky() does not parse the body and thus wouldn't be able to validate the body. Unless maybe we return a KyResponse with custom body methods that do perform validation when the user calls them.

[olsio]

Good questions.

My understanding for standardschema is that it is just for validation not transformation so that would still need to be done via hook or on the result itself.

In terms of lifecycle I agree it should be with the json() call after everything. My assumption was the validation would only run on the resulting Json not sure if there are header use cases.

So this would become equivalent but throw any exception for failed validation.

import z from 'zod'

ky.get('/foo').json<string[]>()
ky.get('/foo').json(z.array(z.string()))

[sholladay]

If I understand the spec correctly, it looks like the validate() function is allowed to transform the result and it's up to the validation library whether that happens or not. In joi's case, you can toggle that on or off in the schema itself. So this should work nicely for those who want to do type coercion or other transformations.

[LinusU]

Is this just syntactic sugar to write:

await ky.get('/foo').json(schema)

instead of:

schema.parse(await ky.get('/foo').json())

?

I my team, we use Zod a lot, specifically together with Ky, and we just use the latter code.

The thing I like about Ky is that it's very light weight. Not saying that adding this specific feature would make it "heavy" instead of "light". But I feel like this and the cookieJar proposal is adding things that could just as easily live outside this package, without a significant impact to usability. Just my 2 cents ☺️

[olsio]

That is true but this could be added without any dependencies. But I also have the feeling that we cannot simply add an optional schema as it will conflict with the generic type passed to json()

And if that would require a new method like jsonWithSchema() I don't think it would be worth it. I just don't know enough about typescript types to know what is possible.

[sholladay]

I decided to close the cookie jar issue until Node figures out what it wants to do regarding cookies. It's a valid but niche use case that should be coordinated upstream.

Response schema validation, on the other hand, would be something that, ideally, most people would use, and probably will never be upstream.

As for what's possible here: We won't need any new methods. You'll just pass your schema as an option and then infer the schema's type to provide the generic. Should be relatively simple.