Rilis Zod 4

• Zod, library deklarasi skema dan validasi, merilis versi 4 stabil dengan peningkatan performa utama dan fitur yang telah lama diminta
• Ada peningkatan besar pada kecepatan dan ukuran bundle, dan versi mini baru (v4-mini) memangkas ukuran bundle secara signifikan
• Ditambahkan registry metadata baru, konversi JSON Schema, serta fitur inferensi tipe rekursif
• Pengalaman pengembang ditingkatkan melalui kustomisasi pesan error dan sistem locale multibahasa
• Skalabilitas makin tinggi dengan hadirnya subpaket core yang dapat dimanfaatkan untuk membangun library ke depan

---

Pengenalan Zod 4

Panduan rilis utama

• Setelah 1 tahun pengembangan aktif, Zod 4 dirilis sebagai versi stabil
• Pengembangan dilakukan dengan dukungan OSS Fellowship dari Clerk
• Saat ini didistribusikan berdampingan dengan Zod 3, sehingga migrasi bertahap ke Zod 4 menjadi lebih mudah
• Panduan detail mengenai beberapa perubahan breaking dapat dilihat di Migration guide

Latar belakang pertumbuhan

• Dibandingkan Zod 3 yang dirilis pada 2021, Zod 4 mengalami pertumbuhan eksponensial dalam jumlah GitHub stars dan unduhan mingguan
• Zod 4 jauh lebih cepat, lebih ramping, dan efisiensi compiler TypeScript ditingkatkan
• 9 isu utama yang telah lama banyak diminta berhasil diselesaikan

Benchmark dan performa

• Peningkatan kecepatan:
  • Parsing string: 14,71 kali lebih cepat
  • Parsing array: 7,43 kali lebih cepat
  • Parsing object (safeParse): 6,5 kali lebih cepat
• Tersedia skrip untuk menjalankan benchmark langsung dari repo
• Berkat struktur generic yang ditingkatkan, performa kompilasi saat method chaining seperti .extend() dan .omit() meningkat 10 kali lipat
• Kecepatan kompilasi TypeScript meningkat signifikan pada skema dan codebase berskala besar

Ukuran bundle dan Zod Mini

• Ukuran bundle dasar berkurang 57%, sehingga v4 berukuran 2,3 kali lebih kecil dibanding v3
• zod/v4-mini menyediakan API berbasis fungsi yang tree-shakeable, dan mengurangi ukuran bundle hingga 85%
• Perbedaan API antara core dan v4-mini dirangkum secara detail di dokumentasi resmi
• Strukturnya dirancang agar bundler dapat dengan mudah menghapus method yang tidak digunakan

Registry metadata dan dukungan JSON Schema

• typed metadata dapat didaftarkan dan dikelola pada skema dengan strong typing
• Registry global (z.globalRegistry) menyediakan pemrosesan metadata kompatibel JSON Schema dan penyertaan otomatis
• .meta() dan .describe() memudahkan dokumentasi skema
• Dengan .toJSONSchema(), skema dapat dikonversi ke format JSON Schema, dengan metadata diterapkan secara otomatis

Inferensi otomatis tipe rekursif

• Tipe object rekursif dan tipe mutual-recursive dapat didefinisikan dan diinferensikan secara alami tanpa type casting terpisah
• Kegunaannya meningkat besar dibanding pola Zod 3 sebelumnya
• Bahkan pada tipe rekursif dan mutual-recursive, semua fitur method skema tetap dapat digunakan

Tipe file dan fitur validasi

• Tipe file() baru memungkinkan validasi instance File
• Menyediakan validasi berbagai batasan file seperti ukuran file (min, max) dan tipe MIME

Sistem pesan error dan locale

• Dengan API locale global (z.locales), dukungan multibahasa untuk pesan error menjadi memungkinkan
• Fungsi resmi z.prettifyError mendukung formatting error yang ramah pengguna

Fungsi format dan template literal

• Format string yang sudah ada (email, dll.) dipromosikan menjadi fungsi level atas sehingga keterbacaan dan tree shaking meningkat
• Menyediakan berbagai opsi regex email untuk memenuhi kebutuhan validasi yang beragam
• Dukungan tipe template literal: pola string dan kombinasi kompleks yang dapat diekspresikan di sistem tipe menjadi mudah diimplementasikan

