Zod 4 sürümü yayınlandı

 (zod.dev)
1 puan yazan GN⁺ 2025-05-20 | 1 yorum | WhatsApp'ta paylaş
  • Şema tanımlama ve doğrulama kütüphanesi Zod'un 4. sürümü yayınlandı. Büyük performans iyileştirmeleri ve uzun süredir talep edilen özelliklerle birlikte kararlı sürüm çıktı
  • Hız ve bundle boyutu tarafında büyük iyileştirmeler yapıldı; yeni mini sürüm (v4-mini) bundle boyutunu ciddi ölçüde azaltıyor
  • Yeni metadata registry ve JSON Schema dönüşümü ile özyinelemeli tip çıkarımı özelliği eklendi
  • Hata mesajı özelleştirme ve çok dilli locale sistemi gibi geliştirici deneyimini güçlendiren yenilikler sunuldu
  • Gelecekte kütüphane geliştirmede kullanılabilecek core alt paketinin eklenmesiyle genişletilebilirlik daha da arttı

Zod 4'e giriş

Önemli sürüm duyurusu

  • 1 yıllık yoğun geliştirmenin ardından Zod 4 kararlı sürüm olarak yayınlandı
  • Geliştirme süreci Clerk'ün OSS Fellowship desteğiyle yürütüldü
  • Şu anda Zod 3 ile paralel olarak dağıtılıyor; bu da Zod 4'e kademeli geçişi kolaylaştırıyor
  • Bazı breaking change'lere dair ayrıntılı bilgi Migration guide içinde bulunabilir

Büyümenin arka planı

  • 2021'de çıkan Zod 3'e kıyasla Zod 4, GitHub yıldız sayısı ve haftalık indirme sayısında katlanarak büyüdü
  • Zod 4 çok daha hızlı, daha hafif ve TypeScript derleyici verimliliği açısından daha iyi
  • Uzun süredir çokça talep edilen 9 önemli sorun çözüldü

Benchmark ve performans

  • Hız artışı:
    • String parsing: 14.71 kat daha hızlı sonuç
    • Dizi parsing: 7.43 kat daha hızlı
    • Nesne parsing (safeParse): 6.5 kat daha hızlı
  • Depoda benchmark'ı doğrudan çalıştırabilmeniz için script sağlanıyor
  • İyileştirilen generic yapısı sayesinde .extend(), .omit() gibi metotları zincirlerken derleme performansı 10 kat arttı
  • Büyük şemalarda ve geniş kod tabanlarında TypeScript derleme hızı önemli ölçüde iyileşti

Bundle boyutu ve Zod Mini

  • Varsayılan bundle boyutu %57 küçüldü; v4, v3'e göre 2.3 kat daha küçük bir boyut sunuyor
  • zod/v4-mini, fonksiyon tabanlı ve tree-shake edilebilir bir API sunarak bundle boyutunu %85'e kadar azaltıyor
  • Core ile v4-mini arasındaki API farkları resmi dokümantasyonda ayrıntılı biçimde açıklanıyor
  • Kullanılmayan metotların bundler tarafından kolayca atılabilmesi için yapı buna göre tasarlandı

Metadata registry ve JSON Schema desteği

  • Typed metadata şemalara güçlü tip desteğiyle kaydedilip yönetilebiliyor
  • Global registry(z.globalRegistry) içinde JSON Schema uyumlu metadata işleme ve otomatik ekleme özelliği sunuluyor
  • .meta(), .describe() ile şema dokümantasyonu kolaylaşıyor
  • .toJSONSchema() ile şemaları JSON Schema formatına dönüştürmek mümkün; metadata da otomatik olarak yansıtılıyor

Özyinelemeli tiplerin otomatik çıkarımı

  • Özyinelemeli nesne tipleri ve karşılıklı özyinelemeli tipler, ayrı bir type cast gerekmeden doğal biçimde tanımlanıp çıkarılabiliyor
  • Kullanım deneyimi, önceki Zod 3 kalıplarına göre ciddi biçimde iyileştirildi
  • Özyinelemeli ve karşılıklı özyinelemeli tiplerde de tüm şema metotları kullanılabiliyor

