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:

• feat: create coercion actions for primitives (and date) #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]

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

[Copilot]

Pull Request Overview

This PR adds a new stringbool action that converts string values to boolean values based on configurable truthy and falsy string lists. The implementation is inspired by Zod's string-to-boolean coercion functionality and provides case-sensitive/insensitive matching options.

• Implements string-to-boolean transformation with customizable truthy/falsy values
• Provides case sensitivity control with default insensitive matching
• Includes comprehensive test coverage for all configuration options

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
library/src/actions/stringbool/stringbool.ts	Core implementation of the stringbool action with options interface and transformation logic
library/src/actions/stringbool/stringbool.test.ts	Comprehensive test suite covering default options, custom configurations, and error cases
library/src/actions/stringbool/stringbool.test-d.ts	TypeScript type tests ensuring correct type inference for inputs, outputs, and issues
library/src/actions/stringbool/index.ts	Export module for the stringbool action
library/src/actions/index.ts	Adds stringbool to the main actions export
website/src/routes/api/menu.md	Updates API documentation menu to include stringbool entries
website/src/routes/api/(actions)/stringbool/index.mdx	API documentation for the stringbool action with usage examples
website/src/routes/api/(types)/StringboolAction/index.mdx	Documentation for the StringboolAction type interface
website/src/routes/api/(types)/StringboolIssue/index.mdx	Documentation for the StringboolIssue type interface
website/src/routes/api/(types)/StringboolOptions/index.mdx	Documentation for the StringboolOptions type interface

[pkg-pr-new]

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.