6 TypeScript Doğrulama Kütüphanesini Karşılaştırdım: Beni Şaşırtanlar 🤔

TypeScript projelerinde çalışma zamanı (runtime) doğrulaması gerektiğinde tartışma genellikle "Hangi kütüphaneyi kullanmalıyım?" sorusuna dönüşür. Zod, Valibot, ArkType, typia mı, yoksa sadece basit bir type guard (tip koruyucusu) yazmak mı?

Asıl sormamız gereken soru şudur: Gerçekten aynı problemi çözen kütüphaneleri mi karşılaştırıyoruz?

Eğer tek ihtiyacımız if (isUser(input)) { input.name; } gibi basit bir kontrolse, tam kapsamlı bir şema sistemine ihtiyacımız olmayabilir. Ancak ihtiyacımız olan şeyler şunlarsa:

• Yapılandırılmış doğrulama hataları (structured validation errors)
• Veri dönüşümleri (transformations)
• Ayrıştırma (parsing) işlemleri
• Şema üst verisi (schema metadata)
• Çatı (framework) entegrasyonları

Bu durumda küçük bir boolean kontrolü (type guard) yeterli olmayacaktır. "Hangi doğrulayıcı en iyisi?" diye sormak yerine, aynı User doğrulamasını 7 farklı yaklaşımla (elle yazılmış TypeScript predicate guard, is-kit, Runtypes, Valibot, Zod, ArkType, typia) uygulayarak tarayıcı paket boyutu ve çalışma zamanı performansını karşılaştırmak çok daha öğreticidir.

Buradaki en zor kısım yedi doğrulayıcıyı derlemek değil, yedisinin de çalışma zamanında tam olarak aynı sözleşmeyi (runtime contract) ifade etmesini sağlamaktır. Örneğin, "en fazla 100 karakterlik bir metin" kuralı bile kütüphaneler arasında farklı çalışma zamanı davranışları üretebilir.

🧪 Doğrulayacağımız User Tipi#

Karşılaştırmada kullanılan ortak User veri yapısı şu alanlardan oluşur: id, name, age, role ("admin" | "user"), tags (string[]) ve alt nesne olarak profile (bio ve active).

Bu tip için belirlenen çalışma zamanı (runtime) kuralları şunlardır:

• id bir metin (string) olmalıdır
• name 1 ile 100 arasında UTF-16 kod birimi içermelidir
• age 18 ile 120 arasında bir tam sayı (integer) olmalıdır
• role tam olarak "admin" veya "user" olmalıdır
• tags metinlerden oluşan bir dizi olmalıdır
• profile.bio bir metin olmalıdır
• profile.active bir boolean olmalıdır
• Kök dizinde ve profile içinde fazladan anahtarlar (extra keys) reddedilmelidir
• Değerler otomatik tip dönüşümüne (coercion) uğramamalıdır

Bu karşılaştırmada ana girdi alanı standart JSON'dan çözümlenmiş verilerdir. Bu ayrım önemlidir; çünkü JavaScript çalışma zamanında kalıtımlı özellikler, seyrek diziler (sparse arrays), semboller, getter fonksiyonları ve sayılabilir olmayan (non-enumerable) anahtarlar gibi beklenmedik durumlarla karşılaşabiliriz.

1. ✍️ Elle Yazılmış Guard — Bazen Bir Guard Yeterlidir#

En sade seçenek, hiçbir harici doğrulama kütüphanesi kullanmadan TypeScript predicate (value is User) ile elle yazılmış bir JavaScript kontrol fonksiyonu oluşturmaktır.

Bu yaklaşımda öncelikle değerin null veya dizi olmayan bir nesne (Record<string, unknown>) olup olmadığını kontrol eden bir isRecord yardımcısı ve nesnenin yalnızca beklenen anahtarlara sahip olduğunu (Object.keys ve Object.hasOwn ile) doğrulayan bir hasExactKeys fonksiyonu tanımlanır. Ardından isUser fonksiyonu içinde kök nesnenin ve profile alt nesnesinin anahtarları, metin uzunlukları (name.length), tam sayı ve aralık kuralları (Number.isInteger(value.age)) tek tek kontrol edilir.

Pratik Çıkarımlar ve Geliştirici Yorumu#

• İhtiyaca Göre Araç Seçimi: Sadece gelen verinin tipini daraltmak (type narrowing) istiyorsanız sıfır bağımlılıklı bir type guard en hafif çözümdür. Ancak API sınırlarında detaylı hata mesajları ve veri ayrıştırma gerekiyorsa şema kütüphaneleri kaçınılmazdır.
• Sözleşme Uyuşmazlığı Riski: Farklı doğrulama araçları fazladan anahtarları (extra keys) veya karakter uzunluklarını farklı ele alabilir. Kütüphane seçerken sadece popülerliğe değil, uygulamanızın çalışma zamanı kurallarını ne kadar kesin karşıladığına odaklanın.
• Bakım Maliyeti: Elle yazılan guard fonksiyonları paket boyutunu artırmaz ancak şema büyüdükçe okunabilirliği ve bakımı zorlaşır.