Почему JSON лучше принимать как unknown в TypeScript

Проверяем ответ внешнего API на границе приложения и превращаем его в типизированные данные без утверждения as.

Сервис обещает прислать заказ с полями id и totalCents. Однажды сумма приходит строкой: "2500". Если код уже поверил типу Order, прибавление 100 даст "2500100". Так ошибка во входных данных незаметно превращается в неправильный результат.

Отдели разбор JSON от проверки данных

type Order = {
  id: string;
  totalCents: number;
};

function parseOrder(text: string): Order {
  const value: unknown = JSON.parse(text);
  if (!isOrder(value)) {
    throw new Error('Некорректный формат заказа');
  }
  return value;
}

JSON.parse проверяет синтаксис. Он может вернуть объект, массив, число или null. Тип unknown заставляет проверить результат перед тем, как читать его поля. Аннотация as Order такой проверки не добавляет: она только сообщает компилятору, что ему следует поверить.

Запиши условия, которым должен отвечать заказ

function isOrder(value: unknown): value is Order {
  return (
    typeof value === 'object' &&
    value !== null &&
    !Array.isArray(value) &&
    'id' in value &&
    typeof value.id === 'string' &&
    value.id.trim().length > 0 &&
    'totalCents' in value &&
    typeof value.totalCents === 'number' &&
    Number.isSafeInteger(value.totalCents) &&
    value.totalCents >= 0
  );
}

Здесь есть и проверка типов, и правила нашего примера. Идентификатор должен быть заполнен, а сумма в центах должна быть целым неотрицательным числом, которое JavaScript может представить точно. Объявление value is Order связывает результат проверки с типом. Сам компилятор не докажет, что реализация предиката действительно проверяет все условия, поэтому предикату нужны примеры отказа.

Прогони граничные случаи

console.log(parseOrder('{"id":"o-1","totalCents":2500}').totalCents + 100);
// 2600

for (const sample of [
  '{"id":"o-1","totalCents":"2500"}',
  '{"id":"o-1","totalCents":-1}',
  '{"id":"   ","totalCents":10}',
  '{"id":"o-1"}',
  'null',
]) {
  try {
    parseOrder(sample);
    throw new Error('Проверка пропустила некорректный заказ');
  } catch (error) {
    if (!(error instanceof Error) || error.message !== 'Некорректный формат заказа') {
      throw error;
    }
  }
}

Ошибки синтаксиса оставь отдельным случаем. Например, строка '{bad json}' упадёт в JSON.parse, а корректный JSON без totalCents дойдёт до проверки формата. Обработай оба случая на границе приложения, где можно объяснить, что именно не так с ответом.

Для упражнения добавь обязательное поле currency со значениями 'RUB' | 'EUR'. Измени тип, предикат и тесты так, чтобы неизвестная валюта отклонялась так же, как строка вместо суммы.

Сужение типов и предикаты в TypeScript Handbook.