Superstruct para TypeScript: guía completa con ejemplos

Introducción a Superstruct

\n\n

Superstruct es una biblioteca ligera pero potente para la validación y el análisis de estructuras de datos en TypeScript y JavaScript. Permite describir la forma esperada de los datos (objetos, arrays, cadenas, números, etc.) mediante "esquemas" (structs) simples y expresivos, y luego verificar si los datos reales se ajustan a estos esquemas.

\n\n

A diferencia de otras bibliotecas de validación como Zod o Yup, Superstruct se centra en la simplicidad, el rendimiento y el minimalismo. No genera tipos complejos de TypeScript automáticamente (aunque es compatible con ellos), sino que ofrece una API flexible e intuitiva para describir estructuras.

\n\n

¿Para qué sirve Superstruct?

\n

\n
• Validación de datos de fuentes externas: Respuestas de API, datos de formularios, archivos de configuración, localStorage — en cualquier lugar donde los datos puedan llegar en un formato inesperado.
\n
• Creación de DTO (Objetos de Transferencia de Datos) seguros: Garantiza que los datos transferidos entre capas de la aplicación cumplan con la estructura esperada.
\n
• Análisis y transformación: Superstruct no solo puede verificar, sino también transformar datos (por ejemplo, convertir cadenas a números).
\n
• Documentación legible: Los esquemas de Superstruct son en sí mismos una excelente documentación de cómo se ven los datos.
\n

\n\n

Instalación

\n\n

Superstruct es un paquete npm, por lo que la instalación se realiza a través del gestor de paquetes de Node.js:

\n\n

npm install superstruct

\n\n

O, si usas Yarn:

\n\n

yarn add superstruct

\n\n

Después de la instalación, puedes importar la biblioteca en tu archivo TypeScript:

\n\n

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

\n\n

Inicio rápido

\n\n

Vamos a crear un esquema simple para un usuario y verificar los datos.

\n\n

import { object, string, number, assert } from 'superstruct';\n\n// 1. Definimos el esquema (struct)\nconst User = object({\n    id: number(),\n    name: string(),\n    email: string(),\n});\n\n// 2. Datos que queremos verificar\nconst userData = {\n    id: 1,\n    name: 'Alice',\n    email: 'alice@example.com',\n};\n\n// 3. Validación\ntry {\n    assert(userData, User);\n    console.log('¡Datos válidos!');\n} catch (e) {\n    console.error('Error de validación:', e.message);\n}\n\n// 4. Si los datos son incorrectos, assert lanzará una excepción\nconst badData = { id: 'no es un número', name: 'Bob' };\ntry {\n    assert(badData, User);\n} catch (e) {\n    console.error('Error:', e.message);\n    // Salida: Expected a number for `id`, but received: "no es un número"\n}

\n\n

Métodos y funciones principales

\n\n

Superstruct proporciona un conjunto de fábricas para crear esquemas. Aquí están los 10 principales:

\n\n

1. string()

\n

Descripción: Crea un esquema que verifica que el valor sea una cadena.

\n

Parámetros: Ninguno.

\n

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

\n\n

2. number()

\n

Descripción: Verifica que el valor sea un número (incluyendo NaN, a menos que se especifique lo contrario).

\n

Parámetros: Ninguno.

\n

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

\n\n

3. boolean()

\n

Descripción: Verifica que el valor sea booleano (true o false).

\n

Parámetros: Ninguno.

\n

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