JSON → TypeScript

Что это и зачем

TypeScript — JavaScript с системой типов. Главное преимущество — компилятор ловит ошибки до запуска кода: пустые ссылки на свойства, неправильные типы аргументов, опечатки в именах полей. Когда вы получаете JSON от внешнего API, у него нет типов — TypeScript видит unknown или any, компилятор не помогает.

Этот генератор смотрит на пример JSON ответа и автоматически создаёт TypeScript interface (или type), описывающий его структуру. Тип сохраняете в types/api.ts, импортируете и используете при fetch — компилятор валидирует код.

Опции генератора

• Имя интерфейса. Для корневого интерфейса — обычно Response, User, Order и т.д. Вложенные генерируются автоматически из имён ключей (с заглавной буквы).
• type vs interface. Без разницы для простых объектов. interface поддерживает declaration merging (полезно для модулей). type позволяет union, intersection, mapped types.
• camelCase. Преобразует last_login → lastLogin. Полезно если ваш код придерживается JavaScript-конвенций. ⚠ Но это уже не точное отражение API — нужен runtime-маппинг.
• Опциональные поля. Если значение в примере null, поле помечается ?:. Это семантически означает «может отсутствовать». Полезно для API с переменной структурой ответа.

Almost all features of an interface are available in type, the key distinction is that a type cannot be re-opened to add new properties vs an interface which is always extendable.— TypeScript Handbook — Type Aliases vs Interfaces

Что дальше — Zod, OpenAPI

Этот генератор хорош для быстрого старта или одноразовой задачи. Для production есть лучшие подходы:

• Zod. Самая популярная runtime-валидация с автоматическим выводом типов. Один источник правды: схема описывает и валидацию (что приходит с сервера), и тип (что использовать в коде). Изменился API — Zod ругается на runtime, не на compile.
• io-ts. Похоже на Zod, но functional programming style (как fp-ts). Сложнее, но мощнее.
• OpenAPI / Swagger. Если у вашего API есть OpenAPI-спека — используйте openapi-typescript-codegen или orval для автогенерации типов и клиента.
• GraphQL. graphql-codegen берёт схему GraphQL и генерирует типы для каждой query / mutation. Лучшее решение если есть GraphQL.
• tRPC. End-to-end типизация TypeScript: backend и frontend разделяют типы напрямую. Не нужны генерации, но требует TS на backend.

Подводные камни

• JSON может врать. API мог вернуть number, в следующий раз — строку. Генератор учится только по одному примеру.
• Числа JSON. Все числа в JSON — number в JavaScript. Если API возвращает большой ID (Twitter snowflake), он может потерять precision. Используйте string для ID.
• Даты. JSON не имеет типа Date. Даты приходят как ISO 8601 строки. В коде придётся new Date(response.created_at).
• nullable vs optional. null и undefined — разные. foo: string | null = поле есть, может быть null. foo?: string = поле может отсутствовать. Иногда нужно оба: foo?: string | null.