Format angka dan bigint yang baru ditambahkan

• Mendukung tipe integer dan floating point berlebar tetap (int32, uint64, dll.)
• Dapat membuat skema dengan batasan minimum/maksimum yang ditambahkan otomatis dalam rentang aman

Pengenalan z.stringbool

• Mendukung parsing boolean berbasis string (yes, no, dll.), termasuk parsing gaya environment variable
• Nilai truthy/falsy dapat dikustomisasi

Penyatuan API kustomisasi error

• Melalui parameter error yang disatukan, struktur pesan error dan logika penanganannya menjadi lebih rapi
• Berbagai API terkait error sebelumnya (message, invalid_type_error, errorMap) kini deprecated

Peningkatan inti lainnya

• discriminated unions mendukung beragam skema, nesting, dan kombinasi
• .literal() dapat menerima beberapa nilai sekaligus
• Validasi kustom seperti .refine() diintegrasikan dengan cara yang lebih intuitif
• Dengan .overwrite() terkait transform, pascapemrosesan dapat dilakukan tanpa mengubah tipe hasil transformasi

Ekstensibilitas library dan core baru

• Melalui zod/v4/core, fungsi inti dipisahkan ke subpaket tersendiri sehingga integrasi dan ekstensi ke berbagai library dan platform menjadi memungkinkan
• Tersedia dokumentasi panduan dan contoh ekstensi untuk pembuat library

Penutup

• Zod 4 memantapkan posisinya sebagai library validasi data yang sangat meningkatkan keamanan tipe, performa, ekstensibilitas, dan pengalaman pengembang
• Postingan desain tambahan dan update berikutnya telah diumumkan
• Dukungan luas disiapkan baik untuk pengguna lama maupun pembuat library

Semoga pengalaman parsing Anda menyenangkan
— Colin McDonnell @colinhacks

[GN⁺]

Komentar Hacker News

• Penulis sendiri meminta masukan dan memberikan penjelasan rinci tentang cara pengelolaan versi, menekankan bahwa npm tidak cocok untuk menangani situasi seperti Zod, serta menyebut banyak library langsung mengimpor dan memakai antarmuka/kelas Zod; jika Zod mengalami perubahan versi mayor, semua library tersebut harus menyesuaikan secara bersamaan dan bisa memicu ledakan versi. Seperti di Go, perubahan yang tidak kompatibel sebaiknya ditangani dengan menambahkan jalur subpath baru; di lingkungan TypeScript, zod@^3.25.0 saja bisa mendukung "zod/v3" dan "zod/v4" sekaligus, sehingga menyediakan jalur upgrade bertahap bagi pengguna akhir.

  • Mengucapkan terima kasih atas kontribusi pada Zod, dan sangat menantikan peningkatan performa tsc serta perbaikan pada discriminated unions. Walau cukup memahami pendekatan pengelolaan versinya, ia mengusulkan agar bagi pengguna seperti dirinya yang tidak khawatir soal benturan dependensi transitif, akan bagus juga jika tersedia paket tunggal dalam bentuk 4.0.0. Ia memperkirakan keharusan mengubah import menjadi "zod/v4" akan menambah noise di kode dan menimbulkan kerepotan tambahan seperti konflik auto-import di IDE. Meski begitu, secara keseluruhan ia menilai ini upgrade yang sangat menjanjikan dan menyampaikan terima kasih.

  • Mengatakan sedang membaca artikel dari ponsel jadi mohon dimaklumi jika ada yang terlewat, lalu bertanya apakah ketidaknyamanan terbesar terkait .optional() termasuk dalam penyelesaian 9 dari 10 isu teratas kali ini. Ia menyebut Zod sangat luar biasa sehingga tetap dipakai meski ada ketidaknyamanan, dan berterima kasih atas library yang hebat ini.

  • Berterima kasih karena bisa menghapus banyak kode hack manual di versi baru Zod. Ia sendiri memakai zod-key-parser untuk mengurangi typo, dan penasaran kenapa fitur seperti ini tidak ada secara bawaan di library, apakah dianggap di luar cakupan, atau memang belum diimplementasikan. Ia juga membagikan diskusi terbuka terkait.

  • Menekankan bahwa cara yang meminimalkan rasa sakit jangka pendek sering kali adalah yang terbaik, sambil menyinggung kekacauan besar saat migrasi Python 2/3.

  • Membagikan pengalaman pernah sangat kesulitan ketika memakai tipe rekursif dan bentuk discriminated union secara bersamaan, misalnya saat XML disisipkan di dalam JSON, dan berharap pembaruan kali ini banyak memperbaiki keadaan.

