JSON ke TypeScript

Apa yang Sebenarnya Dilakukan Konverter

Konverter mem-parsing JSON Anda, menelusuri setiap nilai, dan menghasilkan sekumpulan deklarasi interface TypeScript yang mendeskripsikan bentuknya. Objek bersarang masing-masing mendapat antarmuka bernama sendiri, yang diturunkan dari kunci properti induk dalam PascalCase (field user menjadi antarmuka User). Ketika dua objek bersarang berbenturan pada nama yang sama, yang kedua mendapat sufiks numerik (User, User2). Pada level root, array menjadi alias type Root = RootItem[]; ditambah antarmuka RootItem; objek menjadi antarmuka Root tunggal (atau nama apa pun yang Anda masukkan di kolom «nama root»).

Contoh input dan output:

// Input
{
  "id": 42,
  "name": "Ada",
  "active": true,
  "tags": ["admin", "billing"],
  "profile": { "bio": "Programmer", "link": null }
}

// Output
export interface Root {
  id: number;
  name: string;
  active: boolean;
  tags: string[];
  profile: Profile;
}

export interface Profile {
  bio: string;
  link: unknown;
}

Pemetaan Tipe JSON → TypeScript

Untuk array objek di level root, konverter menggabungkan kunci dari semua item menjadi satu antarmuka representatif. Itu adalah perkiraan yang memadai ketika item berbagi bentuk yang sama, tetapi kehilangan informasi ketika bentuknya benar-benar berbeda (misalnya array events yang heterogen). Untuk kasus itu, Anda perlu menulis discriminated union secara manual setelah pembuatan.

Mengapa interface untuk Objek, type untuk Array Root

TypeScript Handbook resmi memberikan heuristik satu baris: «Jika Anda ingin heuristik, gunakan interface hingga Anda perlu menggunakan fitur dari type.» Keduanya bertipe struktural, keduanya dapat mendeskripsikan bentuk objek, tetapi interface menang untuk bentuk objek karena mendukung declaration merging (membuka kembali antarmuka untuk menambah field), bekerja bersih dengan extends, dan muncul berdasarkan nama dalam error kompiler. Alias type diperlukan ketika Anda membutuhkan union primitif, interseksi beberapa tipe, atau penamaan sesuatu yang bukan objek, itulah mengapa array level root mendapat alias type Root = RootItem[]; daripada antarmuka.

Catatan tentang penamaan: konverter menggunakan PascalCase tanpa awalan I lama (jadi User bukan IUser). Panduan gaya TS modern (Google, Microsoft, komunitas React) hampir secara universal membuang awalan tersebut. Nama properti cocok dengan kunci JSON persis (camelCase jika JSON menggunakan camelCase, snake_case jika menggunakan snake_case). Kunci yang bukan pengenal JS valid (mengandung tanda hubung, spasi, atau dimulai dengan digit) dikutip: "foo-bar": string;.

Apa yang Tidak Dilakukan Alat Ini (Jujur tentang Keterbatasan)

Satu contoh JSON membawa lebih sedikit informasi daripada skema nyata, jadi beberapa hal yang ingin dideteksi tidak mungkin dilakukan hanya dari input:

• Field opsional. Setiap properti dalam contoh Anda menjadi wajib. Jika API nyata terkadang menghilangkan field, Anda perlu menambahkan ? secara manual: email?: string;. Atau jalankan konverter pada beberapa contoh dan union hasilnya.
• Deteksi nullable. null dalam contoh menjadi unknown; konverter tidak dapat mengetahui apakah field benar-benar nullable (string | null) atau hanya kebetulan null dalam sampel ini. Sesuaikan secara manual berdasarkan kontrak API.
• Union literal string. Field status dengan nilai "active" menjadi string, bukan "active" | "inactive" | "pending". Konverter tidak dapat melihat nilai-nilai lainnya.
• Deteksi tipe Date. String ISO 8601 seperti "2024-04-12T10:00:00Z" tetap menjadi string. Date JavaScript bukan tipe JSON.
• Discriminated union. Jika array root berisi item dengan bentuk berbeda (event dari tipe yang berbeda, record polimorfik), konverter menggabungkan semua kunci menjadi satu antarmuka daripada menghasilkan tagged union. Untuk data heterogen nyata, Anda perlu menulis union secara manual.
• Presisi angka. number JavaScript secara aman merepresentasikan bilangan bulat hingga 2⁵³−1. ID bilangan bulat yang lebih besar kehilangan presisi ketika di-parsing oleh JSON.parse; jika API Anda mengembalikan bilangan bulat 64-bit, pola paling aman adalah mengirimnya sebagai string dan mengetiknya sebagai string.

Kapan Menggunakan Alat Ini

• Bootstrap tipe dari respons API nyata. Hit endpoint, tempel JSON, dapatkan kumpulan antarmuka awal. Sesuaikan secara manual untuk field opsional dan literal string.
• Menambahkan tipe ke SDK pihak ketiga yang tidak memiliki tipe. Banyak perpustakaan JS lama dikirim tanpa tipe. Membuat tipe dari contoh respons lebih cepat daripada membaca dokumentasinya.
• Berbagi tipe antara front-end dan back-end. Buat tipe dari satu contoh kanonik dan salin ke kedua codebase (atau bagikan melalui paket tipe yang diterbitkan).
• Migrasi codebase JS ke TypeScript. Buat tipe dari data nyata yang mengalir melalui aplikasi dan secara bertahap anotasi tanda tangan fungsi.
• Membuat tipe untuk file konfigurasi. Pengetikan yang ketat membuat error konfigurasi terlihat pada waktu kompilasi.
• Mendokumentasikan bentuk file data internal. Antarmuka yang dihasilkan berfungsi ganda sebagai dokumentasi yang dapat dibaca mesin.

