JSON в TypeScript: тип JSON.parse, JSON в интерфейс, импорт

JSON.parse возвращает any, поэтому TypeScript принимает любой тип, которому вы присваиваете результат. Так что типизировать разобранный JSON можно одной строкой, но это значит и то, что тип это ваше обещание, а не то, что проверяет компилятор:

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

Во втором объекте age это строка "41". TypeScript всё равно считает его number, потому что any можно присвоить чему угодно, и программа печатает 411. Для JSON, который ваш собственный код записал только что, аннотации достаточно. Данные из запроса, файла или локального хранилища проверяйте.

Разбор в unknown

Если типизировать результат как unknown, компилятор потребует проверку, прежде чем можно будет обратиться к любому свойству:

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

console.log(data.name);

Ошибка: index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Каждая проверка, которую вы затем пишете, сужает data ещё немного.

Проверка защитником типа

Защитник типа это функция, которая возвращает value is User. Когда она возвращает true, TypeScript дальше считает значение типом User, а проверки внутри неё выполняются по-настоящему во время выполнения:

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 на некорректном тексте бросает SyntaxError, поэтому в реальном коде его тоже оборачивают в try/catch. Для больших или вложенных данных самописные защитники становятся длинными; библиотеки схем вроде Zod или Valibot позволяют описать форму один раз и получить из неё и валидатор, и тип TypeScript.

JSON в интерфейс TypeScript

Преобразование примера JSON в типы это механическая работа. Возьмём такой ответ:

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

Сопоставьте каждому значению его тип, дайте вложенным объектам свои интерфейсы и отметьте то, что может меняться:

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

По одному примеру нельзя понять, какие поля опциональны или могут быть null. Прежде чем окончательно решить, где нужны ? и | null, посмотрите несколько ответов или документацию API.

Даты и reviver

В JSON нет типа даты, поэтому даты приходят строками. Второй аргумент JSON.parse, reviver, вызывается для каждого ключа и может их восстановить:

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

Параметр value у reviver имеет тип any, как и результат, поэтому тип Order по-прежнему принимается на веру, а не проверяется. JSON.stringify(order, null, 2) добавляет в вывод отступ в два пробела и превращает Date обратно в ISO-строку.

JSON.stringify и что он теряет

JSON.stringify типизирован как возвращающий string. Значения, которые он преобразует, не всегда возвращаются такими же, и тип об этом не предупреждает:

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

Правила времени выполнения те же, что и в обычном JavaScript; они описаны на странице JSON в JavaScript.

Тип для любого значения JSON

Когда код обрабатывает произвольный JSON, рекурсивный тип точно описывает, что может содержать JSON, и отвергает то, чего не может:

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

Без комментария последняя строка дала бы ошибку компиляции, потому что объект Date не является JsonValue.

Импорт файлов .json

Файл .json можно импортировать как модуль, и TypeScript выведет его тип из содержимого:

{ "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 это работает без дополнительных настроек, если module равен nodenext, node20, commonjs, esnext или preserve. При node16 и node18 импорт падает с ошибкой TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., пока вы не добавите "resolveJsonModule": true; значение false отключает импорт JSON везде. В ES-модуле при nodenext или node20 импорту нужен атрибут with { type: "json" } (без него ошибка TS1543), и разрешён только импорт по умолчанию (для import { port } ошибка TS1544). tsc копирует импортированный файл .json в outDir рядом со скомпилированным JavaScript.