Zod en los límites

TypeScript no puede validar cuerpos HTTP, cadenas de consulta o variables de entorno en tiempo de ejecución. Los esquemas Zod en los límites del sistema convierten la entrada desconocida en datos tipados y confiables.

Receta

import { z } from 'zod';
 
const EnvSchema = z.object({
  PORT: z.coerce.number().default(3000),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
});
 
export const env = EnvSchema.parse(process.env);

const CreateUser = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
});
type CreateUser = z.infer<typeof CreateUser>;

Cuándo usarlo:

• Configuración de arranque desde process.env
• Validación de cuerpo JSON POST/PUT en Express 5 o Fastify 5
• Análisis de cargas de webhook de Stripe, Twilio, etc.
• Reemplazo de conversiones as MyType inseguras en req.body

Ejemplo de trabajo

import { z } from 'zod';
import { createServer, type IncomingMessage, type ServerResponse } from 'node:http';
 
const EnvSchema = z.object({
  PORT: z.coerce.number().default(3000),
});
const env = EnvSchema.parse(process.env);
 
const CreateItem = z.object({
  name: z.string().min(1),
  qty: z.number().int().positive(),
});
 
async function readJson(req: IncomingMessage): Promise<unknown> {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
}
 
function sendJson(res: ServerResponse, status: number, body: unknown): void {
  res.writeHead(status, { 'content-type': 'application/json' });
  res.end(JSON.stringify(body));
}
 
const server = createServer(async (req, res) => {
  if (req.method === 'POST' && req.url === '/items') {
    try {
      const raw = await readJson(req);
      const item = CreateItem.parse(raw);
      sendJson(res, 201, { id: '1', ...item });
    } catch (err) {
      if (err instanceof z.ZodError) {
        sendJson(res, 400, { error: 'validation_failed', issues: err.flatten() });
        return;
      }
      throw err;
    }
    return;
  }
  sendJson(res, 404, { error: 'not_found' });
});
 
server.listen(env.PORT);

Lo que esto demuestra:

• parse lanza ZodError en caso de fallo: mapea a 400, no a 500
• z.coerce.number() maneja variables de entorno de cadena como "3000"
• z.infer deriva tipos de TypeScript del mismo esquema que en tiempo de ejecución
• flatten() produce errores a nivel de campo seguros para los clientes

Análisis profundo

Cómo funciona

• Zod construye una cadena de validadores; parse se ejecuta sincrónicamente. Mantén los esquemas modestos en rutas críticas o almacena en caché los esquemas compilados.
• safeParse devuelve { success, data | error } - estilo funcional sin try/catch.
• Las transformaciones (z.string().transform(s => s.trim())) se ejecutan después de la validación - documenta los efectos secundarios.
• Los refinamientos (.refine()) expresan reglas entre campos - confirmación de contraseña, rangos de fechas.

Mapa de límites

Notas de TypeScript

import { z } from 'zod';
 
const IdParams = z.object({ id: z.string().uuid() });
 
// Patrón de middleware reutilizable
function parseParams<T extends z.ZodType>(schema: T, input: unknown): z.infer<T> {
  return schema.parse(input);
}

Errores comunes

• Uso repetido de .parse en cargas útiles enormes - compila una vez, reutiliza los objetos de esquema. Solución: const Schema = z.object(...) a nivel de módulo.
• Filtración de pilas de ZodError a los clientes - usa flatten() o un mapa de errores personalizado. Solución: registra el error completo solo en el servidor.
• Duplicación de esquema e interfaz - la deriva está garantizada. Solución: solo z.infer, sin interface paralelo.
• Variables de entorno opcionales sin valores predeterminados - undefined falla en esquemas estrictos. Solución: .optional(), .default(), o documenta las variables requeridas.
• Confiar en z.string() para columnas HTML/JSON - la validación no es sanitización. Solución: escapa en la salida, SQL parametrizado.

Alternativas

Preguntas frecuentes

Relacionado

• Tipado de manejadores Express/Fastify - genéricos de manejadores
• Conceptos básicos de configuración - patrones de carga de variables de entorno
• Zod - recetas centradas en la biblioteca
• Estándares de respuesta de error - forma 400

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.