Saltar al contenido
Numio

Convertir TypeScript a esquemas Zod — Numio

Genera esquemas Zod a partir de interfaces y tipos de TypeScript con ts-to-zod. Cada tipo Foo pasa a un fooSchema exportado, y las etiquetas JSDoc como @format email o @minimum pasan a validadores de Zod.

Los tipos de tu API ya existen como interfaces de TypeScript y quieres validar en tiempo de ejecución las peticiones entrantes sin escribir esquemas a mano.

TypeScript

Zod Schema

Cuándo usarla

  • Los tipos de tu API ya existen como interfaces de TypeScript y quieres validar en tiempo de ejecución las peticiones entrantes sin escribir esquemas a mano.
  • Validas la entrada de formularios con Zod y quieres que el esquema siga siendo coherente con el tipo de TypeScript compartido.

Cómo usarla

  1. Pega interfaces o alias de tipo de TypeScript; añade etiquetas JSDoc como @minimum 13 o @format email para obtener validadores.
  2. En la configuración, activa Keep TSDoc Comments para copiar los comentarios a la salida, o Skip the creation of zod validators from JSDoc annotations para ignorar las etiquetas.
  3. El código fuente se convierte en el servidor mediante /api/typescript-to-zod; copia el código que importa z de "zod".

TypeScript

export interface Signup {
  /**
   * @format email
   */
  email: string;
  /**
   * @minimum 13
   * @maximum 120
   */
  age: number;
  plan: "free" | "pro";
  referrer?: string | null;
  createdAt: Date;
}

Esquemas Zod

import { z } from "zod"

export const signupSchema = z.object({
  email: z.string().email(),
  age: z.number().min(13).max(120),
  plan: z.union([z.literal("free"), z.literal("pro")]),
  referrer: z.string().optional().nullable(),
  createdAt: z.date(),
})

Detalles y limitaciones

La página envía tu entrada a una ruta del servidor (/api/typescript-to-zod) para convertirla; no se procesa solo en el navegador. Las rutas API de Next.js aceptan por defecto cuerpos de solicitud de hasta 1 MB.

Solo se convierten tipos. Las funciones y constantes exportadas no producen ningún esquema.

Si un tipo hace referencia a un tipo que no está en la entrada, el conversor notifica un error de dependencia faltante en lugar de emitir un esquema.

Los esquemas se ordenan por dependencias, así que un tipo referenciado como Author se emite antes que el tipo que lo usa.

FAQ

¿Cómo se convierten los campos opcionales y null?

referrer?: string | null pasa a z.string().optional().nullable(); una propiedad de tipo Author | null pasa a authorSchema.nullable().

¿Cómo se trata Date?

Una propiedad Date pasa a z.date(), que acepta objetos Date, no strings ISO. Usa z.coerce.date() para entrada JSON.

¿Por qué obtengo "Some schemas can't be generated due to direct or indirect missing dependencies"?

Un tipo hace referencia a otro tipo que no está en el código pegado. Pega también los tipos referenciados.

Especificaciones y referencias