TypeBox para TypeScript: guía completa con ejemplos prácticos

¿Qué es TypeBox y para qué sirve?

TypeBox es una potente librería para TypeScript que permite definir esquemas de datos compatibles con el estándar JSON Schema y, al mismo tiempo, inferir tipos estáticos de TypeScript correctos. En palabras simples, es un puente entre la validación de datos en tiempo de ejecución (cuando tu aplicación funciona y verifica datos sobre la marcha) y los tipos en tiempo de compilación (cuando TypeScript verifica la corrección del código antes de ejecutarlo).

¿Para qué sirve? En el desarrollo web moderno, los datos suelen provenir de fuentes no confiables: solicitudes a APIs, formularios en sitios web, archivos de configuración. Sin validación, corres el riesgo de obtener errores en tiempo de ejecución que son difíciles de detectar. TypeBox resuelve este problema de forma elegante: describes el esquema una vez y obtienes:

• Validador en tiempo de ejecución — verifica si un objeto cumple con el esquema durante la ejecución del programa.
• Tipo estático — TypeScript infiere automáticamente el tipo que puedes usar para anotaciones.
• JSON Schema — el esquema se puede serializar a JSON y usar en otras herramientas (por ejemplo, para generar formularios de UI o documentación).

TypeBox es ideal para: crear endpoints de API con validación del cuerpo de la solicitud, trabajar con archivos de configuración, construir formularios complejos con validación de campos, y cualquier escenario donde la seguridad de tipos sea importante en todas las etapas.

Instalación de TypeBox

TypeBox es una librería para Node.js/TypeScript, por lo que se instala a través de npm (o yarn/pnpm).

npm install @sinclair/typebox

Después de la instalación, puedes importarla en tu proyecto:

import { Type } from '@sinclair/typebox';

Para trabajar con validación, también necesitarás un validador. TypeBox no lo incluye por defecto para dejar la elección al desarrollador. Se recomienda usar @sinclair/typebox/compiler (compilador integrado) o ajv (validador JSON Schema popular). Instalemos el compilador:

npm install @sinclair/typebox-compiler

O, si prefieres AJV:

npm install ajv ajv-formats

Ten en cuenta: la librería se llama @sinclair/typebox, no simplemente typebox. Esto es importante para una instalación correcta.

Inicio rápido con ejemplo de código

Vamos a crear un esquema simple para un usuario y validarlo.

import { Type } from '@sinclair/typebox';
import { TypeCompiler } from '@sinclair/typebox/compiler';

// 1. Definimos el esquema del usuario
const UserSchema = Type.Object({
    id: Type.Number(),
    name: Type.String({ minLength: 2 }),
    email: Type.String({ format: 'email' }),
    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),
});

// 2. Creamos el compilador para validación
const validator = TypeCompiler.Compile(UserSchema);

// 3. Datos de prueba
const validUser = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
};

const invalidUser = {
    id: 'not-a-number',
    name: 'A',
    email: 'invalid-email',
};

// 4. Validación
console.log(validator.Check(validUser));   // true
console.log(validator.Check(invalidUser)); // false

// 5. Obtenemos el tipo estático
type UserType = Static<typeof UserSchema>;
// Ahora UserType es { id: number; name: string; email: string; age?: number; }

En este ejemplo, definimos un esquema, lo compilamos en un validador y verificamos dos objetos. Observa el uso de Type.Optional para el campo age — puede estar ausente. También usamos format: 'email' para validar el formato del correo electrónico.

Métodos y funciones principales de TypeBox

TypeBox ofrece un amplio conjunto de funciones para crear esquemas. Veamos las más importantes.

1. Type.String()

Qué hace: Crea un esquema para el tipo string. Permite