io-ts para TypeScript: guía completa con ejemplos

¿Qué es io-ts y para qué sirve?

\nio-ts es una biblioteca para TypeScript que resuelve uno de los problemas más comunes en el desarrollo con este lenguaje: la discrepancia entre los tipos estáticos (en tiempo de compilación) y los datos reales (en tiempo de ejecución). TypeScript es una herramienta excelente, pero su sistema de tipos solo funciona durante el desarrollo. Cuando tu aplicación se ejecuta, todos los tipos se borran. Si recibes datos de una API externa, de un formulario en un sitio web, de localStorage o de cualquier otra fuente no controlada por tu compilador, no puedes estar seguro de que los datos coincidan con los tipos declarados.\n

\nAquí es donde entra en juego la validación en tiempo de ejecución (runtime). io-ts te permite definir un esquema de datos una sola vez y luego usarlo para dos propósitos:\n

\n
• Tipado estático (compile-time): TypeScript infiere los tipos basándose en tu esquema, garantizando la seguridad del código durante la escritura.
\n
• Validación en tiempo de ejecución (runtime): io-ts verifica si los datos reales coinciden con tu esquema y devuelve un resultado exitoso o un error detallado.
\n

\nLa biblioteca se basa en el concepto de códecs (codecs). Un códec es un objeto que sabe cómo decodificar (verificar y transformar) datos sin procesar en un tipo TypeScript y cómo codificar (serializar) ese tipo de vuelta. Esto convierte a io-ts en una herramienta potente no solo para la validación, sino también para la serialización/deserialización segura de datos.\n

Instalación

\nio-ts es una biblioteca para el ecosistema Node.js y navegadores, por lo que se instala a través de npm (o yarn). Ten en cuenta que io-ts requiere fp-ts como peer dependency, ya que utiliza conceptos funcionales como Either y Option.\n

npm install io-ts fp-ts

\nO, si usas yarn:\n

yarn add io-ts fp-ts

\nDespués de la instalación, puedes importar la biblioteca en tu proyecto:\n

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

Inicio rápido: primer ejemplo

\nComencemos con un ejemplo sencillo. Supongamos que esperamos un objeto de usuario con los campos name (cadena) y age (número). Definamos el esquema con io-ts e intentemos validar algunos datos.\n

import * as t from 'io-ts';\nimport { isRight, isLeft } from 'fp-ts/Either';\n\n// 1. Definimos el esquema (códec)\nconst User = t.type({\n    name: t.string,\n    age: t.number,\n});\n\n// 2. Función para obtener el tipo de forma segura\ntype User = t.TypeOf<typeof User>;\n\n// 3. Datos para validar\nconst validData = { name: 'Alice', age: 30 };\nconst invalidData = { name: 'Bob', age: 'veinte' }; // age es una cadena, no un número\n\n// 4. Validación\nconst result1 = User.decode(validData);\nconst result2 = User.decode(invalidData);\n\nconsole.log(isRight(result1)); // true\nconsole.log(isLeft(result2));  // true\n\n// 5. Extraemos los datos (si la validación fue exitosa)\nif (isRight(result1)) {\n    const user: User = result1.right;\n    console.log(user.name); // Alice\n}\n\n// 6. Manejamos el error\nif (isLeft(result2)) {\n    console.error('Error de validación:', result2.left);\n    // Mostrará una lista de errores, por ejemplo:\n    // [ { value: 'veinte', context: [...], message: 'Invalid value "veinte" supplied to : { name: string, age: number }/age: number' } ]\n}\n

\nEn este ejemplo vemos el patrón clave: decode devuelve un Either<Errors, A> de la biblioteca fp-ts. Either es un contenedor que puede contener un error (tipo izquierdo) o un valor exitoso (tipo derecho). Verificamos el resultado usando las funciones isRight e isLeft.\n

Métodos y funciones principales de io-ts

\nio-ts proporciona