Générer des types TypeScript à partir de JSON — la bonne méthode

Partir de vrais exemples

Collez une réponse dans le convertisseur JSON vers TypeScript et vous obtenez une interface pour chaque objet imbriqué. Un seul exemple ne montre cependant qu’une forme possible. Collez donc un tableau de plusieurs objets réels : le convertisseur les fusionne et marque comme optionnels les champs absents de certains d’entre eux.

[
  { "id": 1, "name": "Ada", "email": "ada@example.com", "team": { "id": 7, "name": "Core" } },
  { "id": 2, "name": "Grace", "email": null }
]

interface User {
  id: number;
  name: string;
  email: string | null;
  team?: Team;
}
interface Team {
  id: number;
  name: string;
}

Optionnel n’est pas nullable

team?: Team signifie que la clé peut être absente. email: string | null signifie que la clé est toujours présente mais peut valoir null. Les API les utilisent différemment et votre code les vérifie différemment ('team' in user contre user.email === null). Conservez donc cette distinction au lieu de tout transformer en ?: … | null.

Affiner ce que l’exemple ne peut pas révéler

• Unions de littéraux : un champ status vu comme "active" devient string. Remplacez-le par 'active' | 'paused' | 'deleted' d’après la documentation de l’API.
• Dates : elles arrivent sous forme de chaînes ISO. Typez-les en string et convertissez-les en périphérie de votre code. Ne les traitez pas comme des objets Date.
• Identifiants : les identifiants numériques volumineux (au-delà de 2⁵³) perdent en précision en JavaScript. C’est pourquoi de nombreuses API les envoient sous forme de chaînes.
• Tableaux vides : ils deviennent unknown[] ou any[]. Précisez vous-même le type des éléments.

Les types disparaissent à l’exécution

TypeScript vérifie votre code, pas les données. Si l’API change, le compilateur ne s’en apercevra pas. Validez les réponses à la frontière de votre application :

1. Générez un schéma à partir des mêmes exemples avec JSON vers JSON Schema.
2. Modifiez-le (champs requis, énumérations, formats comme date-time) et testez des charges utiles réelles dans le validateur JSON Schema.
3. Validez dans votre application avec une bibliothèque comme Ajv, et générez les types à partir du schéma (JSON Schema vers TypeScript) afin de disposer d’une seule source de vérité.

import Ajv from 'ajv';
const ajv = new Ajv();
const validate = ajv.compile(userSchema);
const data = await res.json();
if (!validate(data)) throw new Error('Unexpected API response: ' + ajv.errorsText(validate.errors));

Des bibliothèques comme Zod ou Valibot font la même chose, avec le schéma écrit directement en TypeScript, puis en déduisent le type.

Nommage et structure

Donnez au type racine un nom explicite (User, et non Root), exportez les types depuis un seul module et privilégiez interface pour les formes d’objets que vous pourriez étendre. Formatez et inspectez d’abord les grandes réponses avec le formateur JSON pour repérer les branches importantes.