Uso básico

Esta página te guiará a través de los conceptos básicos de la creación de esquemas, el análisis de datos y el uso de tipos inferidos. Para obtener documentación completa sobre la API de esquemas de Zod, consulta Definición de esquemas.

Definición de un esquema

Antes de poder hacer cualquier otra cosa, necesitas definir un esquema. Para los propósitos de esta guía, usaremos un esquema de objeto simple.

import * as z from "zod"; 
 
const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});

Análisis de datos

Dado cualquier esquema Zod, usa .parse para validar una entrada. Si es válida, Zod devuelve un clon profundo fuertemente tipado de la entrada.

Player.parse({ username: "billie", xp: 100 }); 
// => devuelve { username: "billie", xp: 100 }

await Player.parseAsync({ username: "billie", xp: 100 }); 

Manejo de errores

Cuando la validación falla, el método .parse() lanzará una instancia de ZodError con información detallada sobre los problemas de validación.

try {
  Player.parse({ username: 42, xp: "100" });
} catch(error){
  if(error instanceof z.ZodError){
    error.issues; 
    /* [
      {
        expected: 'string',
        code: 'invalid_type',
        path: [ 'username' ],
        message: 'Invalid input: expected string'
      },
      {
        expected: 'number',
        code: 'invalid_type',
        path: [ 'xp' ],
        message: 'Invalid input: expected number'
      }
    ] */
  }
}

Para evitar un bloque try/catch, puedes usar el método .safeParse() para obtener un objeto de resultado plano que contenga los datos analizados con éxito o un ZodError. El tipo de resultado es una unión discriminada, por lo que puedes manejar ambos casos convenientemente.

const result = Player.safeParse({ username: 42, xp: "100" });
if (!result.success) {
  result.error;   // instancia de ZodError
} else {
  result.data;    // { username: string; xp: number }
}

await schema.safeParseAsync("hello");

Inferencia de tipos

Zod infiere un tipo estático de tus definiciones de esquema. Puedes extraer este tipo con la utilidad z.infer<> y usarlo como quieras.

const Player = z.object({ 
  username: z.string(),
  xp: z.number()
});
 
// extraer el tipo inferido
type Player = z.infer<typeof Player>;
 
// usarlo en tu código
const player: Player = { username: "billie", xp: 100 };

En algunos casos, los tipos de entrada y salida de un esquema pueden divergir. Por ejemplo, la API .transform() puede convertir la entrada de un tipo a otro. En estos casos, puedes extraer los tipos de entrada y salida de forma independiente:

const mySchema = z.string().transform((val) => val.length);
 
type MySchemaIn = z.input<typeof mySchema>;
// => string
 
type MySchemaOut = z.output<typeof mySchema>; // equivalente a z.infer<typeof mySchema>
// number

Ahora que hemos cubierto los conceptos básicos, saltemos a la API de esquemas.