valibotx

A collection of extensions for valibot.

valibot maintainers tend to keep the valibot core to the minimum and sometimes refuse to accept non-essential contributions, as explained here.

valibotx re-exports valibot and adds a set of non-obtrusive extensions. Due to how valibot is organized, this is still perfectly tree-shakeable.

• valibot <0.31: valibotx 1
• valibot >=0.31: valibotx 2

Install

npm install valibot valibotx

Use

Simply import valibotx instead of valibot and enjoy both the original and the new methods:

import * as v from "valibotx"

const integerSchema = v.integerNumber([v.minValue(100)])

Schemas

integerNumber

Validate integer number.

naturalNumber

Validate natural number (positive integer).

Parse data

safeParseOutput

Shortcut for safeParse().output. Returns undefined for failed parse.

Alias: tryParse.

Actions

safeUrl

An extension of url() that only allows "safe" URLs by limiting protocols and possibly hostnames. Prevent javascript:alert('pwn3d') and other malicious URLs.

Usage:

// Allow any https:// URL.
v.pipe(v.string(), v.safeUrl())

// Allow http and https links to Twitter.
v.pipe(v.string(), v.safeUrl({
  protocol: ["http", "https"],
  hostname: ["twitter.com", "x.com"],
}))

Methods

coerceArray

Coerces the input to be an array.

Useful for normalizing query string inputs such as ?id=1&id=2 which are presented as string | string[].

Usage:

// works for both single ID and multiple IDs
const ids = v.parse(v.coerceArray(v.array(v.string())), request.query.id)

flatErrorsParser

Works similar to parser, but throws a FlatErrorsError which is a Error with root, nested, and other properties (implementing the interface of FlatErrors).

Usage:

const parseBody = v.flatErrorsParser(v.object({
  name: v.string(),
}))

// h3 handler
export default defineEventHandler(async (event) => {
  const body = await readValidatedBody(event, parseBody)
  // body is validated, or a HTTP 400 with { data: flatErrors } is thrown
})

Issues

createFlatErrors

Utility shortcut to simplify creating FlatErrors:

• accepts root error(s), nested error(s), or both
• converts single strings to error lists

Usage:

createFlatErrors("Single root error")
// => FlatErrors { root: ["Single root error"], nested: {} }

createFlatErrors(["Root error 1", "Root error 2"])
// => FlatErrors { root: ["Root error 1", "Root error 2"], nested: {} }

createFlatErrors({ nested1: "Nested 1", nested2: ["Nested 2a", "Nested 2b"] })
// => FlatErrors { nested: { nested1: ["Nested 1"], nested2: ["Nested 2a", "Nested 2b"] } }

createFlatErrors("Root", { nested: "Nested" })
// => FlatErrors { root: ["Root"], nested: { nested: ["Nested"] } }

To create a wrapper around createFlatErrors, you can use types CreateFlatErrors (the function overload type) or CreateFlatErrorsInput (the argument overload tuples).

Types

BaseSchemaMaybeAsync, GenericSchemaMaybeAsync

Shortcuts for BaseSchema<...> | BaseSchemaAsync<...> and GenericSchema<...> | GenericSchemaAsync<...>.

Related issue: https://github.com/fabian-hiller/valibot/issues/198