TypeScript JSON: JSON.parse Tipleme, JSON'dan Interface

JSON.parse any döndürür, bu yüzden TypeScript sonucu atadığınız her tipi kabul eder. Bu, parse edilen JSON'u tiplemeyi tek satırlık bir iş yapar, ama aynı zamanda tipin derleyicinin kontrol ettiği bir şey değil, sizin verdiğiniz bir söz olduğu anlamına gelir:

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

İkinci nesnede age, "41" string'idir. TypeScript onu yine de number olarak görür, çünkü any her şeye atanabilir ve program 411 yazdırır. Kendi kodunuzun az önce yazdığı JSON için işaretleme yeterlidir. Bir istekten, bir dosyadan ya da local storage'dan gelen veriyi doğrulayın.

unknown'a Parse Etmek

Sonucu unknown olarak tiplemek, derleyicinin herhangi bir özellik kullanılmadan önce bir kontrol istemesini sağlar:

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

console.log(data.name);

Hata şudur: index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Sonra yazdığınız her kontrol data'yı biraz daha daraltır.

Type Guard ile Doğrulamak

Type guard, value is User döndüren bir fonksiyondur. true döndürdüğünde TypeScript değeri o andan itibaren bir User olarak görür ve içindeki kontroller gerçek çalışma zamanı kontrolleridir:

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 bozuk metinde kendisi bir SyntaxError fırlatır, bu yüzden gerçek kod onu da try/catch ile sarar. Büyük ya da iç içe veri için elle yazılan guard'lar uzar; Zod ya da Valibot gibi şema kütüphaneleri şekli bir kez tanımlamanıza ve hem doğrulayıcıyı hem de TypeScript tipini ondan türetmenize izin verir.

JSON'dan TypeScript Interface'ine

Bir JSON örneğini tiplere çevirmek mekanik bir iştir. Şu yanıt verildiğinde:

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

Her değeri tipine eşleyin, iç içe nesnelere kendi interface'lerini verin ve değişebilen yerleri işaretleyin:

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

Tek bir örnek hangi alanların isteğe bağlı ya da null olabileceğini söyleyemez. ? ve | null kararını vermeden önce birkaç yanıta ya da API'nin belgelerine bakın.

Tarihler ve Reviver

JSON'un bir tarih tipi yoktur, bu yüzden tarihler string olarak gelir. JSON.parse'ın ikinci argümanı olan reviver her anahtar için çağrılır ve onları yeniden oluşturabilir:

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));

Reviver'ın value parametresi any'dir, sonuç da öyle; bu yüzden Order tipi hâlâ kontrol edilmez, güvenilir. JSON.stringify(order, null, 2) çıktıyı iki boşlukla girintiler ve Date'i yeniden ISO string'ine çevirir.

JSON.stringify ve Kaybettikleri

JSON.stringify, string döndürecek şekilde tiplenmiştir. Dönüştürdüğü değerler her zaman aynı şekilde geri gelmez ve tip sizi uyarmaz:

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

Çalışma zamanı kuralları düz JavaScript'tekiyle aynıdır ve JavaScript'te JSON sayfasında anlatılır.

Her JSON Değeri İçin Bir Tip

Kod rastgele JSON işlediğinde, özyinelemeli bir tip JSON'un tam olarak neleri tutabileceğini tanımlar ve tutamayacağı değerleri reddeder:

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() };

Yorum olmadan son satır bir derleme hatasıdır, çünkü bir Date nesnesi bir JsonValue değildir.

.json Dosyalarını Import Etmek

Bir .json dosyası bir modül gibi import edilebilir ve TypeScript tipini içeriğinden çıkarır:

{ "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" };

TypeScript 7'de bu, module değeri nodenext, node20, commonjs, esnext ya da preserve iken ek ayar olmadan çalışır. node16 ve node18 altında siz "resolveJsonModule": true ekleyene kadar TS2732 hatasıyla başarısız olur: Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension. Seçeneği false yapmak JSON import'larını her yerde kapatır. nodenext ya da node20 altındaki bir ES modülünde import with { type: "json" } attribute'unu gerektirir (onsuz TS1543 hatası) ve yalnızca default import'a izin verilir (import { port } için TS1544 hatası). tsc, import edilen .json dosyasını derlenmiş JavaScript'in yanına, outDir içine kopyalar.