Superstruct para TypeScript: guia completo com exemplos

Introdução ao Superstruct

\n\n

Superstruct é uma biblioteca leve, porém poderosa, para validação e análise de estruturas de dados em TypeScript e JavaScript. Ela permite descrever a forma esperada dos dados (objetos, arrays, strings, números, etc.) usando "esquemas" (structs) simples e expressivos, e então verificar se os dados reais correspondem a esses esquemas.

\n\n

Diferente de outras bibliotecas de validação, como Zod ou Yup, o Superstruct foca em simplicidade, desempenho e minimalismo. Ele não gera tipos TypeScript complexos automaticamente (embora seja compatível com eles), mas oferece uma API flexível e intuitiva para descrever estruturas.

\n\n

Para que serve o Superstruct?

\n

\n
• Validação de dados de fontes externas: Respostas de API, dados de formulários, arquivos de configuração, localStorage — em qualquer lugar onde os dados possam chegar em um formato inesperado.
\n
• Criação de DTOs (Data Transfer Objects) seguros: Garante que os dados transmitidos entre as camadas da aplicação correspondam à estrutura esperada.
\n
• Análise e transformação: O Superstruct pode não apenas validar, mas também transformar dados (por exemplo, converter strings em números).
\n
• Documentação legível: Os esquemas do Superstruct por si só são uma excelente documentação de como os dados se parecem.
\n

\n\n

Instalação

\n\n

Superstruct é um pacote npm, portanto a instalação é feita através do gerenciador de pacotes Node.js:

\n\n

npm install superstruct

\n\n

Ou, se você usa Yarn:

\n\n

yarn add superstruct

\n\n

Após a instalação, você pode importar a biblioteca no seu arquivo TypeScript:

\n\n

import { struct, string, number, object, array, optional, union, literal, enums, size, refine, assert, is, validate } from 'superstruct';

\n\n

Início rápido

\n\n

Vamos criar um esquema simples para um usuário e validar os dados.

\n\n

import { object, string, number, assert } from 'superstruct';\n\n// 1. Definir o esquema (struct)\nconst User = object({\n    id: number(),\n    name: string(),\n    email: string(),\n});\n\n// 2. Dados que queremos validar\nconst userData = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n};\n\n// 3. Validação\ntry {\n    assert(userData, User);\n    console.log('Dados válidos!');\n} catch (e) {\n    console.error('Erro de validação:', e.message);\n}\n\n// 4. Se os dados estiverem incorretos, assert lançará uma exceção\nconst badData = { id: 'não é número', name: 'Bob' };\ntry {\n    assert(badData, User);\n} catch (e) {\n    console.error('Erro:', e.message);\n    // Saída: Expected a number for `id`, but received: "não é número"\n}

\n\n

Principais métodos e funções

\n\n

O Superstruct fornece um conjunto de fábricas para criar esquemas. Aqui estão 10 principais:

\n\n

1. string()

\n

Descrição: Cria um esquema que verifica se o valor é uma string.

\n

Parâmetros: Nenhum.

\n

import { string, assert } from 'superstruct';\n\nconst NameSchema = string();\nassert('Hello', NameSchema); // OK\n// assert(123, NameSchema); // Erro: Expected a string, but received: 123

\n\n

2. number()

\n

Descrição: Verifica se o valor é um número (incluindo NaN, a menos que especificado de outra forma).

\n

Parâmetros: Nenhum.

\n

import { number, assert } from 'superstruct';\n\nconst AgeSchema = number();\nassert(30, AgeSchema); // OK\n// assert('30', AgeSchema); // Erro

\n\n

3. boolean()

\n

Descrição: Verifica se o valor é booleano (true ou false).

\n

Parâmetros: Nenhum.

\n

import { boolean, assert } from 'superstruct';\n\nconst IsActiveSch