Generator typów TypeScript z JSON

Generator typów TypeScript z JSON

Ręczne opisywanie odpowiedzi API jest żmudne i podatne na błędy. Ten generator typów TypeScript zamienia przykładowy JSON – pojedynczy obiekt albo tablicę rekordów – na interfejsy lub aliasy type gotowe do wklejenia do pliku types.ts.

Jak to działa

• klucze obiektu stają się polami interfejsu, a nazwę głównego typu wpisujesz sam (domyślnie Root),
• zagnieżdżone obiekty tworzą osobne interfejsy (RootAddress),
• tablice mapują się na Typ[], a pusta tablica na unknown[],
• wartości liczbowe → number, logiczne → boolean, tekstowe → string, null → null,
• gdy ta sama pozycja ma w różnych rekordach różne typy, powstaje unia, np. string | null,
• pole obecne tylko w części rekordów dostaje znak ?.

Nad wynikiem widać liczbę wygenerowanych typów, pól i pól opcjonalnych, a przycisk kopiuje cały kod. Na start możesz wczytać jeden z czterech przykładów: użytkownik, produkt, lista obiektów albo odpowiedź API.

Przykład

Wejście:

{"id":1,"name":"Anna","tags":["a","b"],"address":{"city":"Warszawa"}}

Wyjście przy domyślnych ustawieniach (interface z export):

Kilka rekordów naraz

Wklej tablicę obiektów, a generator scali ich pola w jeden typ. Przykład „Lista obiektów” z nazwą główną Contact:

[{"id":1,"name":"Anna","phone":null},{"id":2,"name":"Jan","email":"[email protected]","phone":"500100200"}]

Pole phone raz jest puste, raz ma tekst, więc dostaje unię string | null. Pole email występuje tylko w drugim rekordzie, więc jest opcjonalne. Liczniki pokażą 1 interfejs, 4 pola i 1 pole opcjonalne. Dla tablicy na najwyższym poziomie powstaje typ jednego elementu, a w kodzie używasz go jako Contact[].

Opcje

Mechanizm wnioskowania typów: od wartości do deklaracji

Generator nie zna z góry schematu API. Dostaje wyłącznie przykładowy JSON – obiekt albo niepustą tablicę obiektów – który najpierw jest parsowany do struktury danych: obiektów, tablic i wartości prostych. Wartość prosta na najwyższym poziomie (np. sama liczba) nie ma pól do opisania, więc narzędzie zgłosi błąd. Na podstawie próbki typy powstają w przejściu rekurencyjnym. Jeśli wartością jest obiekt, generator nie wkleja go w miejscu użycia, tylko tworzy osobny interfejs i wstawia referencję do niego.

Nazewnictwo interfejsów wynika z kontekstu. Obiekt główny otrzymuje nazwę z pola „Nazwa główna” (domyślnie Root). Obiekt w polu address staje się RootAddress, a obiekt w address.geo — RootAddressGeo. W wyniku interfejs rodzica zawsze stoi przed interfejsami zagnieżdżonymi. Gdy dwie ścieżki dają tę samą nazwę, druga dostaje cyfrę: obiekty w polach user_name i userName stają się RootUserName i RootUserName2. Po wygenerowaniu warto zmienić nazwy na takie, które pasują do domeny, na przykład RootAddress na DeliveryAddress.

Przy tablicach generator sprawdza wszystkie wartości w tablicy. Tablica liczb daje number[], tablica tekstów — string[], a tablica mieszana ["a", 1] — (string | number)[]. Tablica obiektów dostaje osobny interfejs elementu z końcówką Item: pole items w obiekcie Root daje RootItemsItem[], a pola wszystkich elementów są scalane. Pusta tablica nie niesie informacji o typie elementu, więc generator wstawia unknown[] – to sygnał, że typ trzeba wpisać ręcznie. Wartości zagnieżdżone głębiej niż 20 poziomów obiektów i tablic też dostają unknown. Generator nie ma wbudowanej listy typów specjalnych: data w stringu pozostanie stringiem, a identyfikator liczbowy — number.

Przykład krok po kroku: głębiej zagnieżdżony profil

1. Wejściowy JSON: {"userId":7,"profile":{"displayName":"Anna","stats":{"posts":12,"followers":345}},"active":true}
2. Generator analizuje obiekt główny. Widzi pola userId, profile i active. userId ma wartość 7, więc typ number. active ma true, więc boolean. profile jest obiektem, więc powstanie osobny interfejs.
3. Dla profile analizuje displayName i stats. displayName to tekst, więc string. stats jest obiektem, więc znów osobny interfejs.
4. Dla stats odczytuje posts:12 i followers:345. Obie wartości są liczbami, więc oba pola otrzymują typ number.
5. Wynik: trzy interfejsy i siedem pól. Root zawiera userId: number, profile: RootProfile, active: boolean. RootProfile zawiera displayName: string i stats: RootProfileStats. RootProfileStats zawiera posts: number i followers: number.
6. Każdy interfejs ma domyślnie export, więc po zmianie nazw fragment można wkleić do pliku types.ts i importować w innych modułach.

Tabela referencyjna: co generator rozpoznaje z kontekstu

Praktyczne wskazówki przed wklejeniem JSON-a

• Wklejaj kilka realistycznych rekordów — jeśli API zwraca pole tylko w niektórych przypadkach, podaj tablicę z rekordem z tym polem i bez niego, a generator oznaczy je „?”. Kluczy nieobecnych w żadnym rekordzie nie zgadnie.
• Nadaj nazwy domenowe — wpisz nazwę zasobu w pole „Nazwa główna”, np. OrderResponse, a typy zagnieżdżone dostaną ją jako przedrostek. Resztę popraw ręcznie, np. OrderResponseCustomer na Customer.
• Ustaw export świadomie — zostaw go, gdy typy mają być importowane w innych plikach projektu.
• Opcję „Wszystkie pola opcjonalne” stosuj ostrożnie — dodaje „?” do każdego pola, więc rzadko jest zgodna z kontraktem API. Dokładniejszy wynik daje scalenie kilku rekordów.
• Pola readonly przydają się dla danych, których kod nie modyfikuje, np. odpowiedzi z API trzymanej w stanie aplikacji.
• Usuń dane wrażliwe — tokeny, adresy e-mail i identyfikatory klientów nie powinny trafiać do narzędzia online. Do typów wystarczą wartości zastępcze tego samego rodzaju.

Czego generator nie uwzględnia

• Brak schematu API — narzędzie wnioskuje z próbki JSON, a nie z OpenAPI, JSON Schema czy dokumentacji. Nie wykryje pól, których nie ma w przykładzie.
• Semantyka wartości — data, identyfikator, waluta i UUID pozostaną zwykłym stringiem albo number. Pole status z wartością „paid” da string, nie unię literałów ani enum.
• Pola, które czasem znikają lub bywają null — jeśli w każdym wklejonym rekordzie pole ma wartość, dostanie typ bez „?” i bez null, nawet gdy API czasem je pomija.
• Powtarzające się kształty — dwa obiekty o tych samych polach w różnych miejscach dostaną dwa osobne interfejsy. Nazwy oparte na ścieżce bywają też długie (ApiResponseDataItemsItem), więc przy większych odpowiedziach API trzeba je uporządkować ręcznie.