Code-First vs Schema-First vs Langsung (Di Mana Alat Ini Berada)

Tiga alur kerja umum untuk mendapatkan tipe TypeScript dari data runtime:

• Validator runtime code-first: Zod, Yup, Effect Schema, Joi. Anda menulis skema validator dalam JS, ia memberi Anda baik parsing runtime maupun tipe TypeScript melalui inferensi. Skema adalah sumber kebenaran. Terbaik ketika validasi sama pentingnya dengan tipe.
• Schema-first: tulis JSON Schema atau spesifikasi OpenAPI, buat tipe TypeScript melalui alat seperti quicktype, json-schema-to-typescript, atau openapi-typescript. Terbaik ketika kontrak API mencakup beberapa bahasa.
• Inferensi sampel langsung (alat ini, ditambah mode plain-JSON quicktype), tempel data nyata, dapatkan tipe. Jalur tercepat; jaminan validasi paling lemah karena tidak ada yang memeriksa data runtime terhadap tipe.

Pilihan yang tepat bergantung pada apakah kekhawatiran Anda sebagian besar adalah pengecekan tipe statis (alat ini sangat baik) atau juga keamanan runtime (gunakan Zod / Effect Schema sebagai gantinya).

Kesalahan Umum

1. Memperlakukan tipe yang dihasilkan sebagai spesifikasi yang sudah selesai. Mereka adalah titik awal 70% selesai. Tambahkan ? untuk field opsional, | null di mana benar-benar nullable, union literal string di mana berlaku.
2. Membuat tipe dari satu contoh ketika API memiliki varian. Objek user yang terkadang memiliki email dan terkadang tidak akan dibuat sebagai «email diperlukan». Jalankan beberapa contoh dan union hasilnya, atau edit secara manual.
3. Menandai semuanya readonly secara otomatis. Berguna untuk aliran data yang tidak dapat diubah tetapi salah untuk objek state yang Anda mutasi. Gunakan toggle readonly dengan bijaksana.
4. Mempercayai presisi pada ID bilangan bulat besar. number JavaScript mencapai batas di 2⁵³−1. Untuk ID 64-bit, kirimkan sebagai string dan ketik sebagai string.
5. Mengacaukan interface dengan type. Alat yang berbeda, trade-off yang berbeda. Heuristik TypeScript Handbook adalah «gunakan interface kecuali Anda memerlukan fitur yang hanya type yang menyediakan,» tepat seperti yang dilakukan alat ini.
6. Menempel JSON rahasia ke konverter sisi server. Respons API nyata sering berisi data pelanggan, kredensial, ID internal. Konversi hanya di browser (alat ini) menjaga data di mesin Anda.

Pertanyaan yang Lebih Sering Diajukan

Mengapa semua field saya ditandai sebagai wajib?

Karena satu contoh JSON tidak dapat memberi tahu konverter field mana yang terkadang tidak ada dalam API nyata. Setiap kunci yang muncul dalam contoh menjadi wajib. Jika Anda tahu sebuah field bersifat opsional, tambahkan ? di akhir secara manual: email?: string;. Untuk deteksi opsionalitas multi-sampel, CLI quicktype yang lebih canggih menanganinya secara native.

Mengapa field null saya diketik sebagai unknown?

Karena konverter tidak dapat membedakan dari satu null apakah field selalu nullable (string | null) atau apakah itu hanya kebetulan null dalam sampel ini (string). unknown adalah default konservatif; TypeScript akan memaksa Anda untuk mempersempit tipe sebelum menggunakan nilai, yang lebih aman daripada any. Edit ke string | null secara manual setelah Anda mengetahui maksud API.

Haruskah saya menggunakan interface atau type?

Heuristik TypeScript Handbook resmi: gunakan interface hingga Anda membutuhkan fitur yang hanya type yang menyediakan, terutama union type, intersection type, atau penamaan primitif. Konverter ini mengikuti aturan tersebut: interface untuk setiap bentuk objek, type untuk alias array root. Beberapa panduan gaya merekomendasikan default ke type sebagai gantinya (Matt Pocock telah memperdebatkan hal ini secara publik) tetapi default konvensional adalah interface untuk objek.

Apakah JSON saya akan diunggah ke suatu tempat?

Tidak. Konversi adalah JavaScript IIFE yang berdiri sendiri yang mem-parsing JSON Anda melalui JSON.parse, menelusuri nilai, dan menulis output TypeScript ke textarea. Tidak ada fetch, tidak ada panggilan analytics yang membawa konten JSON, tidak ada server. Ini penting karena respons API nyata biasanya berisi data pelanggan, ID internal, atau kredensial yang tidak ingin Anda alirkan melalui pihak ketiga.

Bagaimana dengan JSDoc, Zod, atau validasi runtime?

Alat ini hanya menghasilkan tipe TypeScript waktu kompilasi: tidak ada validator runtime (tidak ada Zod / Yup / Effect Schema), tidak ada komentar JSDoc. Jika Anda membutuhkan validasi runtime yang sekaligus menjadi tipe statis, tulis skema dalam Zod dan gunakan z.infer<typeof Schema> Zod untuk menurunkan tipe. Jika Anda memiliki JSON Schema dan menginginkan validasi runtime sekaligus tipe TS, pasangan konvensionalnya adalah json-schema-to-typescript + AJV.

Mengapa tidak ada awalan I pada nama antarmuka?

Karena sebagian besar panduan gaya TypeScript modern membuangnya. Google's TypeScript Style Guide merekomendasikan untuk menghindarinya secara eksplisit; komunitas React telah bertemu pada PascalCase tanpa awalan. Konvensi IUser lama berasal dari pengaruh C# / Java pada TypeScript awal; praktik saat ini adalah User saja.