feat: add `stringbool` action

[alexilyaev]

Resolves #1240

Reference

Mostly inspired by Zod’s implementation:

• https://github.com/colinhacks/zod/blob/v4.0.5/packages/zod/src/v4/core/api.ts#L1491
• https://github.com/colinhacks/zod/blob/v4.0.5/packages/zod/src/v4/classic/tests/stringbool.test.ts

Also referenced the upcoming Valibot actions:

• https://github.com/fabian-hiller/valibot/pull/1212

Open Questions

Should it be named stringbool?

• Some of the new actions are named toSomething
• Would be nice to keep the same name for an easier discovery and transition from Zod to Valibot

Should it accept a message?

• What’s the criteria for deciding that?
• Some actions accept a custom message and some don't

Do we have integration tests between a schema and an action?

• This action should only be used with a certain schema (v.string() currently)

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Comments	Updated (UTC)
valibot	Ready	Preview	Comment	Aug 22, 2025 6:42pm

[pkg-pr-new[bot]]

Open in StackBlitz

npm i https://pkg.pr.new/valibot@1251

commit: c4b52e9

[fabian-hiller]

In Zod z.stringbool() does multiple things. It validates the input data and transforms in to a boolean if possible. In Valibot we separate these things between schemas and actions and pipe them together. As you pointed out v.stringbool() seems like a bad name as it is unclear what it is doing. A Valibot user would probably expect that it validates whether a string is 'true' | 'false' | 'yes' | 'no' | … but a transformation seems unexpected as we usually use words that describe the transformation in the name and v.stringbool() does not really do that. Better would be a name like parseBoolean or toBooleanFlag. What do you think?

[alexilyaev]

In Zod z.stringbool() does multiple things. It validates the input data and transforms in to a boolean if possible. In Valibot we separate these things between schemas and actions and pipe them together. As you pointed out v.stringbool() seems like a bad name as it is unclear what it is doing. A Valibot user would probably expect that it validates whether a string is 'true' | 'false' | 'yes' | 'no' | … but a transformation seems unexpected as we usually use words that describe the transformation in the name and v.stringbool() does not really do that. Better would be a name like parseBoolean or toBooleanFlag. What do you think?

I'm not sure what's the best API for this. As a schema, validating that a value is a "boolish" string is very similar to an enum or a picklist. But then when we want to transform it to a boolean, we have a special definition for truthy or falsy values. So, what would we expect to see in the usage?

From a developer perspective, I'd like something short and clean, like:

pipe(stringbool(), toBoolean())

• This would tell me I'm validating a string that represents boolean like values
• And that I want the end value as actual boolean
• Would also be easy to find coming from Zod
• But how would toBoolean know what to do in this case?

As for the other suggestions:

• parseBoolean does not align with the naming of the new transformation actions, and confuses with .parse().
• toBooleanFlag could be fine, but technically the output is only boolean, "flag" represents the input, not output.