typia para TypeScript: guia completo com exemplos

O que é typia e para que serve?

\n\n

typia é uma biblioteca poderosa para TypeScript que fornece verificação de tipos em tempo de execução (runtime type validation) com uma característica única: ela gera o código de verificação durante a compilação (compile-time), e não durante a execução. Isso a torna uma das bibliotecas mais rápidas para validação de dados no ecossistema TypeScript.

\n\n

Principais problemas que o typia resolve:

\n

\n
• Desempenho: Ao contrário de bibliotecas populares (zod, yup, io-ts), o typia não usa reflexão ou decoradores. Em vez disso, ele gera código de verificação otimizado durante a compilação, proporcionando um ganho de velocidade de 10 a 100 vezes.
\n
• Segurança de tipos: Você obtém a garantia de que os dados provenientes de fontes externas (API, banco de dados, formulários) correspondem às suas interfaces TypeScript.
\n
• Mínimo boilerplate: Você não precisa escrever esquemas de validação separados — o typia usa seus tipos TypeScript existentes.
\n
• Suporte a tipos complexos: Union, intersection, conditional types, mapped types — tudo funciona "pronto para uso".
\n

\n\n

A biblioteca é especialmente útil para:

\n

\n
• Desenvolvimento backend em Node.js com TypeScript
\n
• Aplicações frontend que exigem validação de formulários ou respostas de API
\n
• Arquitetura de microsserviços, onde a velocidade de serialização/desserialização é importante
\n
• Projetos onde o desempenho e a segurança de tipos são críticos
\n

\n\n

Instalação

\n\n

A instalação do typia consiste em duas etapas: a própria biblioteca e o transformador TypeScript (compilador).

\n\n

Passo 1. Instalação via npm

\n

npm install typia\n# ou\nyarn add typia\n# ou\npnpm add typia

\n\n

Passo 2. Instalação do transformador

\n

npm install --save-dev typia-transform\n# ou\nyarn add -D typia-transform\n# ou\npnpm add -D typia-transform

\n\n

Passo 3. Configuração do tsconfig.json

\n

Adicione o plugin ao seu tsconfig.json:

\n

{\n  "compilerOptions": {\n    "plugins": [\n      {\n        "transform": "typia-transform"\n      }\n    ]\n  }\n}

\n\n

Passo 4. Uso com ttypescript (recomendado)

\n

Instale o ttypescript para transformação automática:

\n

npm install --save-dev ttypescript

\n

Em seguida, substitua tsc por ttsc nos seus scripts do package.json:

\n

{\n  "scripts": {\n    "build": "ttsc",\n    "start": "node dist/index.js"\n  }\n}

\n\n

Importante: o typia requer TypeScript versão 4.4 ou superior. Sem o transformador, a biblioteca não funcionará.

\n\n

Início rápido com exemplo de código

\n\n

Vamos criar um exemplo simples de validação de dados de usuário.

\n\n

import typia from "typia";\n\n// Definindo a interface\ninterface IUser {\n  id: number;\n  name: string;\n  email: string;\n  age: number;\n  isActive: boolean;\n}\n\n// Criando a função de validação\nconst validateUser = typia.createValidate<IUser>();\n\n// Dados de teste\nconst testData = {\n  id: 1,\n  name: "Ivan Petrov",\n  email: "ivan@example.com",\n  age: 30,\n  isActive: true,\n};\n\n// Validação\nconst result = validateUser(testData);\n\nif (result.success) {\n  console.log("Dados válidos:", result.data);\n} else {\n  console.log("Erro de validação:", result.errors);\n}\n\n// Exemplo com dados incorretos\nconst badData = {\n  id: "não é número", // Deveria ser number\n  name: "Ivan",\n  email: "não é email",\n  age: -5,\n  isActive: "sim", // Deveria ser boolean\n};\n\nconst badResult = validateUser(badData);\nconsole.log("Erros:", badResult.errors);

\n\n

Este exemplo mostra como é fácil validar dados usando apenas a interface TypeScript. Sem esquemas ou decoradores adicionais!

\n\n

Métodos e funções principais

\n\n

1. typia.