Standard Schema - TypeScript doğrulaması için ortak arayüz

• JavaScript/TypeScript tabanlı şema kütüphanelerinin ortak bir arayüz uygulaması için tasarlanmış bir spesifikasyon
• Amaç, her kütüphanede kullanıcının tanımladığı tür doğrulama mantığının yeniden kullanılabilmesini sağlayarak, araçların ayrı adaptörler olmadan birbiriyle uyumlu çalışmasını mümkün kılmak
• Zod, Valibot, ArkType gibi başlıca kütüphanelerin geliştiricileri tarafından ortaklaşa tasarlandı

Başlıca arayüz (StandardSchemaV1)

• Tüm spesifikasyon ~standard adlı nesne özelliği üzerinden uygulanır
• ~standard içinde version, vendor, validate, types gibi zorunlu özellikler bulunur
• validate fonksiyonu başarılı olduğunda value, başarısız olduğunda ise issues dizisini döndürür
• types özelliği sayesinde TypeScript'te şemanın girdi (input) ve çıktı (output) türleri çıkarılabilir
• Tüm güncellemeler, major sürüm değişikliği olmadığı sürece geriye dönük uyumluluğu korur

Tasarım hedefleri

• Çalışma zamanı doğrulama desteği: Hata bilgilerini standart bir biçimde iletir
• Statik tür çıkarımı desteği: TypeScript tabanlı kütüphanelerin çıkardığı tür bilgisini açıkça görünür kılar
• Sadelik: Mevcut kütüphane fonksiyonlarına yalnızca birkaç satır eklenerek uygulanabilir
• API çakışmalarını önleme: Her şeyi yalnızca ~standard ad alanına koyarak mevcut API ile çakışmayı engeller
• Geliştirici deneyimini koruma: ~standard gibi tilde (~) ile başlayarak otomatik tamamlamada önceliği düşürür

Hangi kütüphaneler bunu uyguluyor?

• Zod, Valibot, ArkType, Arri Schema, TypeMap gibi kütüphaneler şimdiden Standard Schema desteği sunuyor
• tRPC, TanStack Form, TanStack Router, Hono Middleware gibi araçlar da Standard Schema tabanlı kullanıcı şemalarını kabul ediyor

Spesifikasyon kendi kütüphanenize nasıl uygulanır?

• StandardSchemaV1 arayüzünü kütüphanenize kopyalayıp ~standard özelliğini ekleyin
• validate fonksiyonunu mevcut doğrulama fonksiyonuna bağlayarak, başarı durumunda { value }, hata durumunda { issues } döndürecek şekilde düzenleyin
• Gerekirse asenkron doğrulama da mümkündür, ancak senkron doğrulama önerilir

Standard Schema ile kullanıcı tanımlı şema nasıl alınır?

• Şema kütüphanesi olmadan doğrudan kullanmak için @standard-schema/spec paketini kurabilir veya arayüzü kopyalayabilirsiniz
• standardValidate örneğindeki gibi, standart arayüze sahip bir şema ise hangi kütüphaneden gelirse gelsin aynı şekilde doğrulama yapılabilir
• Yalnızca senkron doğrulamaya izin vermek istiyorsanız, validate dönüş değerinin Promise olup olmadığını kontrol edip buna göre istisna fırlatabilirsiniz

SSS

• @standard-schema/spec bağımlılığını eklemek gerekir mi?: Bunu bağımlılık olarak eklemek zorunlu değildir; kopyalayıp kullanabilirsiniz
• dev dependency olarak eklenemez: Kütüphanenin public API'sinin bir parçası olduğu için gerçek dağıtım ortamında da kullanılabilir olmalıdır
• ~standard önünde neden tilde (~) kullanılıyor?: Otomatik tamamlamada diğer özelliklerin ardından görünmesi amaçlanmıştır
• Neden Symbol yerine string anahtar kullanılıyor?: Çünkü TypeScript'te Symbol anahtarları otomatik tamamlama sıralaması ve tür çıkarımı açısından sorun yaratabilir