JSON'dan TypeScript'e

Dış API ile konuşan TypeScript projelerinin neredeyse hepsinde, bir geliştiricinin örnek JSON yanıtı paylaşıp 'biri bunu tipleyebilir mi' diye sorduğu bir an gelir. Yıllarca yanıt elle yazmaktı: bir Type.ts dosyası açın, interface tanımlayın, anahtarları kopyalayın, opsiyonelleri tahmin edin. Geniş API yüzeyi olan projelerde bu sıkıcılık otomatik JSON'dan TypeScript üreticilerin doğmasını sağladı. Bu araç, gerçek prod kodunda en çok karşılaşılan vakalara göre ayarlanmış bir üreticidir.

Üretici JSON ağacında yürür, her değer için runtime şekline göre tip çıkarır ve adlandırılmış interface'ler (veya type alias — siz seçin) üretir. Primitif türler bariz: "hello" → string, 42 → number, true → boolean, null → null. Diziler elemanları incelenerek tiplenir: hepsi string ise `string[]`, karışık string+number ise `(string | number)[]`, boş dizi ise `unknown[]`. Nesneler en ilginç durumdur: üretici her iç nesneye otomatik ad verir (UserAddress, OrderLineItem) ve onu ayrı interface olarak yayar; bu yaklaşım çıktıyı düz ve idiomatik tutar, kimsenin okuyamayacağı tek devasa iç içe tip yerine.

Optional algılama daha zorlu bir karardır. Bir alan örneklenen tüm nesnelerde varsa zorunludur, en az birinde yoksa optional olur (`field?: type`). Tek nesne örneği için üretici hangi alanların bazen eksik olduğunu bilemez ve hepsini zorunlu olarak işaretler — daha doğru optional algılama için birkaç örnek nesne yapıştırın. 'Her zaman optional' modu, gevşek bir API ile çalışırken tüm alanları her durumda optional işaretler.

Adlandırma da yargı kararı gerektirir. Üretici adları JSON yolundan seçer — root.users[0].address Address olur — ama aynı şekil farklı yollarda görünebilir; bunları paylaşılmış tek interface'e mi birleştireceği yoksa farklı adlarla kopyalayacağı seçilebilir. Varsayılan 'yapıya göre birleştir' modu çoğu zaman doğrudur: aynı anahtarlar ve aynı tipler aynı interface'i üretir.

Çıktı özelleştirme bu aracı basit üreticilerden ayıran şeydir. `interface User` ile `type User =` arasında seçim yapabilirsiniz (interface declaration merging destekler, daha idiomatiktir; type alias union ve intersection için zorunludur). Tüm özelliklere `readonly` ekleyebilirsiniz. Kök tipi açıkça adlandırabilirsiniz. `export` anahtar kelimesini açıp kapatabilirsiniz. Her seçenek farklı codebase'lerde gerçek tercihlere karşılık gelir.

Birkaç gerçek vaka: Bilmediğiniz üçüncü taraf API'sini keşfediyorsunuz — tek yanıtı yapıştırın, üzerine refine edebileceğiniz başlangıç tipini alın. Eski tipsiz koda tip ekliyorsunuz — temsili yanıtı yapıştırın, üretilen tipi yerleştirin, çıkan tip hatalarını çözün. Test fixture'ları için tip üretiyorsunuz — fixture JSON'undan üretmek tek adımdır. Şema yayınlamayan API'ı tersine mühendislik yapıyorsunuz — birkaç temsili yanıt toplayın, contract'a refine edin.

Üretici basit araçların gözden kaçırdığı uç durumları işler. Boş nesneler (`{}`) `Record<string, never>` olarak tiplenir, anlamsız `{}` (TypeScript'te 'null/undefined hariç her şey') yerine. Boş diziler `unknown[]` olarak tiplenir, sessizce `any[]`'e değil — TypeScript kullanmanın anlamını korumak için. Tarih string'leri varsayılan olarak `string`'dir; çoğu codebase deserialization katmanında `Date`'e parse eder.

Performans basit: tipik örnekler için (birkaç yüz KB) milisaniyeler içinde, çok MB'lık örnekler bile bir saniyeden az. Çıktı sözdizimi vurgulu ve tek tıkla kopyalanabilir. Yükleme adımı yoktur — yapıştırdığınız JSON yerel JavaScript ile tarayıcıda işlenir, sunucuya gitmez. Bu gizlilik özelliği gerçek prod verisi tipliyorsanız önemlidir; çoğu online JSON-to-TypeScript üretici JSON'u sunucuya yüklemek zorundadır.

Bu araç Omnvert'in diğer geliştirici utiliti'leriyle doğal eşleşir. Tip ürettikten sonra JSON'u JSON Viewer ile gezebilir veya iki versiyonu JSON Diff ile karşılaştırabilirsiniz. YAML ↔ JSON kaynak format YAML olduğunda yararlıdır. Regex Tester üretim sonrası adları toplu düzenlemek için faydalıdır.