• Menyatakan ragu terhadap import zod/v4-mini, dan menduga ini justru akan memperbesar ukuran bundle. Karena dokumentasi resmi mengatakan zod/v4 direkomendasikan untuk kebanyakan kasus, developer aplikasi akan memakai zod/v4, tetapi jika penulis library juga menambahkan zod/v4-mini demi menghemat ukuran bundle, keduanya bisa sama-sama masuk ke bundle dan menimbulkan duplikasi. Ia bertanya apakah masalah ini bisa dikurangi jika zod/v4 hanyalah wrapper dari zod/v4-mini.

• Untuk mempermudah migrasi Zod 4, diperkenalkan cara di mana v3 dan v4 disediakan bersamaan lewat zod@3.25; pendekatan ini dikritik karena, dikombinasikan dengan keterbatasan pengelolaan dependensi npm, membuat v4 harus tampak seperti v3. Ia menyoroti ketidakefisienan sistem peer dependencies di npm.

  • Penulis sendiri kembali menjelaskan strategi versi dengan penambahan subpath ala Golang. Meski sulit diterapkan di ekosistem Zod karena karakteristik npm, ia menekankan kelebihannya: mendukung v3 dan v4 sekaligus serta menyediakan migrasi bertahap.

  • Tidak sepenuhnya setuju dengan pendapat sebelumnya bahwa peer dependencies yang rusak membuat v4 menyamar sebagai v3. Ia menekankan bahwa ini adalah cara untuk migrasi bertahap: mengganti satu per satu ke zod/v4, lalu akhirnya upgrade penuh ke v4.

  • Menegaskan bahwa meski banyak orang mengkritik, ini bukan semata keterbatasan mendasar npm, melainkan keputusan praktis agar library dengan perubahan besar tetap bisa diubah secara bertahap.

  • Mengatakan mungkin bias karena sudah lama hanya memakai npm, tetapi penasaran metode apa yang lebih baik untuk mendukung transisi dari v3 ke v4 secara bertahap alih-alih memindahkan semuanya sekaligus.

  • Menyebut bahwa walau sudah merasakan banyak perbaikan lewat beta Zod 4, ia tetap belum bisa upgrade dengan benar di codebase besar karena sulitnya pengaturan module resolution. Ia berharap ini juga dirilis murni sebagai versi mayor tanpa lapisan legacy. Ia membagikan penjelasan penulis tentang pencegahan “ledakan versi”, namun menurutnya dukungan paralel untuk v3 juga bisa meredam guncangan.

