Valibot para TypeScript: guía completa con ejemplos

Introducción: ¿qué es Valibot y para qué sirve?

\n\n

Valibot es una biblioteca moderna, modular y ligera para la validación de datos en TypeScript y JavaScript. A diferencia de gigantes como Zod o Joi, Valibot está diseñado con énfasis en el tamaño mínimo del bundle y tree-shaking (posibilidad de eliminar código no utilizado).

\n\n

La filosofía principal de Valibot es «paga solo por lo que usas». Si solo necesitas verificar que una cadena tenga una longitud mínima, importas únicamente string y minLength, no toda la biblioteca. Esto hace que Valibot sea ideal para proyectos donde el tamaño del bundle final de JavaScript es importante (por ejemplo, aplicaciones móviles o bibliotecas de componentes).

\n\n

La biblioteca está completamente tipada y ofrece una excelente integración con TypeScript, infiriendo automáticamente los tipos a partir de los esquemas de validación. Valibot admite tanto primitivas simples (cadenas, números, booleanos) como estructuras complejas (objetos, arrays, tipos unión, esquemas recursivos).

\n\n

Instalación

\n\n

Valibot se distribuye a través del gestor de paquetes npm. Para instalarlo, ejecuta el siguiente comando en la terminal de tu proyecto:

\n\n

npm install valibot

\n\n

Si usas yarn:

\n\n

yarn add valibot

\n\n

Para pnpm:

\n\n

pnpm add valibot

\n\n

Después de la instalación, puedes importar las funciones necesarias en tu archivo TypeScript:

\n\n

import { string, number, object, minLength, maxValue } from 'valibot';

\n\n

Inicio rápido con ejemplo de código

\n\n

Vamos a crear un esquema de validación simple para un formulario de registro de usuario. Validaremos el nombre, el correo electrónico y la edad.

\n\n

import { object, string, number, email, minLength, maxValue, safeParse } from 'valibot';\n\n// 1. Definimos el esquema\nconst UserSchema = object({\n  name: string([minLength(2, 'El nombre debe tener al menos 2 caracteres')]),\n  email: string([email('Correo electrónico no válido')]),\n  age: number([maxValue(120, 'La edad no puede ser mayor a 120')])\n});\n\n// 2. Datos a validar\nconst inputData = {\n  name: 'Ana',\n  email: 'ana@ejemplo.com',\n  age: 30\n};\n\n// 3. Validamos\nconst result = safeParse(UserSchema, inputData);\n\nif (result.success) {\n  console.log('Datos válidos:', result.output);\n  // result.output tiene el tipo { name: string; email: string; age: number; }\n} else {\n  console.error('Errores de validación:', result.issues);\n  // result.issues es un array de objetos con descripción de errores\n}

\n\n

En este ejemplo usamos safeParse, un método seguro que no lanza una excepción, sino que devuelve un objeto con el campo success. Si la validación es exitosa, en result.output estarán los datos validados con los tipos correctos.

\n\n

Métodos y funciones principales

\n\n

Valibot proporciona muchas funciones para crear esquemas. Veamos las más importantes.

\n\n

1. string()

\n

Qué hace: Crea un esquema para validar valores de tipo cadena. Acepta un array opcional de validadores para comprobaciones adicionales (longitud, patrón, etc.).

\n

Parámetros:

\n

\n
• validations (opcional): array de funciones validadoras como minLength, maxLength, email, url, regex y otras.
\n

\n

Ejemplo:

\n

import { string, minLength, maxLength, email } from 'valibot';\n\nconst UsernameSchema = string([minLength(3), maxLength(20)]);\nconst EmailSchema = string([email()]);\n\nconsole.log(safeParse(UsernameSchema, 'Jo')); // { success: false, issues: [...] }\nconsole.log(safeParse(EmailSchema, 'test@test.com')); // { success: true, output: 'test@test.com' }

\n\n

2. number()

\n

Qué hace: Crea un esquema para validar valores numéricos. Soporta va