Dosya tipi ve doğrulama özellikleri

  • Yeni file() tipi ile File instance'ları doğrulanabiliyor
  • Dosya boyutu (min, max) ve MIME type gibi çeşitli dosya kısıtları doğrulanabiliyor

Hata mesajları ve locale sistemi

  • Global locale API'si (z.locales) ile hata mesajları için çok dilli destek sağlanabiliyor
  • Resmi z.prettifyError fonksiyonu ile kullanıcı dostu hata biçimlendirmesi sunuluyor

Format fonksiyonları ve template literal

  • Mevcut string formatları (email vb.) üst seviye fonksiyonlara taşınarak okunabilirlik ve tree shaking iyileştirildi
  • Çeşitli email regex seçenekleri sunularak farklı doğrulama ihtiyaçları karşılanıyor
  • Template literal tipi desteği: tip sisteminde ifade edilebilen string kalıpları ve karmaşık kombinasyonlar kolayca kurulabiliyor

Yeni sayı ve bigint formatları

  • Sabit genişlikli tamsayı ve kayan noktalı sayı tipleri (int32, uint64 vb.) destekleniyor
  • Güvenli aralık içinde otomatik minimum/maksimum kısıtlar eklenmiş şemalar oluşturulabiliyor

z.stringbool tanıtımı

  • String tabanlı boolean parsing (yes, no vb.) yapılabiliyor; environment variable tarzı parsing de destekleniyor
  • Truthy/falsy değerler özelleştirilebiliyor

Hata özelleştirme API'sinin birleştirilmesi

  • Birleştirilmiş error parametresi ile hata mesajları ve işleme mantığı daha düzenli hale getirildi
  • Mevcut çeşitli hata API'leri (message, invalid_type_error, errorMap) deprecated oldu

Diğer temel iyileştirmeler

  • Discriminated union'lar çeşitli şemaları, iç içe yapıları ve kombinasyonları destekliyor
  • .literal() artık aynı anda birden fazla değere izin veriyor
  • .refine() gibi özel doğrulamalar daha sezgisel biçimde entegre edildi
  • Transform ile ilgili .overwrite() sayesinde dönüşüm tipi değiştirilmeden sonradan işleme yapılabiliyor

Kütüphane genişletilebilirliği ve yeni core

  • zod/v4/core ile çekirdek işlevler ayrı bir alt pakete ayrıldı; böylece farklı kütüphane ve platformlara entegrasyon/genişletme mümkün hale geldi
  • Kütüphane geliştiricileri için kılavuz belgeler ve genişletme örnekleri sağlanıyor

Kapanış

  • Zod 4, tip güvenliği, performans, genişletilebilirlik ve geliştirici deneyimi alanlarının tamamında büyük ilerleme kaydeden bir veri doğrulama kütüphanesi olarak konumlanıyor
  • Gelecekte ek tasarım yazıları ve güncellemelerin geleceği duyuruldu
  • Hem mevcut kullanıcılar hem de kütüphane geliştiricileri için geniş kapsamlı destek hazırlanıyor

Mutlu parsing'ler
— Colin McDonnell @colinhacks

İlgili okumalar