• Bertanya, dalam kasus rumit seperti tipe yang dikembalikan server berbeda untuk setiap endpoint, atau beberapa field bisa bernilai null seperti pada pengguna anonim, model tipe seperti apa yang sebaiknya dipakai untuk menangani respons server. Ia mengeluhkan bahwa membuat banyak fungsi seperti normalizeUser/normalizePost makin lama makin sulit dikelola, dan meminta orang lain berbagi cara menanganinya di dunia kerja.

  • Memberikan solusi dengan contoh discriminated union: mendefinisikan bagian skema yang sama sebagai objek lalu memperluasnya sesuai situasi tertentu. Ia menasihati bahwa jika kasusnya sangat beragam memang akan tetap kompleks, tetapi setidaknya schema validator membantu menjaganya tetap sistematis.

  • Secara ideal, yang terbaik adalah menetapkan struktur tipe User sebagai satu sumber kebenaran, misalnya dalam bentuk discriminated union. Dengan asumsi backend Python, ia mengusulkan struktur berupa beberapa model Pydantic + union, lalu pembuatan tipe klien TypeScript melalui code generation OpenAPI/GraphQL.

  • Mengatakan akan bisa memberi jawaban lebih baik jika ada contoh penggunaan nyata, tetapi menjelaskan bahwa menambahkan properti pembeda pada union type, misalnya "user_type", memudahkan akses ke field masing-masing. Sistem tipe lalu bisa mengenali properti yang tepat sesuai konteks.

  • Menegaskan bahwa server seharusnya mengekspor tipenya sendiri. Menulis ulang tipe secara terpisah di klien satu per satu itu tidak efisien. Untuk backend Python, ia menjelaskan cara memakai Pydantic agar spesifikasi OpenAPI dihasilkan otomatis lalu tipe untuk klien TypeScript dibuat darinya.

  • Menyebut GraphQL memang dirancang cocok untuk kasus seperti ini; dengan library GraphQL di TypeScript, bentuk hasil query bisa diinferensikan otomatis, dan tipe respons dapat dibentuk dinamis berdasarkan field yang dipilih.

• Menyebut bahwa walaupun Zod 4 membaik, ArkType tetap jauh lebih cepat. Pada library lama, ada batas performa karena harus menjaga kompatibilitas mundur dan sintaks yang ada. Dari analisis proyeknya sendiri, alasan memilih ArkType adalah performa dan kemudahan penggunaan di TypeScript.

  • Ia melihat metrik kecepatan ArkType, tetapi bertanya dampak nyatanya seperti apa dalam penggunaan sebenarnya. Dalam situasi umum seperti validasi form tampaknya pengaruhnya kecil, jadi ia penasaran apakah ini dipakai di area sensitif performa seperti validasi input API berkecepatan sangat tinggi.

  • Menyebut ArkType tidak masuk dalam riset, tetapi memang sedang mencarinya sambil mempertimbangkan kemudahan pakai di TypeScript. Meski begitu, ia tidak berencana pindah dari Zod.

  • Mengatakan pengalaman memakai ArkType sangat sulit dan ia lebih menyukai Zod karena lebih mudah dipakai.

  • Bertanya alasan khusus memilih ArkType dibanding TypeBox.

• Mengucapkan selamat kepada tim Zod atas rilisan baru ini. Namun melihat banyaknya breaking changes di migration guide, ia khawatir proyek besar yang sangat bergantung pada Zod akan terbebani dan sulit dikelola. Dari pengalamannya memelihara proyek frontend lama, banyak library mengalami perubahan besar dan dokumentasinya kurang, sehingga ia menyayangkan arah perkembangan JS saat ini.

  • Ia mengelola beberapa aplikasi Next.js besar, dan selama setahun terakhir harus melalui perubahan besar dan sulit seperti Next.js 14→15, Next.js pages→app router, React 18→19, Eslint 8→9, Tailwind 3→4, dan itu benar-benar melelahkan. Ia bahkan sempat berpikir lebih baik membangunnya dengan Django. Ia juga mengenang bahwa migrasi Tailwind 3→4 ternyata yang paling menyakitkan.

  • Dijelaskan bahwa untuk meredakan masalah seperti ini, diperkenalkan strategi menyediakan edisi mini secara bersamaan. Ini mempermudah transisi bertahap, dan dari sisi optimalitas tree-shaking, kehadiran mini dianggap perlu untuk menghadapi alternatif lain.

  • Menyarankan agar memanfaatkan alat seperti LLM supaya migrasi tidak terlalu sulit.

