JSON em TypeScript: tipar JSON.parse, JSON para interface e imports

JSON.parse retorna any, então o TypeScript aceita qualquer tipo ao qual você atribua o resultado. Isso faz com que tipar JSON lido seja uma linha só, mas também significa que o tipo é uma promessa sua, não algo que o compilador verifica:

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

O segundo objeto tem age como a string "41". O TypeScript continua chamando isso de number, porque any pode ser atribuído a qualquer coisa, e o programa imprime 411. Para um JSON que o seu próprio código acabou de escrever, a anotação basta. Para dados de uma requisição, de um arquivo ou do local storage, valide.

Fazendo parse para unknown

Tipar o resultado como unknown faz o compilador exigir uma verificação antes de qualquer propriedade ser usada:

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

console.log(data.name);

O erro é index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Cada verificação que você escreve depois estreita data um pouco mais.

Validando com um type guard

Um type guard é uma função que retorna value is User. Quando ela retorna true, o TypeScript passa a tratar o valor como User, e as verificações dentro dela são verificações reais em tempo de execução:

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

O próprio JSON.parse lança um SyntaxError para texto malformado, então código real também o envolve em try/catch. Para payloads grandes ou aninhados, type guards escritos à mão ficam longos; bibliotecas de schema como Zod ou Valibot permitem declarar o formato uma vez e derivar dele tanto o validador quanto o tipo TypeScript.

JSON para interface TypeScript

Converter um exemplo de JSON em tipos é mecânico. Dada esta resposta:

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

Associe cada valor ao seu tipo, dê uma interface própria aos objetos aninhados e marque o que pode 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

Um único exemplo não diz quais campos são opcionais ou podem ser null. Olhe várias respostas, ou a documentação da API, antes de decidir onde vão ? e | null.

Datas e o reviver

JSON não tem tipo de data, então as datas chegam como strings. O segundo argumento de JSON.parse, o reviver, é chamado para cada chave e pode reconstruí-las:

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

O parâmetro value do reviver é any, e o resultado também, então o tipo Order continua sendo confiado, e não verificado. JSON.stringify(order, null, 2) indenta a saída com dois espaços e transforma o Date de volta na sua string ISO.

JSON.stringify e o que ele perde

JSON.stringify é tipado para retornar string. Os valores que ele converte nem sempre voltam iguais, e o tipo não 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

As regras em tempo de execução são as mesmas do JavaScript puro, explicadas em JSON no JavaScript.

Um tipo para qualquer valor JSON

Quando o código lida com JSON arbitrário, um tipo recursivo descreve exatamente o que o JSON pode conter e rejeita o que ele não pode:

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

Sem o comentário, a última linha é um erro de compilação, porque um objeto Date não é um JsonValue.

Importando arquivos .json

Um arquivo .json pode ser importado como um módulo, e o TypeScript infere o tipo a partir do conteúdo:

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

No TypeScript 7 isso funciona sem configurações extras com module definido como nodenext, node20, commonjs, esnext ou preserve. Com node16 e node18 falha com o erro TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., até você adicionar "resolveJsonModule": true; defini-la como false desativa imports de JSON em qualquer caso. Em um ES module com nodenext ou node20, o import precisa do atributo with { type: "json" } (erro TS1543 sem ele) e só o import default é permitido (erro TS1544 para import { port }). O tsc copia o arquivo .json importado para o outDir, ao lado do JavaScript compilado.