JSON w TypeScript: typowanie JSON.parse, JSON do interfejsu

JSON.parse zwraca any, więc TypeScript akceptuje każdy typ, do którego przypiszesz wynik. Dzięki temu otypowanie sparsowanego JSON-a zajmuje jedną linię, ale oznacza to też, że typ jest twoją obietnicą, a nie czymś, co sprawdza kompilator:

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

Drugi obiekt ma age jako string "41". TypeScript nadal nazywa to number, bo any da się przypisać do wszystkiego, a program wypisuje 411. Dla JSON-a, który twój kod przed chwilą sam zapisał, adnotacja wystarczy. Dane z żądania, pliku albo local storage trzeba walidować.

Parsowanie do unknown

Otypowanie wyniku jako unknown sprawia, że kompilator wymaga sprawdzenia, zanim użyjesz jakiejkolwiek właściwości:

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

console.log(data.name);

Błąd to index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Każde kolejne sprawdzenie, które napiszesz, zawęża data trochę bardziej.

Walidacja przez type guard

Type guard to funkcja zwracająca value is User. Gdy zwraca true, TypeScript od tego miejsca traktuje wartość jako User, a sprawdzenia w jej wnętrzu są prawdziwymi sprawdzeniami w czasie działania:

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

Sam JSON.parse rzuca SyntaxError przy niepoprawnym tekście, więc prawdziwy kod owija go też w try/catch. Przy dużych albo zagnieżdżonych danych ręcznie pisane guardy robią się długie; biblioteki schematów, takie jak Zod czy Valibot, pozwalają zadeklarować kształt raz i wyprowadzić z niego zarówno walidator, jak i typ TypeScript.

Z JSON do interfejsu TypeScript

Zamiana próbki JSON na typy jest mechaniczna. Mając taką odpowiedź:

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

Przypisz każdej wartości jej typ, daj zagnieżdżonym obiektom własny interfejs i oznacz to, co może się zmieniać:

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

Jedna próbka nie powie, które pola są opcjonalne albo mogą być null. Zanim zdecydujesz o ? i | null, przejrzyj kilka odpowiedzi albo dokumentację API.

Daty i reviver

JSON nie ma typu daty, więc daty przychodzą jako stringi. Drugi argument JSON.parse, czyli reviver, jest wywoływany dla każdego klucza i może je odtworzyć:

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

Parametr value revivera ma typ any, podobnie jak wynik, więc typ Order nadal opiera się na zaufaniu, a nie na sprawdzeniu. JSON.stringify(order, null, 2) wcina wynik o dwie spacje i zamienia Date z powrotem na string ISO.

JSON.stringify i to, co gubi

JSON.stringify ma typ zwracający string. Wartości, które konwertuje, nie zawsze wracają takie same, a typ o tym nie ostrzega:

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

Reguły w czasie działania są takie same jak w zwykłym JavaScripcie; opisuje je strona JSON w JavaScripcie.

Typ dla dowolnej wartości JSON

Gdy kod obsługuje dowolny JSON, typ rekurencyjny opisuje dokładnie to, co JSON może zawierać, i odrzuca wartości, których nie może:

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

Bez tego komentarza ostatnia linia jest błędem kompilacji, bo obiekt Date nie jest JsonValue.

Importowanie plików .json

Plik .json można zaimportować jak moduł, a TypeScript wnioskuje jego typ z zawartości:

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

W TypeScript 7 działa to bez dodatkowych ustawień, gdy module ma wartość nodenext, node20, commonjs, esnext albo preserve. Przy node16 i node18 kończy się błędem TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., dopóki nie dodasz "resolveJsonModule": true; ustawienie go na false wyłącza importy JSON wszędzie. W ES module przy nodenext albo node20 import wymaga atrybutu with { type: "json" } (bez niego błąd TS1543) i dozwolony jest tylko import domyślny (błąd TS1544 dla import { port }). tsc kopiuje zaimportowany plik .json do outDir obok skompilowanego JavaScriptu.