1 yorum

 
GN⁺ 2025-05-20
Hacker News görüşleri

  • Yazar, kendi görüşlerinin paylaşılmasını istiyor ve sürümleme yaklaşımını ayrıntılı biçimde açıklıyor; npm'in Zod gibi bir durumu ele almak için uygun olmadığını vurguluyor. Pek çok kütüphanenin Zod arayüzlerini/sınıflarını doğrudan içe aktarıp kullandığını, Zod büyük sürüm değiştirirse bu kütüphanelerin hepsinin aynı anda uyum sağlaması gerekeceğini ve bir sürüm patlaması yaşanabileceğini belirtiyor. Go'ya benzer şekilde, kırıcı değişiklikler için yeni bir alt yol ekleme yönteminin kullanıldığını, TypeScript ortamında zod@^3.25.0 ile "zod/v3" ve "zod/v4"ün aynı anda desteklenebildiğini ve bunun son kullanıcıya kademeli bir yükseltme yolu sunduğunu açıklıyor

    • Zod'a yapılan katkılar için teşekkür ediyor; özellikle tsc performansı ve discriminated unions iyileştirmeleri konusunda heyecanlı olduğunu söylüyor. Sürümleme yaklaşımını tamamen anladığını, ancak kendisi gibi transitive dependency çakışmalarından endişe etmeyen kullanıcılar için bunun tek başına 4.0.0 paketi olarak da sunulmasının güzel olabileceğini öneriyor. "zod/v4" olarak import değiştirmenin kodda gürültü yaratacağını ve IDE otomatik importlarıyla ek uğraş doğurabileceğini düşünüyor; yine de genel olarak çok umut verici bir yükseltme olduğunu belirterek teşekkür ediyor

    • Habere mobilde bakarken gözünden kaçtıysa affedilmesini istiyor ve .optional() ile ilgili en büyük sıkıntının bu kez çözülen ilk 9/10 sorun arasında olup olmadığını soruyor. Zod'un çok iyi olduğu için can sıkıcı yanlarına rağmen kullanmaya devam ettiğini ve harika bir kütüphane olduğunu söyleyerek teşekkür ediyor

    • Yeni Zod sürümüyle birlikte çok sayıda elle yapılmış hack kodunu kaldırabilecek olmaktan memnun olduğunu söylüyor. Yazım hatalarını azaltmak için bizzat zod-key-parser kullandığını, buna benzer bir özelliğin neden doğrudan kütüphanede yer almadığını merak ediyor; bunun kapsam dışı mı görüldüğünü yoksa henüz uygulanmadığını soruyor ve ilgili açık tartışmaları paylaşıyor

    • Kısa vadeli acıyı en aza indirmenin çoğu zaman en iyi yaklaşım olduğunu vurguluyor ve Python 2/3 geçişindeki büyük karmaşayı hatırlatıyor

    • Recursive type ile discriminated union yapısını aynı anda kullanırken, örneğin XML'i JSON içine gömmek gibi durumlarda, ciddi zorluk yaşadığını paylaşıyor ve bu güncellemeyle durumun çok daha iyi olmasını umuyor

  • zod/v4-mini importuna şüpheyle yaklaştığını söylüyor; bunun tersine bundle boyutunu artırabileceğini tahmin ediyor. Resmî belgelerde zod/v4ün çoğu durumda önerildiği yazdığı için uygulama geliştiricilerinin zod/v4 kullanacağını, ancak kütüphane yazarlarının bundle boyutunu azaltmak için zod/v4-miniyi de eklemesi halinde ikisinin de bundle'a girerek tekrar yaratabileceğinden endişe ediyor. Eğer zod/v4, zod/v4-mini için bir wrapper olsaydı bu sorunun azalabilir olup olmadığını soruyor

  • Zod 4'e geçişi kolaylaştırmak için v3 ve v4'ün zod@3.25 içinde birlikte sunulması yönteminin getirildiğini, bu yapının npm'in bağımlılık yönetimi sınırları yüzünden v4'ün v3 gibi görünmek zorunda kaldığı anlamına geldiğini eleştiriyor. npm'in peer dependencies sisteminin verimsizliğine işaret ediyor

    • Yazar, Go tarzı alt yol eklemeli sürümleme stratejisini yeniden açıklıyor. Bunun npm'in doğası nedeniyle Zod ekosistemine doğrudan uygulanmasının zor olduğunu, ancak v3 ve v4'ü aynı anda destekleyerek kademeli geçiş sağlama avantajı sunduğunu vurguluyor

    • Peer dependencies bozuk olduğu için v4'ün v3 gibi gösterildiği yönündeki önceki görüşe tam katılmadığını söylüyor. Bunun, kademeli geçiş için seçilmiş bir yöntem olduğunu; her şeyi yavaş yavaş zod/v4 ile değiştirdikten sonra tamamen v4'e geçmenin hedeflendiğini belirtiyor

    • İnsanların çok eleştirdiğini, ancak bunun aslında npm'in temel bir kusurundan çok, büyük değişiklikler içeren bir kütüphaneyi aşamalı biçimde güncellenebilir kılmak için alınmış pratik bir karar olduğunu savunuyor

    • Uzun zamandır yalnızca npm kullandığı için önyargılı olabileceğini söylüyor ama v3'ten v4'e bir anda toplu geçiş yapmak yerine kademeli destek sağlamanın bundan daha iyi bir yolu ne olabilirdi diye soruyor

    • Zod 4 beta ile zaten büyük iyileşmeler gördüğünü, ancak büyük bir kod tabanında modül çözümleme ayarlarının zorluğu yüzünden düzgün yükseltme yapamadığını anlatıyor. Keşke eski katman olmadan, yalnızca ana sürüm olarak da yayımlansaydı diyor. Yazarın "sürüm patlaması"nı önlemeye dönük açıklamasını paylaşıyor, ancak yine de v3 desteği sürerken geçişin şokunu azaltmanın mümkün olduğunu düşündüğünü ekliyor

  • Sunucudan dönen tiplerin endpoint'e göre değiştiği veya bazı alanların anonim kullanıcı örneğinde olduğu gibi null gelebildiği karmaşık durumlarda, sunucu yanıtının hangi tip modeliyle ele alınması gerektiğini soruyor. normalizeUser/normalizePost gibi çok sayıda fonksiyon yazdıkça yönetimin giderek karmaşıklaştığını belirtiyor ve bunun pratikte nasıl çözüldüğüne dair deneyim istiyor

    • Çözüm olarak bir discriminated union örneği veriyor. Şemanın ortak kısmını bir nesne olarak tanımlayıp, özel durumlar için bunu genişletme yaklaşımını açıklıyor. Çok fazla varyasyon olduğunda işin yine karmaşıklaşabileceğini, ancak bir schema validator ile en azından yapının sistemli tutulabileceğini söylüyor

    • İdeal olarak User tip yapısının tek bir kaynaktan, örneğin discriminated union biçiminde tanımlanmasının en iyisi olduğunu belirtiyor. Python backend varsayımıyla, birden fazla Pydantic model + union ve ardından OpenAPI/GraphQL code generation ile TypeScript istemci tipleri üretme yapısını öneriyor

    • Gerçek kullanım örneğini bilseler daha iyi yanıt verebileceklerini, ancak union type içine ayırt edici bir özellik, örneğin "user_type", eklenirse ilgili alanlara erişimin kolaylaşacağını açıklıyor. Böylece tip sistemi duruma göre uygun özellikleri anlayabiliyor

    • Sunucunun tipleri doğrudan dışa vermesi gerektiğini söylüyor. İstemci tarafında ayrı tipleri baştan yeniden yazmanın verimsiz olduğunu; Python backend için Pydantic ile OpenAPI şeması otomatik üretilip buradan TypeScript istemci tiplerinin türetilebileceğini anlatıyor

    • GraphQL'in bu tür kullanım senaryolarına uygun tasarlandığını belirtiyor. TypeScript GraphQL kütüphaneleriyle sorgu sonucunun biçiminin otomatik çıkarılabildiğini ve seçilen alanlara göre yanıt tiplerinin dinamik biçimde oluştuğunu örnekliyor

  • Zod 4'ün iyileşmiş olmasına rağmen ArkType'ın hâlâ çok daha hızlı olduğunu söylüyor. Yerleşik kütüphanelerde geriye dönük uyumluluk ve sözdizimini koruma gereği nedeniyle performans sınırları bulunduğunu, kendi proje analizleri sonucunda ArkType'ı performans ve TypeScript kullanım deneyimi nedeniyle seçtiğini belirtiyor

    • ArkType'ın hız metriklerini gördüğünü ama bunun pratikte neyi değiştirdiğini merak ettiğini söylüyor. Form doğrulama gibi genel senaryolarda etkisinin az göründüğünü, belki ultra hızlı API girdi doğrulaması gibi performansa duyarlı yerlerde mi kullanıldığını soruyor

    • ArkType araştırmada yer almamış olsa da TypeScript kullanım deneyimini önemseyerek buna baktığını, yine de Zod'dan geçmeyi planlamadığını söylüyor

    • ArkType deneyiminin kendisi için oldukça zor olduğunu, Zod'un ise çok daha kullanışlı geldiğini ve bu yüzden tercih ettiğini belirtiyor

    • TypeBox yerine ArkType'ı seçmek için özel bir nedeni olup olmadığını soruyor

  • Zod ekibini yeni sürüm için kutluyor. Migration guide'daki kırıcı değişikliklerin çokluğu nedeniyle, Zod'a büyük ölçüde bağımlı projelerde bunun ciddi bir yük ve yönetim zorluğu yaratabileceğinden endişe ettiğini söylüyor. Eski frontend projelerini sürdürme deneyimine dayanarak, her kütüphanede büyük değişiklikler ve yetersiz belgeler görmenin bugünkü JS ekosistemindeki can sıkıcı yönlerden biri olduğunu ifade ediyor

    • Birkaç büyük Next.js uygulaması yönettiğini, son bir yılda Next.js 14→15, Next.js pages→app router, React 18→19, Eslint 8→9, Tailwind 3→4 gibi çok büyük ve zor geçişler yaşadığını ve gerçekten yıpratıcı olduğunu anlatıyor. Hatta bazen keşke bunu Django ile yapmış olsaydık diye düşündüğünü, özellikle de Tailwind 3→4 geçişinin şaşırtıcı biçimde en acı verici olanı olduğunu söylüyor

    • Bu tür sorunları hafifletmek için eşzamanlı mini sürüm stratejisinin getirildiğini, bunun kademeli geçişi kolaylaştırdığını ve tree-shaking verimliliği açısından mini sürümün alternatiflere karşı rekabet edebilmek için gerekli olduğunu açıklıyor

    • LLM gibi araçlarla migration'ın sanıldığı kadar zor olmayabileceğini öneriyor

  • Zod'un mevcut diğer alternatiflere göre çok daha iyi olduğunu söylüyor. Ancak web geliştirmede aynı veri yapısını birden fazla şekilde tanımlamak zorunda kalmanın can sıkıcı bir gerçek olduğunu; JS girdi doğrulaması, Swagger ile API tanımı, sunucu ve istemci için ayrı tanımlar derken bunun fazlasıyla tekrar ve uğraş yarattığını belirtiyor

    • TypeScript'in yalnızca statik kontrol aracı olarak kalmasından memnun olmadığını; çalışma zamanında kontrol istemese bile sınıf/fonksiyon/nesne tip verilerinin dışarıya kolayca aktarılabilmesini istediğini söylüyor. Şu anda birçok aracın kendi modelini ve builder yapısını tanımlamak zorunda kalması nedeniyle tekrarın kaçınılmaz olduğunu, standartlaşma girişimi olan Standard Schema projesinin büyük doğrulama kütüphaneleriyle bütünleşmeye başladığını ama API tanımı ve ORM tarafına genişlemesinin henüz erken aşamada olduğunu paylaşıyor

    • Bu tür araçların asıl değerinin, bir şeyi tek sefer tanımlayıp type safety'yi tüm uygulamaya yayabilmek olduğunu söylüyor. Zod şemasının bir tür tek doğruluk kaynağı olarak kullanılabileceğini vurguluyor

    • Bu kadar karmaşık yapılardan rahatsız olan kişiler arasında bile, gerçekte her şeyi TypeScript'le, Zod dahil, tek yerde birleştirme önerisine karşı çıkanların az olmadığını da ekliyor

    • Tüm API'lerin ve sistemlerin sürekli değişim ve deneme hâlinde olduğunu, katmanların artmasının bir dezavantaj olduğunu ama "projede iş yürüsün yeter" denilen ortamlarda bunun sonunda yalnızca daha fazla iş çıkardığını söylüyor

    • Genel olarak trpc gibi uçtan uca type safety sağlayan yaklaşımların kullanılabileceğini, ancak bunun için hem frontend hem backend'in TypeScript olması gerektiğini ve web dışı platformlarda, örneğin mobilde, bunun pratikte zorlaştığını belirtiyor

  • Uzman olmadığını söylüyor ama schema tabanlı JSON-Schema'nın, TypeScript dışındaki dillerde de validator uygulanabildiği için iyi bir seçenek olabileceğini düşünüyor. ajv.js.org gibi kütüphaneler örneği üzerinden Zod ile nasıl kıyaslanacağını soruyor

    • Zod'un yalnızca JSON biçimlerini değil, tüm JS nesnelerini de, örneğin tarihleri ve sınıf örneklerini, doğrulayabildiğini; yani JSON'da temsil edilemeyen veriler üzerinde de çalışabildiğini açıklıyor. Ayrıca JSON dönüştürme sürecinde de kullanılabileceğini; örneğin bir ISO tarih string'ini doğrulayıp Date nesnesine dönüştürebildiğini söylüyor

    • Zod 4'ün artık Zod şemalarını JSON-Schema'ya dönüştürmeyi desteklediğini, eskiden bunun için harici kütüphane gerektiğini belirtiyor. Zod'un asıl farkının preprocess/refine özellikleri olduğunu; doğrulama öncesi callback ekleyerek örneğin MM/DD/YYYY biçimini DD/MM/YYYY biçimine çevirip sonra doğrulama yapılabildiğini ve JSON-Schema'da bunun mümkün olmadığını vurguluyor

    • JSON-Schema'nın da iyi bir seçenek olduğunu, bu senaryoda üretim için TypeBox'ın uygun olabileceğini; avj kullanılabileceği gibi kendi doğrulama sisteminin de tercih edilebileceğini söylüyor. Kendi doğrulama sisteminin daha hızlı olduğunu ama yalnızca senkron çalıştığını, avj'nin ise asenkron doğrulamayı da desteklediğini ve daha derin doğrulamalar için avantaj sağladığını belirtiyor

    • Birden fazla dilde kullanılacaksa JSON-Schema'nın en yaygın çözüm olduğunu, OpenAPI ile sarıldığında otomatik API dokümantasyonu da üretilebildiğini ekliyor

  • Zod'u yeni projede kullanmaya yeni başladığını ve bu sürüm zamanlamasının tam isabet olduğunu söylüyor. Her şey plana göre gitseydi v4'e geçmek için çok daha fazla değişiklik yapması gerekeceğini, bu yüzden zamanlamanın mükemmel olduğunu belirtiyor

  • Beklediğinden çok daha fazla olumsuz yorum görünce şaşırdığını söylüyor. v4'ün ilk sürümlerini test ederken yeni API'yi beğendiğini ama migration yolunun nasıl olacağı konusunda endişelendiğini, hatta ayrı bir paket adıyla yayımlanmasının daha iyi olup olmayacağını düşündüğünü anlatıyor. Ancak yazarın seçtiği yöntemin sorunu çok iyi çözdüğünü ve bu sayede bağımlılık güncellemelerini beklemeden hemen v4'ü benimseyebildiğini söylüyor

    • Kendisi de doğrulama gibi alanlarda her şeyi tek seferde migrate etmenin gerçekçi olmadığını düşündüğünü ve mevcut yaklaşımın pratikte en iyi seçenek olduğunu belirtiyor