Generate TypeScript Types dari JSON — dengan Cara yang Benar

Mulai dari contoh data asli

Tempel response ke konverter JSON to TypeScript, dan kamu akan mendapat interface untuk setiap objek bertingkat. Tapi satu contoh hanya menunjukkan satu bentuk data, jadi tempel array berisi beberapa objek asli: konverter akan menggabungkannya dan menandai field yang tidak ada di sebagian objek sebagai optional.

[
  { "id": 1, "name": "Ada", "email": "ada@example.com", "team": { "id": 7, "name": "Core" } },
  { "id": 2, "name": "Grace", "email": null }
]

interface User {
  id: number;
  name: string;
  email: string | null;
  team?: Team;
}
interface Team {
  id: number;
  name: string;
}

Optional tidak sama dengan nullable

team?: Team berarti key mungkin tidak ada. email: string | null berarti key selalu ada, tapi nilainya bisa null. API memakai keduanya dengan cara berbeda, dan kodemu juga mengeceknya dengan cara berbeda ('team' in user vs user.email === null). Jadi pertahankan perbedaannya, jangan membuat semuanya ?: … | null.

Perketat hal yang tidak bisa dilihat dari contoh

• Literal union — field status yang terlihat sebagai "active" akan menjadi string; ganti dengan 'active' | 'paused' | 'deleted' dari dokumentasi API.
• Tanggal datang sebagai string ISO. Beri tipe string dan parse di tepi aplikasi — jangan berpura-pura itu objek Date.
• ID — ID numerik besar (di atas 2⁵³) kehilangan presisi di JavaScript; itulah sebabnya banyak API mengirimnya sebagai string.
• Array kosong akan menjadi unknown[] atau any[]; isi sendiri tipe elemennya.

Types hilang saat runtime

TypeScript mengecek kodemu, bukan datanya. Kalau API berubah, compiler tidak akan menyadarinya. Karena itu, validasi response di perbatasan aplikasi:

1. Buat schema dari contoh yang sama dengan JSON to JSON Schema.
2. Edit schema-nya — field wajib, enum, format seperti date-time — lalu uji payload asli di JSON Schema Validator.
3. Validasi di aplikasimu dengan library seperti Ajv, dan buat types dari schema (JSON Schema to TypeScript) supaya hanya ada satu sumber kebenaran.

import Ajv from 'ajv';
const ajv = new Ajv();
const validate = ajv.compile(userSchema);
const data = await res.json();
if (!validate(data)) throw new Error('Unexpected API response: ' + ajv.errorsText(validate.errors));

Library seperti Zod atau Valibot melakukan hal yang sama, dengan schema yang ditulis langsung dalam TypeScript, lalu menyimpulkan type dari schema tersebut.

Penamaan dan struktur

Beri nama yang bermakna untuk root type (User, bukan Root), ekspor types dari satu modul, dan utamakan interface untuk bentuk objek yang mungkin akan kamu extend. Rapikan dan periksa response besar lebih dulu dengan JSON Formatter supaya kamu bisa melihat cabang mana yang penting.