JSON in TypeScript: tipizzare JSON.parse, da JSON a interfaccia, import

JSON.parse restituisce any, quindi TypeScript accetta qualsiasi tipo a cui assegni il risultato. Questo rende la tipizzazione del JSON letto una questione di una riga, ma significa anche che il tipo è una promessa che fai tu, non qualcosa che il compilatore controlla:

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

Il secondo oggetto ha age come stringa "41". TypeScript lo chiama comunque number, perché any si può assegnare a qualunque cosa, e il programma stampa 411. Per un JSON che il tuo stesso codice ha scritto poco prima, l'annotazione va bene. Per dati che arrivano da una richiesta, un file o il local storage, validali.

Fare il parse in unknown

Tipizzare il risultato come unknown obbliga il compilatore a pretendere un controllo prima di usare qualsiasi proprietà:

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

console.log(data.name);

L'errore è index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Ogni controllo che scrivi poi restringe data un po' di più.

Validare con un type guard

Un type guard è una funzione che restituisce value is User. Quando restituisce true, da lì in poi TypeScript tratta il valore come un User, e i controlli al suo interno sono veri controlli a runtime:

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 stesso lancia un SyntaxError su un testo malformato, quindi il codice reale lo racchiude anche in un try/catch. Per payload grandi o annidati, i guard scritti a mano diventano lunghi; librerie di schemi come Zod o Valibot ti permettono di dichiarare la forma una volta sola e ricavarne sia il validatore sia il tipo TypeScript.

Da JSON a interfaccia TypeScript

Convertire un esempio di JSON in tipi è un lavoro meccanico. Data questa risposta:

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

Associa ogni valore al suo tipo, dai agli oggetti annidati un'interfaccia propria, e segna ciò che può variare:

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 solo esempio non può dirti quali campi sono opzionali o nullable. Guarda diverse risposte, o la documentazione dell'API, prima di decidere su ? e | null.

Date e il reviver

JSON non ha un tipo data, quindi le date arrivano come stringhe. Il secondo argomento di JSON.parse, il reviver, viene chiamato per ogni chiave e può ricostruirle:

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

Il parametro value del reviver è any, e lo è anche il risultato, quindi del tipo Order ci si fida ancora invece di controllarlo. JSON.stringify(order, null, 2) indenta l'output di due spazi e ritrasforma la Date nella sua stringa ISO.

JSON.stringify e ciò che perde

JSON.stringify è tipizzato per restituire string. I valori che converte non sempre tornano uguali, e il tipo non ti avvisa:

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

Le regole a runtime sono le stesse del JavaScript semplice, spiegate in JSON in JavaScript.

Un tipo per qualsiasi valore JSON

Quando il codice gestisce JSON arbitrario, un tipo ricorsivo descrive esattamente ciò che JSON può contenere e rifiuta i valori che non può contenere:

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

Senza il commento, l'ultima riga è un errore di compilazione perché un oggetto Date non è un JsonValue.

Importare file .json

Un file .json si può importare come un modulo, e TypeScript ne deduce il tipo dal contenuto:

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

In TypeScript 7 questo funziona senza impostazioni aggiuntive con module impostato a nodenext, node20, commonjs, esnext o preserve. Con node16 e node18 fallisce con l'errore TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., finché non aggiungi "resolveJsonModule": true; impostarlo a false disattiva gli import JSON ovunque. In un ES module con nodenext o node20, l'import richiede l'attributo with { type: "json" } (errore TS1543 senza) ed è permesso solo l'import default (errore TS1544 per import { port }). tsc copia il file .json importato in outDir, accanto al JavaScript compilato.