Installazione e Setup

Installazione

Zod è disponibile su npm e non ha dipendenze esterne. Puoi installarlo con il tuo package manager preferito.

npm

npm install zod

yarn

yarn add zod

pnpm

pnpm add zod

Bun

bun add zod

Configurazione TypeScript

Zod richiede TypeScript 4.5+ e la modalità strict abilitata nel tsconfig.json. Senza strict mode, l’inferenza dei tipi potrebbe non funzionare correttamente.

{
  "compilerOptions": {
    "strict": true,
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true
  }
}

L’opzione strict abilita automaticamente diverse sotto-opzioni importanti come strictNullChecks, strictFunctionTypes e noImplicitAny. Se non puoi attivare strict, assicurati almeno di avere strictNullChecks abilitato:

{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

Importazione

Zod espone tutto tramite un singolo import:

import { z } from "zod";

Tutto ciò che ti serve (schemi, tipi, utilità) è accessibile dall’oggetto z.

Primo Schema di Esempio

Creiamo uno schema per validare i dati di un utente:

import { z } from "zod";

// Definiamo lo schema
const UserSchema = z.object({
  nome: z.string().min(2, "Il nome deve avere almeno 2 caratteri"),
  email: z.string().email("Email non valida"),
  eta: z.number().int().positive("L'età deve essere positiva"),
  ruolo: z.enum(["admin", "utente", "moderatore"]),
});

// Inferiamo il tipo TypeScript dallo schema
type User = z.infer<typeof UserSchema>;

// Validazione con dati corretti
const risultato = UserSchema.safeParse({
  nome: "Marco",
  email: "marco@esempio.it",
  eta: 28,
  ruolo: "admin",
});

if (risultato.success) {
  console.log("Utente valido:", risultato.data);
  // risultato.data è tipizzato come User
} else {
  console.log("Errori:", risultato.error.issues);
}

Validazione con Dati Errati

const risultatoErrato = UserSchema.safeParse({
  nome: "M",
  email: "non-una-email",
  eta: -5,
  ruolo: "superadmin",
});

if (!risultatoErrato.success) {
  console.log(risultatoErrato.error.issues);
  // [
  //   { message: "Il nome deve avere almeno 2 caratteri", path: ["nome"] },
  //   { message: "Email non valida", path: ["email"] },
  //   { message: "L'età deve essere positiva", path: ["eta"] },
  //   { message: "Invalid enum value...", path: ["ruolo"] },
  // ]
}

Uso con JavaScript Puro

Anche se Zod è progettato per TypeScript, funziona perfettamente con JavaScript:

const { z } = require("zod");

const schema = z.object({
  titolo: z.string(),
  completato: z.boolean().default(false),
});

const dati = schema.parse({ titolo: "Studiare Zod" });
console.log(dati); // { titolo: "Studiare Zod", completato: false }

In questo caso non avrai l’inferenza dei tipi, ma la validazione runtime funziona esattamente allo stesso modo.