Transformaciones de Zod

Da forma, realiza coerción y añade lógica de validación personalizada con transform, refine, superRefine, preprocess y pipe.

Receta

Tarjeta de referencia rápida — lista para copiar y pegar.

import { z } from "zod";
 
// transform — cambia el valor de salida
const Trimmed = z.string().transform((s) => s.trim());
const Lower = z.string().transform((s) => s.toLowerCase());
 
// refine — predicado de validación personalizada
const EvenNumber = z.number().refine((n) => n % 2 === 0, {
  message: "Debe ser un número par",
});
 
// superRefine — múltiples problemas, control total
const PasswordSchema = z.string().superRefine((val, ctx) => {
  if (val.length < 8) {
    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Al menos 8 caracteres" });
  }
  if (!/[A-Z]/.test(val)) {
    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Al menos una letra mayúscula" });
  }
  if (!/\d/.test(val)) {
    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Al menos un dígito" });
  }
});
 
// preprocess — realiza coerción antes de la validación
const CoercedNumber = z.preprocess((val) => Number(val), z.number().positive());
 
// pipe — encadena esquemas juntos
const StringToNumber = z.string().pipe(z.coerce.number().int().positive());

Cuándo usarlo: Cuando la validación de tipo básica no es suficiente — necesitas normalizar datos, aplicar reglas de negocio o encadenar transformaciones.

Ejemplo de Trabajo

"use client";
 
import { useState } from "react";
import { z } from "zod";
 
const SignupSchema = z
  .object({
    username: z
      .string()
      .min(3)

Lo que esto demuestra:

• transform para normalizar el nombre de usuario y el correo electrónico
• superRefine para validación de contraseña con múltiples reglas
• preprocess para convertir la edad de string a número
• .refine a nivel de objeto para validación entre campos (coincidencia de contraseña)

Análisis Profundo

Cómo Funciona

• transform se ejecuta después de que pase la validación y asigna la salida a un valor nuevo (puede cambiar el tipo)
• refine añade una comprobación de predicado; devolver false crea un único problema
• superRefine proporciona acceso completo a RefinementCtx para que puedas añadir múltiples problemas
• preprocess ejecuta una función en la entrada sin procesar antes de cualquier validación de esquema
• pipe pasa la salida de un esquema como entrada a otro — útil para transformaciones de múltiples pasos
• Las transformaciones cambian el tipo de salida, lo que significa que z.input y z.output pueden diferir

Variaciones

Refine asincronismo para verificaciones del lado del servidor:

const UniqueEmail = z.string().email().refine(
  async (email) => {
    const exists = await db.user.findUnique({ where: { email } });
    return !exists;
  },
  { message: "Correo electrónico ya registrado" }

Encadenamiento de transformaciones:

const CsvToNumbers = z
  .string()
  .transform((s) => s.split(","))
  .transform((arr) => arr.map(Number))
  .pipe(z.array(z.

Tipos marcados con refine:

const UserId = z.string().uuid().brand<"UserId">();
type UserId = z.infer<typeof UserId>; // string & { __brand: "UserId" }
 
function getUser(id: UserId) { /* ... */ }

Canalización de default + transform:

const Config = z.object({
  port: z.coerce.number().default(3000),
  host: z.string().default("localhost").transform((h) => h.toLowerCase()),
  debug: z.preprocess((

Notas de TypeScript

// Cuando un esquema tiene transformaciones, los tipos de entrada y salida difieren
const S = z.string().transform((s) => s.length);
type SInput = z.input<typeof S>;   // string
type SOutput = z.

Trampas

• refine solo se ejecuta si la validación base pasa — Si z.string().email().refine(...) recibe un no-email, el callback refine nunca se llama. Esto es generalmente deseable pero puede sorprenderte si esperas todos los errores a la vez.

• transform cambia el tipo — Después de .transform(), los validadores anteriores ven el tipo transformado. Si encadenas .min() después de .transform(), valida el valor transformado. Solución: Coloca los validadores antes de las transformaciones.

• preprocess vs coerce — z.preprocess es un gancho de propósito general; z.coerce.* es un atajo para z.preprocess(Constructor, ...). Prefiere z.coerce para la conversión de tipo simple.

• Los refinamientos asincronos requieren parseAsync — Llamar a .parse() en un esquema con refinamientos asincronos lanza un error. Solución: Siempre usa parseAsync o safeParseAsync.

• Ruta refine a nivel de objeto — Si omites path en un .refine() a nivel de objeto, el error aparece en formErrors en lugar de fieldErrors. Solución: Siempre especifica path: ["fieldName"] para refinamientos a nivel de objeto.

Alternativas

Preguntas Frecuentes

const CsvToNumbers = z.string()
  .transform((s) => s.split(","))
  .transform((arr) => arr.map(Number))
  .pipe(z.

const Email = z.string().email().transform((s) => s.toLowerCase().trim());
const Username = z.string().min(3).transform((s

const Password = z.string().superRefine((val, ctx) => {
  if (val.length < 8)
    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "Al menos 8 caracteres" });
  if (!/

schema.refine((d) => d.password === d.confirmPassword, {
  message: "Las contraseñas no coinciden",
  path: ["confirmPassword"],
});

const UniqueEmail = z.string().email().refine(
  async (email) => !(await db.user.findUnique({ where: { email } })),
  { message: "Correo electrónico ya registrado" }
);
// Debe usar parseAsync o safeParseAsync

const UserId = z.string().uuid().brand<"UserId">();
type UserId = z.infer<typeof UserId>;
// string & { __brand: "UserId" }
// Evita pasar strings arbitrarios donde se espera un UserId

const S = z.string().transform((s) => s.length);
type SInput = z.input<typeof S>;   // string
type SOutput = z.output

const NonEmpty = z.array(z.string()).superRefine(
  (arr, ctx): arr is [string, ...string[]] => {
    if (arr.length ===

Relacionado

• Conceptos Básicos de Zod — parse, safeParse, manejo de errores
• Tipos de Zod — todos los tipos incorporados
• Zod Infer — z.infer, z.input, z.output
• RHF + Zod — integración de resolver

Coloca los validadores antes de las transformaciones para que verifiquen la entrada sin procesar.

Los tipos de entrada y salida divergen cuando una transformación cambia el tipo.