io-ts para TypeScript: guia completo com exemplos

O que é io-ts e para que serve?

\nio-ts é uma biblioteca para TypeScript que resolve um dos problemas mais dolorosos no desenvolvimento com esta linguagem: a divergência entre tipos estáticos (em tempo de compilação) e dados reais (em tempo de execução). TypeScript é uma ferramenta excelente, mas seu sistema de tipos funciona apenas durante o desenvolvimento. Quando sua aplicação é executada, todos os tipos são apagados. Se você recebe dados de uma API externa, de um formulário no site, do localStorage ou de qualquer outra fonte não controlada pelo seu compilador, não pode ter certeza de que os dados correspondem aos tipos declarados.\n

\nÉ aqui que entra a validação em tempo de execução (runtime). O io-ts permite que você defina um esquema de dados uma única vez e o utilize para dois propósitos:\n

\n
• Tipagem estática (compile-time): TypeScript infere os tipos com base no seu esquema, garantindo segurança do código durante a escrita.
\n
• Validação em tempo de execução (runtime): O io-ts verifica se os dados reais correspondem ao seu esquema e retorna um resultado bem-sucedido ou um erro detalhado.
\n

\nA biblioteca é baseada no conceito de codecs. Um codec é um objeto que sabe como decodificar (verificar e transformar) dados brutos em um tipo TypeScript e como codificar (serializar) esse tipo de volta. Isso torna o io-ts uma ferramenta poderosa não apenas para validação, mas também para serialização/desserialização segura de dados.\n

Instalação

\nio-ts é uma biblioteca para o ecossistema Node.js e navegadores, portanto é instalada via npm (ou yarn). Observe que o io-ts requer fp-ts como dependência peer, pois utiliza conceitos funcionais como Either e Option.\n

npm install io-ts fp-ts

\nOu, se você usa yarn:\n

yarn add io-ts fp-ts

\nApós a instalação, você pode importar a biblioteca no seu projeto:\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';

Início rápido: primeiro exemplo

\nVamos começar com um exemplo simples. Suponha que esperamos um objeto de usuário com os campos name (string) e age (número). Vamos definir o esquema com io-ts e tentar validar alguns dados.\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';\n\n// 1. Definimos o esquema (codec)\nconst User = t.type({\n    name: t.string,\n    age: t.number,\n});\n\n// 2. Função para obter o tipo de forma segura\ntype User = t.TypeOf<typeof User>;\n\n// 3. Dados para verificação\nconst validData = { name: 'Alice', age: 30 };\nconst invalidData = { name: 'Bob', age: 'vinte' }; // age - string, não número\n\n// 4. Validação\nconst result1 = User.decode(validData);\nconst result2 = User.decode(invalidData);\n\nconsole.log(isRight(result1)); // true\nconsole.log(isLeft(result2));  // true\n\n// 5. Extraímos os dados (se a validação passou)\nif (isRight(result1)) {\n    const user: User = result1.right;\n    console.log(user.name); // Alice\n}\n\n// 6. Tratamos o erro\nif (isLeft(result2)) {\n    console.error('Erro de validação:', result2.left);\n    // Exibirá uma lista de erros, por exemplo:\n    // [ { value: 'vinte', context: [...], message: 'Invalid value "vinte" supplied to : { name: string, age: number }/age: number' } ]\n}\n

\nNeste exemplo, vemos o padrão chave: decode retorna Either<Errors, A> da biblioteca fp-ts. Either é um contêiner que pode conter um erro (tipo esquerdo) ou um valor bem-sucedido (tipo direito). Verificamos o resultado usando as funções isRight e isLeft.\n

Métodos e funções principais do io-ts

\nio-ts fornece