JSON en TypeScript: tipar JSON.parse, JSON a interface e imports

JSON.parse devuelve any, así que TypeScript acepta cualquier tipo al que asignes el resultado. Eso hace que tipar JSON parseado cueste una línea, y también significa que el tipo es una promesa que haces tú, no algo que compruebe el compilador:

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

El segundo objeto tiene age como el string "41". TypeScript sigue llamándolo number, porque any se puede asignar a cualquier cosa, y el programa imprime 411. Para JSON que acaba de escribir tu propio código, la anotación está bien. Para datos que vienen de una petición, un archivo o el local storage, valídalos.

Parsear a unknown

Tipar el resultado como unknown hace que el compilador exija una comprobación antes de usar cualquier propiedad:

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

console.log(data.name);

El error es index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Cada comprobación que escribas después estrecha data un poco más.

Validar con un type guard

Un type guard es una función que devuelve value is User. Cuando devuelve true, TypeScript trata el valor como un User a partir de ahí, y las comprobaciones de dentro son comprobaciones reales en tiempo de ejecución:

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 lanza por sí mismo un SyntaxError con texto mal formado, así que el código real también lo envuelve en try/catch. Con datos grandes o anidados, los guards escritos a mano se alargan; librerías de esquemas como Zod o Valibot te permiten declarar la forma una sola vez y derivar de ella tanto el validador como el tipo de TypeScript.

De JSON a interfaz de TypeScript

Convertir una muestra de JSON en tipos es mecánico. Dada esta respuesta:

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

Asigna a cada valor su tipo, da a los objetos anidados su propia interfaz y marca lo que puede variar:

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

Una sola muestra no puede decirte qué campos son opcionales o pueden ser null. Mira varias respuestas, o la documentación de la API, antes de decidir dónde van ? y | null.

Fechas y el reviver

JSON no tiene tipo fecha, así que las fechas llegan como strings. El segundo argumento de JSON.parse, el reviver, se llama para cada clave y puede reconstruirlas:

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

El parámetro value del reviver es any, y el resultado también, así que el tipo Order sigue siendo un acto de confianza y no una comprobación. JSON.stringify(order, null, 2) sangra la salida con dos espacios y convierte de nuevo el Date en su string ISO.

JSON.stringify y lo que pierde

JSON.stringify está tipado para devolver string. Los valores que convierte no siempre vuelven igual, y el tipo no te avisa:

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

Las reglas en tiempo de ejecución son las mismas que en JavaScript normal, y se explican en JSON en JavaScript.

Un tipo para cualquier valor JSON

Cuando el código maneja JSON arbitrario, un tipo recursivo describe exactamente lo que puede contener JSON y rechaza lo que no:

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

Sin el comentario, la última línea es un error de compilación, porque un objeto Date no es un JsonValue.

Importar archivos .json

Un archivo .json se puede importar como un módulo, y TypeScript infiere su tipo a partir del contenido:

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

En TypeScript 7 esto funciona sin configuración extra con module en nodenext, node20, commonjs, esnext o preserve. Con node16 y node18 falla con el error TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., hasta que añades "resolveJsonModule": true; ponerlo en false desactiva los imports de JSON en todos los casos. En un ES module con nodenext o node20, el import necesita el atributo with { type: "json" } (error TS1543 sin él) y solo se permite el import por defecto (error TS1544 para import { port }). tsc copia el archivo .json importado a outDir junto al JavaScript compilado.