JSON en TypeScript : typer JSON.parse, JSON vers interface

JSON.parse renvoie any, donc TypeScript accepte n'importe quel type auquel vous affectez le résultat. Typer du JSON analysé tient donc en une ligne, mais cela veut aussi dire que le type est une promesse que vous faites, pas quelque chose que le compilateur vérifie :

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

Le second objet a un age qui est la chaîne "41". TypeScript l'appelle quand même number, car any peut être affecté à n'importe quoi, et le programme affiche 411. Pour du JSON que votre propre code vient d'écrire, l'annotation suffit. Pour des données venant d'une requête, d'un fichier ou du stockage local, validez-les.

Analyser vers unknown

Typer le résultat en unknown oblige le compilateur à exiger une vérification avant l'utilisation de toute propriété :

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

console.log(data.name);

L'erreur est index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Chaque vérification que vous écrivez ensuite restreint un peu plus le type de data.

Valider avec un type guard

Un type guard est une fonction qui renvoie value is User. Quand elle renvoie true, TypeScript traite ensuite la valeur comme un User, et les tests qu'elle contient sont de vraies vérifications à l'exécution :

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 lui-même lève une SyntaxError sur un texte mal formé, donc le vrai code l'entoure aussi d'un try/catch. Pour des données volumineuses ou imbriquées, les type guards écrits à la main s'allongent ; des bibliothèques de schémas comme Zod ou Valibot vous permettent de déclarer la forme une seule fois et d'en tirer à la fois le validateur et le type TypeScript.

Du JSON vers une interface TypeScript

Convertir un exemple JSON en types est mécanique. Avec cette réponse :

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

Associez chaque valeur à son type, donnez aux objets imbriqués leur propre interface et marquez ce qui peut varier :

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

Un seul exemple ne peut pas vous dire quels champs sont optionnels ou nullables. Regardez plusieurs réponses, ou la documentation de l'API, avant de décider des ? et des | null.

Les dates et le reviver

JSON n'a pas de type date, donc les dates arrivent sous forme de chaînes. Le second argument de JSON.parse, le reviver, est appelé pour chaque clé et peut les reconstruire :

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

Le paramètre value du reviver est any, tout comme le résultat, donc le type Order reste une affirmation de confiance et non une vérification. JSON.stringify(order, null, 2) indente la sortie de deux espaces et retransforme la Date en sa chaîne ISO.

JSON.stringify et ce qu'il perd

JSON.stringify est typé pour renvoyer une string. Les valeurs qu'il convertit ne reviennent pas toujours identiques, et le type ne vous prévient pas :

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

Les règles à l'exécution sont les mêmes qu'en JavaScript pur, présentées dans le JSON en JavaScript.

Un type pour n'importe quelle valeur JSON

Quand du code manipule du JSON arbitraire, un type récursif décrit exactement ce que JSON peut contenir et refuse les valeurs qu'il ne peut pas contenir :

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

Sans le commentaire, la dernière ligne est une erreur de compilation, car un objet Date n'est pas une JsonValue.

Importer des fichiers .json

Un fichier .json peut être importé comme un module, et TypeScript déduit son type de son contenu :

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

Dans TypeScript 7, cela fonctionne sans réglage supplémentaire avec module réglé sur nodenext, node20, commonjs, esnext ou preserve. Sous node16 et node18, cela échoue avec l'erreur TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., tant que vous n'ajoutez pas "resolveJsonModule": true ; le régler à false désactive les imports JSON partout. Dans un module ES sous nodenext ou node20, l'import exige l'attribut with { type: "json" } (erreur TS1543 sans lui) et seul l'import par défaut est autorisé (erreur TS1544 pour import { port }). tsc copie le fichier .json importé dans outDir à côté du JavaScript compilé.