• Menyebut Zod jauh lebih unggul dibanding banyak alternatif yang ada, tetapi dalam pengembangan web kenyataannya struktur data yang sama harus dijelaskan dengan banyak cara. Validasi input JS, spesifikasi API lewat Swagger, definisi terpisah untuk server dan klien, semuanya terasa terlalu berulang dan merepotkan.

  • Ia menyayangkan TypeScript yang tetap bersikeras sebagai alat khusus pemeriksaan statis. Bukan berarti ia ingin runtime check juga, tetapi ia berharap data tipe dari class/fungsi/objek bisa lebih mudah dipakai ke luar. Saat ini banyak alat harus mendefinisikan model dan builder masing-masing, sehingga duplikasi tak terhindarkan. Ia membagikan bahwa upaya standardisasi lewat proyek Standard Schema mulai menunjukkan tanda integrasi dengan library validasi utama, tetapi perluasan ke spesifikasi API dan ORM masih tahap awal.

  • Menekankan bahwa inti alat semacam ini adalah cukup mendefinisikan sekali lalu type safety bisa disebarkan ke seluruh aplikasi. Skema Zod dapat dijadikan semacam single source of truth.

  • Ia juga menambahkan bahwa di antara orang-orang yang merasa struktur seruwet ini merepotkan, banyak yang justru enggan menerima usulan untuk menyatukan semuanya hanya dengan TypeScript saja, termasuk Zod.

  • Menyebut bahwa semua API dan sistem selalu berubah dan bereksperimen. Banyaknya lapisan kompleks memang sisi negatif, tetapi dalam situasi “asal proyek berjalan baik” pada akhirnya ini tetap menciptakan lebih banyak pekerjaan.

  • Secara umum ia menyebut end-to-end type safety seperti trpc juga bisa dipakai, tetapi untuk itu frontend dan backend harus sama-sama memakai TypeScript, dan akan sulit dipakai untuk platform non-web seperti mobile; ini dianggap sebagai batasan praktis di dunia kerja.

• Mengatakan dirinya bukan ahli, tetapi karena berbasis skema, JSON-Schema mungkin pilihan yang baik karena validator-nya bisa diimplementasikan di banyak bahasa selain TypeScript. Ia bertanya bagaimana perbandingannya dengan Zod, sambil memberi contoh library seperti ajv.js.org.

  • Dijelaskan bahwa Zod tidak hanya bisa memvalidasi bentuk JSON, tetapi juga seluruh objek JS seperti tanggal, instance class, dan data lain yang tidak bisa direpresentasikan sebagai JSON. Zod juga dapat dipakai dalam proses konversi JSON, sehingga skema bisa ditulis berbasis string dan, misalnya, memvalidasi lalu mengubah ISO date string menjadi objek Date.

  • Zod 4 mendukung konversi skema Zod ke JSON-Schema, yang sebelumnya memerlukan library eksternal. Pembeda besar Zod adalah fitur preprocess/refine, yang memungkinkan penambahan callback sebelum validasi, misalnya mengubah MM/DD/YYYY menjadi DD/MM/YYYY sebelum divalidasi; ditekankan bahwa fleksibilitas seperti ini tidak ada di JSON-Schema.

  • JSON-Schema juga disebut pilihan yang baik, dan dalam kasus ini TypeBox cocok untuk pembuatannya. Bisa memakai avj atau sistem validasi bawaannya sendiri; validasi bawaan lebih cepat tetapi hanya sinkron, sementara avj juga mendukung validasi asinkron sehingga lebih menguntungkan bila perlu validasi mendalam.

  • Jika ingin dipakai di banyak bahasa, JSON-Schema adalah yang paling umum; bila dibungkus dengan OpenAPI, kelebihannya adalah dokumentasi API juga bisa dihasilkan otomatis.

• Mengatakan baru saja mulai mengadopsi Zod di proyek baru, dan sangat senang waktu rilis ini terasa pas sekali; kalau sesuai rencana semula, ia mungkin harus melakukan banyak perubahan untuk migrasi ke v4, jadi timing ini terasa sempurna.

• Bereaksi kaget karena ternyata ada lebih banyak komentar negatif dari yang ia duga. Saat menguji versi awal v4 ia menyukai API baru, tetapi khawatir tentang jalur migrasinya, sampai sempat mempertimbangkan usulan merilisnya dengan nama paket terpisah. Namun ia menilai pendekatan penulis justru menyelesaikan masalah ini dengan sangat cemerlang, sehingga orang bisa langsung mengadopsi v4 tanpa harus menunggu dependensi diperbarui.

  • Ia juga merasa bahwa di area seperti validasi, tidak realistis mengharapkan semua orang bisa memigrasikan semuanya sekaligus, dan menilai pendekatan sekarang sebagai yang paling optimal secara praktis.