JSON para io-ts — decodifique e ganhe o tipo

O que esta ferramenta faz

Uma amostra JSON vira códecs io-ts, um const por objeto.

{ "id": 1, "name": "Ada", "address": { "city": "Paris" } }

import * as t from "io-ts";

export const Address = t.type({
  city: t.string,
});

export const Root = t.type({
  id: t.Int,
  name: t.string,
  address: Address,
});

Os filhos são declarados primeiro: códecs são valores de execução, um precisa existir antes que outro o mencione. Um array na raiz ganha o seu próprio códec — export const Users = t.array(UsersItem); — em vez de sobrar para você escrever.

t.Int é um tipo marcado, e isso aparece

t.Int é um refinamento de t.number que carrega uma prova de integralidade. t.TypeOf<typeof Root> dá então { id: Int; … }, não { id: number; … }. Um Int vai aonde se espera um number; o contrário exige um decode. Se esse atrito não compensa a checagem de inteiro na sua base, t.number é uma troca de uma palavra.

Qual dos dois você recebe depende de como o número foi escrito: 3 dá t.Int, 10.0 dá t.number. Até há pouco 10.0 também dava t.Int, e o códec recusava então 10.5 — o registro seguinte. Era um defeito real, encontrado ao escrever estas páginas e corrigido.

O que um códec deixa passar

t.type confere o que conhece e ignora o resto. Uma resposta com três campos a mais decodifica limpa. É a semântica de interface do io-ts, e é o padrão certo para ler a API de outra pessoa — mas se uma chave inesperada tiver de ser um erro, envolva a mesma forma em t.strict, ou em t.exact para removê-la.

Decodificar, em uma linha

import { isRight } from "fp-ts/Either";

const result = Root.decode(payload);
if (isRight(result)) { /* result.right está tipado */ }

PathReporter.report(result) transforma uma falha em caminhos legíveis — útil na primeira vez que um códec recusa uma carga que você julgava certa.

Tudo é obrigatório

Cada chave da amostra cai em t.type, ou seja, obrigatória. O io-ts escreve a opcionalidade num t.partial à parte, unido por t.intersection. Repartir suas chaves entre as duas metades é uma afirmação sobre a API; um documento não pode fazê-la por você.

Privado por padrão

Tudo é executado localmente no seu navegador com JavaScript. Os seus dados nunca são enviados para um servidor, o que torna a ferramenta segura para conteúdo sensível e funciona offline.