Zod para TypeScript: guía completa con ejemplos

Introducción a Zod: qué es y por qué es necesario

En el desarrollo web moderno con TypeScript, uno de los problemas clave es garantizar la integridad de los datos. Incluso con una tipificación estricta, TypeScript no puede garantizar que los datos provenientes de fuentes externas (API, formularios, localStorage, WebSocket) realmente correspondan a los tipos declarados. El compilador de TypeScript funciona en la etapa de desarrollo, pero durante la ejecución del programa los tipos se borran. Aquí es donde Zod viene al rescate.

Zod es una biblioteca para la validación declarativa y tipificación de datos para TypeScript y JavaScript. Permite crear esquemas (schemas) que sirven tanto como validador de datos en tiempo de ejecución como fuente de verdad para los tipos estáticos de TypeScript. La filosofía principal de Zod es "un esquema, dos propósitos": escribes el esquema una vez y obtienes tanto la validación como el tipo inferido automáticamente.

Ventajas clave de Zod:

\n
• Seguridad de tipos: inferencia automática de tipos TypeScript a partir de esquemas.
\n
• Declaratividad: sintaxis legible y concisa.
\n
• Composicionalidad: los esquemas se pueden combinar y extender.
\n
• Errores detallados: mensajes de error de validación claros.
\n
• Cero dependencias: la biblioteca no requiere paquetes adicionales.
\n

Instalación de Zod

Zod es un paquete npm, por lo que la instalación se realiza a través del gestor de paquetes de Node.js. La biblioteca está escrita en TypeScript y viene con archivos de declaración de tipos listos, por lo que no se requiere una instalación adicional de @types/zod.

# Instalación con npm\nnpm install zod\n\n# Instalación con yarn\nyarn add zod\n\n# Instalación con pnpm\npnpm add zod

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

import { z } from "zod";

Ten en cuenta: Zod no se instala con pip, ya que es una biblioteca para el ecosistema JavaScript/TypeScript, no para Python.

Inicio rápido con un ejemplo de código

Vamos a crear un esquema simple para validar datos de usuario y ver inmediatamente cómo Zod combina validación y tipificación.

import { z } from "zod";\n\n// 1. Definimos el esquema\nconst UserSchema = z.object({\n    id: z.number().positive(),\n    name: z.string().min(2, "El nombre debe contener al menos 2 caracteres"),\n    email: z.string().email("Email no válido"),\n    age: z.number().int().min(18, "La edad debe ser al menos 18 años").optional(),\n});\n\n// 2. Inferimos automáticamente el tipo a partir del esquema\ntype User = z.infer<typeof UserSchema>;\n\n// 3. Validamos los datos\nconst validData = {\n    id: 1,\n    name: "Ana",\n    email: "ana@example.com",\n    age: 25,\n};\n\nconst result = UserSchema.safeParse(validData);\n\nif (result.success) {\n    // result.data tiene el tipo User\n    console.log("Validación exitosa:", result.data);\n} else {\n    // result.error contiene información detallada sobre los errores\n    console.log("Errores de validación:", result.error.errors);\n}\n\n// Ejemplo con datos no válidos\nconst invalidData = {\n    id: -1,\n    name: "A",\n    email: "no-email",\n};\n\nconst invalidResult = UserSchema.safeParse(invalidData);\nif (!invalidResult.success) {\n    console.log("Errores:", invalidResult.error.errors);\n    // Mostrará:\n    // - id: debe ser un número positivo\n    // - name: El nombre debe contener al menos 2 caracteres\n    // - email: Email no válido\n}

Métodos y funciones principales de Zod

En esta sección, veremos en detalle los 10 métodos clave de Zod que cubrirán el 90% de tus tareas de validación.

1. z.string() — Validación de cadenas

Qué hace: Crea un esquema para validar valores de cadena. Proporciona una cadena de métodos para imponer restricciones adicionales.

Parámetros: No acepta parámetros al crearse