TypeScript JSON: JSON.parse typisieren, JSON zu Interface, Imports

JSON.parse gibt any zurück, also akzeptiert TypeScript jeden Typ, dem du das Ergebnis zuweist. Das macht das Typisieren von geparstem JSON zu einer Zeile, bedeutet aber auch, dass der Typ ein Versprechen von dir ist und nichts, was der Compiler prüft:

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

Beim zweiten Objekt ist age der String "41". TypeScript nennt es trotzdem number, weil any allem zugewiesen werden kann, und das Programm gibt 411 aus. Für JSON, das dein eigener Code gerade erst geschrieben hat, ist die Annotation in Ordnung. Daten aus einem Request, einer Datei oder dem Local Storage validierst du.

In unknown parsen

Typisierst du das Ergebnis als unknown, besteht der Compiler auf einer Prüfung, bevor irgendeine Eigenschaft verwendet wird:

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

console.log(data.name);

Der Fehler lautet index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Jede Prüfung, die du dann schreibst, engt data ein Stück weiter ein.

Mit einem Type Guard validieren

Ein Type Guard ist eine Funktion, die value is User zurückgibt. Liefert sie true, behandelt TypeScript den Wert von da an als User, und die Prüfungen darin sind echte Prüfungen zur Laufzeit:

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 selbst wirft bei fehlerhaftem Text einen SyntaxError, echter Code packt es also zusätzlich in try/catch. Bei großen oder verschachtelten Daten werden handgeschriebene Guards lang; Schema-Bibliotheken wie Zod oder Valibot lassen dich die Form einmal deklarieren und daraus sowohl den Validator als auch den TypeScript-Typ ableiten.

JSON zu TypeScript-Interface

Ein JSON-Beispiel in Typen umzuwandeln ist Handarbeit nach Schema. Gegeben diese Antwort:

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

Ordne jedem Wert seinen Typ zu, gib verschachtelten Objekten ein eigenes Interface und markiere, was variieren kann:

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

Ein einzelnes Beispiel verrät nicht, welche Felder optional oder nullable sind. Sieh dir mehrere Antworten oder die Dokumentation der API an, bevor du dich auf ? und | null festlegst.

Datumswerte und der Reviver

JSON hat keinen Datumstyp, also kommen Datumswerte als Strings an. Das zweite Argument von JSON.parse, der Reviver, wird für jeden Schlüssel aufgerufen und kann sie wiederherstellen:

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

Der Parameter value des Revivers ist any, ebenso das Ergebnis, der Typ Order wird also weiterhin vertraut statt geprüft. JSON.stringify(order, null, 2) rückt die Ausgabe um zwei Leerzeichen ein und macht aus dem Date wieder seinen ISO-String.

JSON.stringify und was dabei verloren geht

JSON.stringify ist so typisiert, dass es string zurückgibt. Die Werte, die es umwandelt, kommen nicht immer gleich zurück, und der Typ warnt dich nicht:

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

Die Regeln zur Laufzeit sind dieselben wie in reinem JavaScript, beschrieben unter JSON in JavaScript.

Ein Typ für jeden JSON-Wert

Wenn Code beliebiges JSON verarbeitet, beschreibt ein rekursiver Typ genau, was JSON enthalten kann, und lehnt Werte ab, die es nicht kann:

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

Ohne den Kommentar ist die letzte Zeile ein Compilerfehler, weil ein Date-Objekt kein JsonValue ist.

.json-Dateien importieren

Eine .json-Datei lässt sich wie ein Modul importieren, und TypeScript leitet ihren Typ aus dem Inhalt ab:

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

In TypeScript 7 funktioniert das ohne zusätzliche Einstellungen, wenn module auf nodenext, node20, commonjs, esnext oder preserve steht. Unter node16 und node18 scheitert es mit dem Fehler TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., bis du "resolveJsonModule": true ergänzt; auf false gesetzt schaltet die Option JSON-Imports überall ab. In einem ES-Modul unter nodenext oder node20 braucht der Import das Attribut with { type: "json" } (ohne gibt es den Fehler TS1543), und nur der Default-Import ist erlaubt (Fehler TS1544 bei import { port }). tsc kopiert die importierte .json-Datei nach outDir, neben das kompilierte JavaScript.