TypeBox TypeScript: métodos, exemplos, instalação |…

O que é TypeBox e por que você precisa dele?

TypeBox é uma biblioteca poderosa para TypeScript que permite definir esquemas de dados compatíveis com o padrão JSON Schema e, ao mesmo tempo, inferir tipos estáticos TypeScript corretos a partir deles. Em termos simples, é a ponte entre a validação de dados em tempo de execução (quando sua aplicação está rodando e verificando dados dinamicamente) e os tipos em tempo de compilação (quando o TypeScript verifica a correção do código antes de executá-lo).

Por que isso é importante? No desenvolvimento web moderno, os dados frequentemente vêm de fontes não confiáveis: requisições de API, formulários em sites, arquivos de configuração. Sem validação, você corre o risco de erros em tempo de execução que são difíceis de detectar. O TypeBox resolve esse problema de forma elegante: você descreve o esquema uma vez e obtém:

Validador em tempo de execução — verifica se um objeto corresponde ao esquema durante a execução do programa.
Tipo estático — o TypeScript infere automaticamente o tipo, que pode ser usado para anotações.
JSON Schema — o esquema pode ser serializado em JSON e usado em outras ferramentas (por exemplo, para gerar formulários de UI ou documentação).

TypeBox é ideal para: criar endpoints de API com validação do corpo da requisição, trabalhar com arquivos de configuração, construir formulários complexos com validação de campos e qualquer cenário onde a segurança de tipos em todas as etapas seja importante.

Instalação do TypeBox

TypeBox é uma biblioteca para Node.js/TypeScript, portanto é instalada via npm (ou yarn/pnpm).

npm install @sinclair/typebox

Após a instalação, você pode importá-la no seu projeto:

import { Type } from '@sinclair/typebox';

Para trabalhar com validação, você também precisará de um validador. O TypeBox não o inclui por padrão para deixar a escolha com o desenvolvedor. Recomenda-se usar @sinclair/typebox/compiler (compilador embutido) ou ajv (validador JSON Schema popular). Vamos instalar o compilador:

npm install @sinclair/typebox-compiler

Ou, se preferir o AJV:

npm install ajv ajv-formats

Observação: a biblioteca se chama @sinclair/typebox, não apenas typebox. Isso é importante para a instalação correta.

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

Vamos criar um esquema simples para um usuário e validá-lo.

import { Type } from '@sinclair/typebox';
import { TypeCompiler } from '@sinclair/typebox/compiler';

// 1. Definindo o esquema do usuário
const UserSchema = Type.Object({
    id: Type.Number(),
    name: Type.String({ minLength: 2 }),
    email: Type.String({ format: 'email' }),
    age: Type.Optional(Type.Number({ minimum: 0, maximum: 120 })),
});

// 2. Criando o compilador para validação
const validator = TypeCompiler.Compile(UserSchema);

// 3. Dados de teste
const validUser = {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    age: 30,
};

const invalidUser = {
    id: 'not-a-number',
    name: 'A',
    email: 'invalid-email',
};

// 4. Validação
console.log(validator.Check(validUser));   // true
console.log(validator.Check(invalidUser)); // false

// 5. Obtendo o tipo estático
type UserType = Static<typeof UserSchema>;
// Agora UserType é { id: number; name: string; email: string; age?: number; }

Neste exemplo, definimos um esquema, o compilamos em um validador e verificamos dois objetos. Observe o uso de Type.Optional para o campo age — ele pode estar ausente. Também usamos format: 'email' para validar o formato do email.