Valibot
OfficialBetav0.1.0@kubb/plugin-valibot
Options
Pass these options to pluginValibot(). Shared options link to Shared plugin options.
Options overview
| Option | Purpose | Default |
|---|---|---|
output | Where files are written. | { path: 'valibot', barrel: { type: 'named' } } |
group | Split output by tag or path. | None |
importPath | Module the generated files import v from. | 'valibot' |
inferred | Export a type next to each schema. | false |
coercion | Convert input before validation. | false |
coercion.strings | Convert a string with v.toString(). | false |
coercion.numbers | Convert a number and an integer with v.toNumber(). | false |
coercion.dates | Convert a Date field of a response with v.toDate(). | false |
typeGuards | Generate is* type guards and assert* assertions. | false |
typeGuards.is | Generate the is* type guard. | true |
typeGuards.assert | Generate the assert* function. | true |
regexType | How an OpenAPI pattern is written. | 'literal' |
oneOfType | How a oneOf without a discriminator is validated. | 'union' |
printer | Replace the handler for a schema type. | None |
include | Keep only operations and schemas that match. | None |
exclude | Skip operations and schemas that match. | [] |
override | Apply different options per pattern. | [] |
resolver | Customize generated names and file paths. See resolver members. | resolverValibot |
macros | Rewrite AST nodes before printing. | [] |
Option details
importPath
Module the generated files import v from, such as your own module that re-exports Valibot.
| Type | string |
| Required | false |
| Default | 'valibot' |
The module is imported as import * as v, so it must export every Valibot function the schemas call.
inferred
Exports a type next to each schema, so you do not need @kubb/plugin-ts.
| Type | boolean |
| Required | false |
| Default | false |
export type PetSchemaType = v.InferOutput<typeof petSchema>A request schema, such as a request body or a query schema, gets v.InferInput, which is the value the caller passes. Every other schema gets v.InferOutput. The two differ for a schema that converts, such as a Date field or a default.
A schema that is part of a circular reference is annotated as v.GenericSchema, so its inferred type is unknown. Add @kubb/plugin-ts when you need the types of those schemas.
coercion
Converts input before validation, so a query string such as '5' passes an integer schema.
| Type | boolean | { dates?: boolean; strings?: boolean; numbers?: boolean } |
| Required | false |
| Default | false |
v.pipe(v.unknown(), v.toString()) for a string.v.pipe(v.unknown(), v.toNumber()) for a number and an integer.v.pipe(v.unknown(), v.toDate()) for a response field that is a Date. This needs dateType: 'date' on the adapter.true turns on all three. An integer with format: int64 converts with or without this option, because JSON holds a number or a string.
typeGuards
Generates an is* type guard and an assert* function for every component schema.
| Type | boolean | { is?: boolean; assert?: boolean } |
| Required | false |
| Default | false |
export const isPet = (data: unknown): data is v.InferInput<typeof petSchema> => v.is(petSchema, data)
export function assertPet(data: unknown): asserts data is v.InferInput<typeof petSchema> {
v.assert(petSchema, data)
}Both narrow to v.InferInput, the value the schema accepts before it converts anything.
regexType
How an OpenAPI pattern is written inside v.regex(...). Use 'constructor' when a regex literal breaks your build or you need a string pattern.
| Type | 'literal' | 'constructor' |
| Required | false |
| Default | 'literal' |
v.regex(/^[a-z]+$/).v.regex(new RegExp("^[a-z]+$")).oneOfType
How a oneOf without a discriminator is validated. Use 'xor' when values may carry extra keys.
| Type | 'union' | 'xor' |
| Required | false |
| Default | 'union' |
v.union([...]) with strict object members, so extra keys fail, even keys the spec allows.v.union([...]) behind a v.check that passes only when exactly one member matches.printer
Replaces the handler for a schema type such as 'date'. Each handler returns the Valibot expression as a string. this.base(node) returns the built-in output, and this.transform(node) recurses into nested nodes. See the printer guide.
| Type | { nodes?: PrinterValibotNodes } |
| Required | false |
import { pluginValibot } from '@kubb/plugin-valibot'
pluginValibot({
printer: {
nodes: {
date() {
return 'v.pipe(v.string(), v.isoDate(), v.transform((value) => new Date(value)))'
},
},
},
})Resolver members
Besides the shared members of resolver, resolverValibot has these. Members you leave out keep the default.
type ResolverValibotPatch = {
schema?: {
typeName?(name: string): string
type?(name: string): string
inputName?(name: string): string
inputTypeName?(name: string): string
isName?(name: string): string
assertName?(name: string): string
}
param?: {
name?(node: OperationNode, param: ParameterNode): string
path?(node: OperationNode, param: ParameterNode): string
query?(node: OperationNode, param: ParameterNode): string
headers?(node: OperationNode, param: ParameterNode): string
cookies?(node: OperationNode, param: ParameterNode): string
}
response?: {
status?(node: OperationNode, statusCode: StatusCode): string
headers?(node: OperationNode, statusCode: StatusCode): string
body?(node: OperationNode): string
responses?(node: OperationNode): string
response?(node: OperationNode): string
error?(node: OperationNode): string
options?(node: OperationNode): string
}
}Format and type mappings
Kubb maps each OpenAPI format to its Valibot call, such as format: email to v.pipe(v.string(), v.email()). See Valibot schemas for OpenAPI formats.
