Generator schematu Zod

Generator schematu Zod

Generator schematu Zod zamienia listę pól w formacie „nazwa: typ” albo wklejony interface TypeScript na gotowy kod z.strictObject() lub z.object() z typem z.infer. Zod to biblioteka walidacji dla TypeScript działająca w czasie wykonania. Schemat opisuje kształt danych, a z.infer wyciąga z niego statyczny typ — jedno źródło prawdy.

Mapowanie typów

Typ wpisany po dwukropku jest tłumaczony według stałego słownika, bez względu na wielkość liter (Date działa tak samo jak date).

Typ spoza słownika, np. Address albo { street: string }, zamienia się w z.string(), dostaje status „Uwaga” w tabeli pod wynikiem i podbija licznik „Do sprawdzenia”.

Przykład

Dla pól id: number, name: string, email: email i age?: number przy domyślnych opcjach (import, strictObject, typ z.infer) wynik ma 10 linii:

import { z } from "zod";

export const userSchema = z.strictObject({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
  age: z.number().optional(),
});

export type UserSchema = z.infer<typeof userSchema>;

Gdyby e-mail był wpisany jako email: string, dostałbyś samo z.string() bez sprawdzania formatu. Nazwa typu to nazwa schematu z wielką pierwszą literą.

strictObject

Domyślnie z.object() nie zgłasza błędu przy dodatkowych polach, tylko usuwa je z wyniku parse(). strictObject je odrzuca — to bezpieczniejsze przy API, bo wyłapuje literówki i nieoczekiwane dane. W generatorze odpowiada za to opcja „strictObject (odrzucaj nadmiar)”, domyślnie włączona; po jej odznaczeniu dostajesz z.object().

Jak działa generator schematu Zod

Generator czyta tekst linia po linii i każdą linię „nazwa: typ” zamienia na parę klucz-wartość wewnątrz obiektu, gdzie klucz to nazwa pola, a wartość to metoda walidująca, taka jak z.string() albo z.number(). Puste linie, komentarze // i /* */, nagłówek wklejonego interface lub type oraz zamykający nawias są pomijane, podobnie średniki, przecinki i słowo readonly. Linia bez dwukropka i powtórzona nazwa pola trafiają do ostrzeżeń. Limit to 100 pól i 8000 znaków.

Znak „?” po nazwie pola tłumaczony jest na wywołanie .optional() na końcu łańcucha, „| null” w typie na .nullable(), a oba naraz na .nullish(). Zapis „| undefined” działa jak „?”. Różnica jest istotna: pole opcjonalne może w ogóle nie wystąpić, a pole nullable musi zostać przesłane, choć może mieć wartość null. Ograniczeń typu .min(2).max(40) ani wartości domyślnych .default() generator nie dodaje. Jedyny wyjątek to opcja „Teksty niepuste”, która każdy typ string zamienia na z.string().min(1).

Na końcu generator dokłada eksport typu statycznego, dzięki czemu opis walidacji w czasie wykonania i typ widziany przez edytor pochodzą z jednego miejsca. Pod kodem widać liczniki (pola, wymagane, opcjonalne, linie kodu, do sprawdzenia) i tabelę, która pokazuje, jak zamieniono każde pole.

Przykład: schemat formularza rejestracyjnego krok po kroku

1. Wpisujemy pola: id: int, name: string, email: email, age?: int, tags: string[]. Razem 5 pól, z czego 4 są wymagane, a 1 opcjonalne — tyle pokażą liczniki pod wynikiem.
2. Generator mapuje typy: id na z.number().int(), name na z.string(), email na z.string().email(), age na z.number().int().optional(), tags na z.array(z.string()).
3. Zaznaczamy „Teksty niepuste”. Pole name zmienia się w z.string().min(1), a tags w z.array(z.string().min(1)). Email zostaje bez zmian, bo .email() i tak odrzuca pusty tekst.
4. Zostawiamy tryb ścisły, bo dane przychodzą z API. Schemat ma 5 dozwolonych kluczy, a cały kod z importem i typem z.infer liczy 11 linii.
5. Ograniczenia domenowe dopisujemy ręcznie w skopiowanym kodzie: name na z.string().min(2).max(40), a age na z.number().int().min(18).max(120).
6. Test na poprawnych danych: id 42, name „Anna”, email [email protected], age 30, tags [„admin”]. Wszystkie 4 wymagane pola są obecne, opcjonalne age również — walidacja przechodzi i zwraca obiekt w tym samym kształcie.
7. Test na danych z nadmiarowym kluczem: ten sam obiekt plus pole role o wartości „admin”. W schemacie jest 5 kluczy, w danych 6, więc parse() rzuca błąd o kodzie unrecognized_keys z nazwą nieznanego pola. Przy z.object() obiekt przeszedłby, a klucz role zniknąłby z wyniku bez ostrzeżenia.

Sytuacja w danych a metoda Zod

Praktyczne wskazówki przy generowaniu schematu

• Trzymaj jeden schemat na kontrakt — jeśli te same dane walidujesz w formularzu i na serwerze, użyj jednego wygenerowanego schematu zamiast dwóch kopii, które z czasem się rozjadą.
• Waliduj na granicy systemu — schemat ma sens tam, gdzie dane wchodzą: żądanie HTTP, odpowiedź API, zawartość formularza. W środku aplikacji operuj już na typach, nie na ponownych sprawdzeniach.
• Nazwy pól zostaw takie jak w źródle. Jeśli API zwraca snake_case, nie zmieniaj nazw w schemacie, bo dopasowanie danych do pól przestanie być oczywiste. Zmianę konwencji rób osobno, po walidacji.
• Zagnieżdżone struktury buduj od dołu: najpierw addressSchema, potem schemat, który go używa. Odwołanie działa tylko dla nazw kończących się na „Schema”, a schemat musi być zdefiniowany w pliku wcześniej.

Czego narzędzie nie uwzględnia

• Reguł biznesowych — generator odtwarza strukturę typów, ale nie wie, że data końca musi być późniejsza niż data początku, ani że suma pozycji musi zgadzać się z kwotą faktury. Takie warunki dopisujesz samodzielnie, np. przez .refine().
• Zależności między polami — warunki typu „pole wymagane tylko wtedy, gdy inne ma konkretną wartość” nie wynikają z opisu typów i trzeba je dopisać ręcznie na poziomie całego obiektu.
• Zagnieżdżonych obiektów we wklejonym interface — linia address: { nie jest rozpoznana, a pola z jej wnętrza trafiają na najwyższy poziom schematu. Wydziel taki obiekt do osobnego interface i wpisz address: addressSchema.
• Wersji biblioteki — wynik działa w Zod 3 i Zod 4. W Zod 4 zapisy z.string().email(), .url(), .uuid() i .datetime() są oznaczone jako przestarzałe na rzecz z.email(), z.url(), z.uuid() i z.iso.datetime(), ale nadal działają.