v.optional output type is broken

[sbking]

I believe this bug was introduced in v1.0.0-beta.3. When wrapping a transform schema in v.optional with a default value, the inferred output type is now a union including the type of the default value. However, at runtime the default value is still parsed through the transform schema.

Tricky to explain, so here is a playground example.

The schema will always return a number, but now TypeScript says it will return number | "10"

[sbking]

As a sidenote, the behavior of v.optional is a bit confusing and not explained well in the docs. I would expect the default value to be the output type of the transform schema (or any arbitrary type and then return it unmodified with a union output type), but instead what valibot seems to do is expect the input type of the transform schema and then pass it through the wrapped transform schema.

Either way, the TypeScript types are incorrect because it expects TDefault to be assignable to the input type of the wrapped schema, but then still has TDefault as one of the union options of the overall output.

[fabian-hiller]

Thank you for reaching out! You are right! I am very sorry. I will fix this and add tests to make sure this cannot happen again.

optional allows you to define a default input to be used when the input is undefined. The behaviour you describe with the output as the "default" is similar to our fallback method.

[fabian-hiller]

Fixed 😎

[fabian-hiller]

What information do you miss in the docs? I am happy to improve it. Here is our guide and API reference:

• https://valibot.dev/guides/optionals/#default-values
• https://valibot.dev/api/optional/

[sbking]

@fabian-hiller Thank you!

This is what I found confusing about the docs:

With optional the validation of your schema will pass undefined inputs, and if you specify a default_ input value, the schema will use it if the input is undefined. For this reason, the output type may differ from the input type of the schema.

I think I now understand that this is saying, "if you do not provide a default value, the input type of the schema will expand to also allow undefined".

But the way I read it was, "if you do provide a default value, the output type of the schema will expand to include the default value's type, since the default value will be returned directly as output if the input is undefined".

[fabian-hiller]

Thank you. I will have another look at the docs at the end of the year to see if we can improve the explanation.