TypeStack/class-validator para TypeScript: guía completa con ejemplos

1. ¿Qué es y para qué sirve?

La librería TypeStack/class-validator es una potente herramienta para la validación de datos en TypeScript y JavaScript, basada en decoradores. Permite a los desarrolladores definir reglas de validación directamente en las clases, utilizando decoradores de propiedades. Esto hace que el código sea más legible, autodocumentado y simplifica enormemente el procesamiento de datos entrantes, especialmente al trabajar con APIs REST, formularios o cualquier otra fuente de datos.

¿Para qué sirve? En el desarrollo web moderno, los datos provienen de múltiples fuentes: peticiones HTTP, archivos de configuración, bases de datos. Sin una validación fiable, estos datos pueden provocar errores en tiempo de ejecución, vulnerabilidades de seguridad o simplemente un funcionamiento incorrecto de la aplicación. class-validator resuelve este problema proporcionando una forma declarativa de verificar datos. En lugar de escribir largas estructuras if-else, simplemente añades decoradores a las propiedades de la clase y la librería verifica automáticamente que cumplan con las reglas definidas.

Otra ventaja clave es su estrecha integración con TypeScript. Los decoradores no solo permiten validar datos, sino también definir sus tipos, lo que hace que el proceso de desarrollo sea más seguro y predecible. La librería soporta una amplia gama de validadores incorporados (desde comprobaciones simples de longitud de cadenas hasta expresiones regulares complejas) y permite crear fácilmente validadores personalizados.

2. Instalación

Para instalar la librería class-validator y su dependencia obligatoria reflect-metadata, ejecuta el siguiente comando en la terminal de tu proyecto:

npm install class-validator reflect-metadata

Después de la instalación, asegúrate de que en tu archivo tsconfig.json estén habilitadas las siguientes opciones para el correcto funcionamiento de los decoradores:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

También es importante importar reflect-metadata al inicio de tu aplicación (normalmente en el archivo principal index.ts o app.ts):

import "reflect-metadata";

3. Inicio rápido

Veamos un ejemplo mínimo funcional. Crearemos una clase de usuario con validación de campos:

import "reflect-metadata";
import { validate, IsString, IsEmail, MinLength } from "class-validator";

class User {
    @IsString()
    @MinLength(3, { message: "El nombre debe tener al menos 3 caracteres" })
    name: string;

    @IsEmail({}, { message: "Email no válido" })
    email: string;

    constructor(name: string, email: string) {
        this.name = name;
        this.email = email;
    }
}

async function main() {
    const user = new User("Jo", "email-invalido");
    const errors = await validate(user);

    if (errors.length > 0) {
        console.log("Errores de validación:");
        errors.forEach(error => {
            console.log(`- ${error.property}: ${Object.values(error.constraints).join(", ")}`);
        });
    } else {
        console.log("¡Validación exitosa!");
    }
}

main();
// Salida:
// Errores de validación:
// - name: El nombre debe tener al menos 3 caracteres
// - email: Email no válido

En este ejemplo, creamos la clase User, añadimos decoradores a sus propiedades y llamamos a la función validate(). Esta devuelve un array de errores si los datos no cumplen con las reglas.