TypeScript JSON: Tipe JSON.parse, JSON ke Interface, Import

JSON.parse mengembalikan any, jadi TypeScript menerima tipe apa pun yang kamu berikan pada hasilnya. Memberi tipe pada JSON hasil parse jadi cukup satu baris, tetapi itu juga berarti tipenya adalah janji yang kamu buat, bukan sesuatu yang diperiksa compiler:

interface User {
  name: string;
  age: number;
}

const text = '{"name":"Ada","age":36}';
const user: User = JSON.parse(text); // JSON.parse returns any

console.log(user.name.toUpperCase(), user.age + 1); // ADA 37

// The annotation is a promise, not a check:
const wrong: User = JSON.parse('{"name":"Bob","age":"41"}');
console.log(wrong.age + 1); // 411, a string concatenation

Object kedua punya age berupa string "41". TypeScript tetap menganggapnya number, karena any bisa di-assign ke apa saja, dan program mencetak 411. Untuk JSON yang baru saja ditulis oleh kodemu sendiri, anotasi itu tidak masalah. Untuk data dari request, file, atau local storage, lakukan validasi.

Parse ke unknown

Memberi tipe unknown pada hasilnya membuat compiler mewajibkan pemeriksaan sebelum properti apa pun dipakai:

// This does not compile: unknown must be narrowed before use.
const data: unknown = JSON.parse('{"name":"Ada"}');

console.log(data.name);

Error-nya adalah index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Setiap pemeriksaan yang kemudian kamu tulis akan mempersempit tipe data sedikit demi sedikit.

Validasi dengan Type Guard

Type guard adalah fungsi yang mengembalikan value is User. Kalau fungsi itu mengembalikan true, TypeScript memperlakukan nilainya sebagai User sejak saat itu, dan pemeriksaan di dalamnya adalah pemeriksaan runtime yang sungguhan:

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "name" in value &&
    typeof value.name === "string" &&
    "age" in value &&
    typeof value.age === "number"
  );
}

function parseUser(text: string): User {
  const data: unknown = JSON.parse(text);
  if (!isUser(data)) {
    throw new Error("Not a valid user: " + text);
  }
  return data; // narrowed to User
}

console.log(parseUser('{"name":"Ada","age":36}')); // { name: 'Ada', age: 36 }
try {
  parseUser('{"name":"Bob","age":"41"}');
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Not a valid user: {"name":"Bob","age":"41"}
}

JSON.parse sendiri melempar SyntaxError untuk teks yang formatnya rusak, jadi kode sungguhan juga membungkusnya dengan try/catch. Untuk payload yang besar atau bersarang, type guard yang ditulis manual jadi panjang; library schema seperti Zod atau Valibot memungkinkanmu mendeklarasikan bentuknya sekali, lalu menurunkan validator dan tipe TypeScript-nya dari situ.

JSON ke Interface TypeScript

Mengubah contoh JSON menjadi tipe itu pekerjaan mekanis. Misalnya ada response seperti ini:

{
    "id": 42,
    "title": "Learn TypeScript",
    "done": false,
    "owner": { "id": 7, "name": "Ada" },
    "tags": ["study", "ts"],
    "dueDate": "2024-03-15T10:30:00Z",
    "notes": null
}

Petakan setiap nilai ke tipenya, beri object bersarang interface-nya sendiri, dan tandai bagian yang bisa berubah-ubah:

interface Owner {
  id: number;
  name: string;
}

interface Task {
  id: number;
  title: string;
  done: boolean;
  owner: Owner;         // nested object: its own interface
  tags: string[];       // array of strings
  dueDate: string;      // JSON has no dates: it is an ISO string
  notes: string | null; // null in this sample, text in others
  priority?: number;    // missing in this sample, present in others
}

const task: Task = {
  id: 42,
  title: "Learn TypeScript",
  done: false,
  owner: { id: 7, name: "Ada" },
  tags: ["study", "ts"],
  dueDate: "2024-03-15T10:30:00Z",
  notes: null,
};

console.log(task.owner.name, task.tags.length, task.priority ?? "none"); // Ada 2 none

Satu contoh data saja tidak bisa memberitahumu field mana yang opsional atau bisa bernilai null. Lihat beberapa response, atau dokumentasi API-nya, sebelum memutuskan memakai ? dan | null.

Tanggal dan Reviver

JSON tidak punya tipe tanggal, jadi tanggal datang sebagai string. Argumen kedua JSON.parse, yaitu reviver, dipanggil untuk setiap key dan bisa membangun ulang tanggal itu:

interface Order {
  id: number;
  placedAt: Date;
}

const text = '{"id":7,"placedAt":"2024-03-15T10:30:00.000Z"}';

const order: Order = JSON.parse(text, (key, value) =>
  key === "placedAt" ? new Date(value) : value
);

console.log(order.placedAt instanceof Date, order.placedAt.getUTCHours()); // true 10
console.log(JSON.stringify(order, null, 2));

Parameter value milik reviver bertipe any, begitu juga hasilnya, jadi tipe Order tetap dipercaya, bukan diperiksa. JSON.stringify(order, null, 2) memberi indentasi dua spasi pada output dan mengubah Date kembali menjadi string ISO.

JSON.stringify dan Apa yang Hilang

JSON.stringify diberi tipe kembalian string. Nilai yang dikonversinya tidak selalu kembali dalam bentuk yang sama, dan tipenya tidak memperingatkanmu:

interface Meeting {
  title: string;
  at: Date;
  tags: Set<string>;
}

const meeting: Meeting = {
  title: "Launch",
  at: new Date("2024-03-15T10:30:00Z"),
  tags: new Set(["release"]),
};

const json = JSON.stringify(meeting);
console.log(json); // {"title":"Launch","at":"2024-03-15T10:30:00.000Z","tags":{}}

const back = JSON.parse(json);
console.log(typeof back.at, back.tags); // string {}

const nothing: string = JSON.stringify(undefined); // typed string...
console.log(nothing); // ...but the value is undefined

Aturan saat runtime sama seperti di JavaScript biasa, yang dibahas di JSON di JavaScript.

Tipe untuk Nilai JSON Apa Pun

Kalau kode menangani JSON sembarang, tipe rekursif bisa menjelaskan dengan tepat apa saja yang bisa disimpan JSON dan menolak nilai yang tidak bisa:

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

function countLeaves(value: JsonValue): number {
  if (Array.isArray(value)) {
    return value.reduce((n: number, v) => n + countLeaves(v), 0);
  }
  if (typeof value === "object" && value !== null) {
    return Object.values(value).reduce((n: number, v) => n + countLeaves(v), 0);
  }
  return 1;
}

const doc: JsonValue = { name: "Ada", langs: ["en", "fr"], address: { city: "London", zip: null } };
console.log(countLeaves(doc)); // 5

// @ts-expect-error a Date is not a JSON value
const bad: JsonValue = { at: new Date() };

Tanpa komentar itu, baris terakhir adalah error kompilasi karena object Date bukan JsonValue.

Meng-import File .json

File .json bisa di-import seperti module, dan TypeScript menyimpulkan tipenya dari isinya:

{ "name": "app", "port": 8080, "tags": ["a"] }

// CommonJS output, or a bundler
import config from "./config.json";
const port: number = config.port; // typed from the file: number

// An ES module under module: nodenext
import settings from "./config.json" with { type: "json" };

Di TypeScript 7, ini bisa dipakai tanpa pengaturan tambahan kalau module bernilai nodenext, node20, commonjs, esnext, atau preserve. Dengan node16 dan node18, import gagal dengan error TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., sampai kamu menambahkan "resolveJsonModule": true; mengaturnya ke false mematikan import JSON di semua tempat. Di ES module dengan nodenext atau node20, import-nya butuh atribut with { type: "json" } (tanpa atribut itu muncul error TS1543) dan hanya default import yang diizinkan (error TS1544 untuk import { port }). tsc menyalin file .json yang di-import ke outDir, di samping JavaScript hasil kompilasi.