Author: Dominicode

¿Te fiarías de un mensaje de WhatsApp para pagar una factura importante? No. Entonces, ¿por qué confías en que la red te devuelva exactamente el JSON que tu UI necesita?

Poca gente lo dice tan claro: la red es hostil. Los backends cambian, las APIs se versionan mal y los datos llegan raros. TypeScript te da sensaciones de seguridad en el editor. Fuera de la compilación, la realidad es JavaScript indiferente. Tipar una API REST no es cuestión de estética. Es la barrera que separa una app que sobrevive a la producción de un desastre nocturno.

Voy a contarte cómo tipar correctamente una API REST en TypeScript sin postureo. Con ejemplos prácticos, decisiones arquitectónicas y la única verdad que importa: que tu app no rompa en prod por culpa de un campo faltante.

Primera regla: el contrato no es el código. Es la promesa. Y debe ser verificable.

Resumen rápido (lectores con prisa)

Qué es: Validar y tipar el JSON recibido de la red en tiempo de ejecución usando esquemas (por ejemplo Zod) junto a tipos TypeScript.

Cuándo usarlo: Siempre en boundaries de red; imprescindible para APIs externas o equipos distintos.

Por qué importa: Previene errores silenciosos en producción y permite estrategias de error diferenciadas.

Cómo funciona: Fetch/axios → recibir unknown → parse con Zod (o similar) → mapear a modelos internos.

¿Por qué los tipos por sí solos no bastan?

TypeScript vive en tiempo de compilación. Cuando haces fetch o llamas a Axios, recibes JSON en tiempo de ejecución. TypeScript no inspecciona la red. Usar as T es firmar un cheque sin fondos: le estás diciendo al compilador “confía en mí”, pero nadie te va a confiar cuando el objeto tenga un null donde esperabas string.

Eso genera errores silenciosos: undefined que se propaga, componentes que se caen sin stack trace claro, tests que pasan porque los mocks también mienten. La alternativa no es renunciar a TypeScript. Es complementarlo con validación runtime donde pinte.

Paso 1 — Define el contrato: DTO claro y aislado

Haz DTOs en su propio archivo. Separa lo que viene de la red de tus modelos internos.

Ejemplo:

// api/types.ts
export interface UserResponse {
  id: string;
  email: string;
  full_name: string; // nota: formato snake_case típico de backend
  created_at: string;
}

export interface ApiError {
  statusCode: number;
  message: string;
  errorCode?: string;
}

¿Por qué aislarlo?

Porque si el backend cambia full_name → fullName, no quieres que todo tu frontend explote. Cambias la capa de red y mapping. Punto.

Paso 2 — Wrappers: encapsula fetch/axios

No llames fetch o axios.get en mitad del componente. Haz un wrapper que:

• haga la petición,
• valide el payload,
• normalice nombres,
• lance errores tipados.

Con fetch:

async function fetchTyped(url: string, opts?: RequestInit): Promise {
  const res = await fetch(url, opts);
  const text = await res.text();
  let json;
  try {
    json = text ? JSON.parse(text) : {};
  } catch {
    throw new Error(`Invalid JSON from ${url}`);
  }
  if (!res.ok) throw Object.assign(new Error('HTTP error'), { status: res.status, body: json });
  return json as T; // todavía una aserción: complementa con validación runtime
}

Con Axios es más limpio:

import axios from 'axios';
async function get(url: string) {
  const res = await axios.get(url);
  return res.data;
}

Pero cuidado: Axios con genéricos es cómodo, no mágico. Sigue siendo una promesa de que la red devolverá lo que dijiste.

Paso 3 — Validación runtime: Zod o similar

Aquí se separan los novatos de los equipos que sobreviven. Zod no es moda; es la última capa de defensa. Define un esquema, parsea el JSON y obtienes tipado estático y validación a la vez.

Ejemplo con Zod:

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  full_name: z.string(),
  created_at: z.string(), // luego puedes transformar a Date si quieres
});

type UserResponse = z.infer<typeof UserSchema>;

async function fetchUser(id: string) {
  const raw = await fetchTyped<unknown>(`/api/users/${id}`);
  return UserSchema.parse(raw); // lanza un error si no coincide
}

Ventajas:

• Detectas inmediatamente datos corruptos.
• Los errores llegan con contexto (qué llave falló y por qué).
• Puedes transformar created_at a Date de forma declarativa.

Paso 4 — Manejo de errores tipados

No uses catch (e) { console.error(e) }. En TS moderno el error es unknown. Te obliga a respirar antes de leer.

Con Axios:

try {
  const u = await get<UserResponse>('/api/users/1');
} catch (err) {
  if (axios.isAxiosError(err)) {
    const server: ApiError | undefined = err.response?.data;
    console.error('Server:', server?.message ?? err.message);
  } else if (err instanceof z.ZodError) {
    console.error('Validation failed:', err.errors);
  } else if (err instanceof Error) {
    console.error('Network or runtime:', err.message);
  } else {
    console.error('Unknown error', err);
  }
}

¿Por qué esto importa?

Porque no es lo mismo que falles por validación (mal payload) que por HTTP 500 o por timeout. Cada caso requiere una estrategia distinta: retry, fallback UI, mostrar mensaje al usuario, reportar a Sentry con tags distintos.

Paso 5 — Normaliza y mapea en la capa de red

No dejes snake_case pululando por la app. Tradúcelo en la capa de consumo.

function mapUser(api: UserResponse) {
  return {
    id: api.id,
    email: api.email,
    fullName: api.full_name,
    createdAt: new Date(api.created_at),
  };
}

Así tus modelos internos usan camelCase y Date real, no strings sucios.

Decisiones arquitectónicas: cuándo validar y cuánto validar

• Si controlas backend y frontend (monorepo o contrato firme): validación runtime puede ser ligera o incluso obviada en puntos internos. Pero en los boundaries externos, sigue validando.
• Si consumes APIs públicas o equipos distintos: valida TODO. Sin excusas.
• Campos opcionales: define qué hacer cuando faltan. ¿Default? ¿Error? No improvises en el handler.

Performance y coste: ¿La validación runtime es lenta?

Sí, agrega CPU. No, no es un killer. Para la mayoría de apps es insignificante comparado con network. Si tu app maneja miles de respuestas por segundo, shardea validaciones o valida en capas: sólo validar payloads que entren a la lógica crítica.

Testing: no te olvides de tests de integración

Mocks unitarios son útiles, pero añade tests e2e que disparen la API real (o un sandbox) y verifiquen que las validaciones y mappings no rompen. Testear tipado estático no te salva si la red cambia; testear contra endpoint sí.

Checklist práctico (aplicable hoy)

1. Centraliza DTOs en src/api/types.ts.
2. Implementa un http wrapper (fetch/axios) que devuelva unknown.
3. Define Zod schemas para cada DTO.
4. Parsea el unknown con los schemas antes de castear a tipos.
5. Mappea a modelos internos (camelCase, Date).
6. Trata y tipa errores (Axios ZodError, Error genérico).
7. Agrega tests e2e para validar contratos.
8. Logea y reporta fallos con contexto (payload, endpoint, user id).

Antipatrones que debes romper hoy

• Usar as T en todo el código. Es la tapa del inodoro para ignorar problemas.
• Confiar en que “el backend no cambia porque somos amigos”.
• No versionar tus contratos. Versiona APIs y mantén backwards compatibility.
• Manejar errores con any. Eso borra información útil para debugging.

Metáfora que funciona: el contrato es la arquitectura del puente

Tu frontend es el tráfico. El backend es el río. Si el puente (contrato) no es firme y verificado, los coches caen al agua. Los tipos son el plano; la validación runtime es el inspector que revisa la soldadura antes de poner el primer coche encima.

Mini-guía de migración si tienes legado

• Prioriza endpoints críticos: pagos, auth, guardar datos de usuario. Valida primero allí.
• Añade schemas Zod incrementales; empieza por parse y logea sin bloquear; luego, cuando el tráfico confirme estabilidad, cambia a bloquear y fallar fast.
• Automatiza alerts: si un endpoint empieza a fallar por validación, dispara una tarea de mesa de ayuda y un PR para el backend. No lo ignores.

Y ahora, lo que pocas hojas blancas te dirán: la cultura importa

La técnica sola no arregla nada. Si los desarrolladores creen que validar es “trabajo extra” y no “seguridad mínima”, la herramienta se convertirá en una carpeta más del repo. Hazlo obligatorio en el CI:

• Test de contractos: correr zod.parse en un job.
• Rechazar PRs si los contratos no están actualizados.
• Mantén el mapping y los schemas en la misma PR que cambia el backend si controlas ambos.

¿Quieres algo listo para copiar y pegar?

Tengo un template completo: wrapper http (fetch + manejo de errores), ejemplo de schema Zod, mapping y un job de GitHub Actions que valida contratos en CI. Lo dejo preparado para TypeScript + React (Vite) o Next.js.

Haz esto ahora:

1. Crea src/api/
2. Pega el wrapper y el schema Zod del template.
3. Añade ci/validate-contracts.yml a tu pipeline.
4. Corre pnpm test:contracts en tu CI.

¿Te lo mando ya?

Responde “Mándame el template” y te paso:

• El wrapper http.ts listo.
• Un user.schema.ts con Zod y z.infer.
• Un ejemplo de fetchUser + mapping + test e2e.
• Un workflow de GitHub Actions que bloquea merges si falla la validación.

No es sexy. Es aburrido. Pero es lo que evita que pases la noche arreglando producción porque un created_at vino null.
Esto no acaba aquí.

FAQ

• ¿Por qué no son suficientes los tipos de TypeScript?
• ¿Qué es Zod y por qué usarlo?
• ¿Dónde debo validar: en backend o frontend?
• ¿No hará lenta la app la validación runtime?
• ¿Cómo manejar campos opcionales o faltantes?
• ¿Qué patrones debo evitar hoy mismo?

Porque TypeScript opera en tiempo de compilación. Los datos de la red llegan en tiempo de ejecución y pueden diferir del contrato. Validar runtime evita errores silenciosos y fallos en producción.

Zod es una biblioteca de esquemas para validación y parsing en runtime. Proporciona validación declarativa, errores con contexto y permite inferir tipos TypeScript desde el esquema.

Valida en ambos. El backend debe proteger su dominio; el frontend debe validar boundaries externos y usuarios malformados. Si controlas ambos, puedes relajar validaciones internas, pero nunca las boundaries públicas.

Añade CPU, sí, pero para la mayoría de aplicaciones el coste es insignificante frente a la latencia de red. Para sistemas de alto rendimiento, valida selectivamente o en capas.

Decide una política: default, error o fallback. Documenta la decisión y aplica la política consistentemente en la capa de red. No improvises en handlers dispersos.

Evita usar as T indiscriminadamente, confiar en que el backend no cambiará y manejar errores con any. También evita no versionar contratos y no tener tests contra endpoints reales.

Tiempo estimado de lectura: 6 min

¿Listo para dejar de escribir código como si fuera 2016? TypeScript 6.0 no es un parche: es un ultimátum. Lee rápido. Haz el plan. Y no lo dejes para mañana.

Tiempo estimado de lectura: 8 min

TypeScript 6.0 ya está aquí. Y no viene a hacerte la vida más fácil solo por cortesía: viene a exigir calidad. Si tu repo huele a “any” y a configuraciones por defecto, vas a ver errores. Muchos. Bienvenidos a la criba.

Resumen rápido (lectores con prisa)

TypeScript 6.0 activa “strict” por defecto, cambia el módulo por defecto a ESM y trae typings nativos para APIs modernas como Temporal y utilidades como getOrInsert en Map. Migrar requiere rama dedicada, pruebas y una estrategia gradual para modernizar módulos y reemplazar Date por Temporal.

Qué cambia en TypeScript 6.0

Primero: el golpe que no puedes ignorar — strict por defecto

Hasta ahora, muchos iniciaban proyectos con la mínima fricción posible. Eso se acabó. TS 6.0 crea nuevos proyectos con “strict”: true por defecto. Traducción al cristiano:

Si tu código vive de aserciones (as any, as unknown, as Tipo), la migración te sacará los esqueletos del armario. Buen momento para limpiar deuda técnica, no para hacer commits de pánico.

Ejemplo rápido: tsconfig mínimo ahora

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "esnext",
    "strict": true,
    ...
  }
}

Segundo: adiós CommonJS (por defecto), hola esnext

TS 6.0 asume ESM como estándar. El valor por defecto de module pasa a esnext. Esto es intencional: el mundo ya está usando imports nativos, top-level await y bundlers modernos.

Impactos prácticos:

¿Te preocupa Node legacy? Mantén compatibilidad en módulos concretos o transpila a CommonJS solo donde lo necesites. Pero el camino natural ahora es ESM.

Tercero: nuevas API que facilitan la vida (Temporal, getOrInsert…)

Temporal: el reemplazo sensato del desastre llamado Date

Temporal no es una moda. Es la API de fechas que por fin piensa en zonas horarias, mutabilidad y precisión. TS 6.0 trae typings nativos para Temporal, así que puedes usarla sin depender de librerías externas.

Ejemplo:

import { Temporal } from '@js-temporal/polyfill'; // en runtime, o nativo en motores que lo implementen

const ahora = Temporal.Now.plainDateTimeISO();
const proximaSemana = ahora.add({ days: 7 });
console.log(proximaSemana.toString());

Temporal hace que calcular intervalos, convertir zonas y sumar días deje de ser una pesadilla llena de bugs.

getOrInsert en Map: menos boilerplate, menos condiciones de carrera

La operación de “si existe devuélvelo, si no cálcula/crea e inserta” es un patrón recurrente. Con getOrInsert (o emplace) lo tienes atómico y tipado:

const cache = new Map();
const user = await cache.getOrInsert(id, async () => await fetchUsuario(id));

Esto evita el clásico:

if (!map.has(key)) map.set(key, factory());
const val = map.get(key);

Menos código, menos bugs, menos gente escribiendo race conditions cuando la función es asíncrona.

Cómo migrar sin incendiar el repo (plan paso a paso)

Plan práctico

Checklist práctico para cada repo

Riesgos reales y cuándo NO actualizar aún

No es un dogma: hay casos donde deberías esperar.

Si estás en uno de esos escenarios, planifica una migración progresiva y una ventana de compatibilidad.

Performance y el futuro del compilador (spoiler: se viene cambio de motor)

TS 6.0 es la última gran versión mayor que funciona sobre el compilador escrito en JS/TS. El equipo ha dejado claro que la arquitectura actual llegó a su techo en repos masivos, y se ha hablado de explorar compiladores nativos (Go u otras tecnologías). Eso implica:

No lo tomes como alarma: tómalo como señal para ordenar tu base de código ahora, antes de que el motor cambie.

Ejemplos rápidos que deberías probar hoy (copia-pega y juega)

Una metáfora rápida

TS 6.0 es el peaje en la autopista. Si vas en coche viejo sin luces, te obliga a parar y actualizar. Si ya vas con el coche bien afinado, pasas más rápido. Y sí: pagarás por entrar, pero el viaje será más predecible.

Cierre con plan de ataque corto (haz esto hoy)

CTA

¿Quieres la checklist automática para tu repo? Respóndeme con “MIGRAR MI REPO” y te envío el script que crea el branch, activa strict y lista los errores más críticos.

FAQ

¿Por qué TS 6.0 activa strict por defecto?

Porque busca elevar la calidad del código desde el inicio de nuevos proyectos. Activar strict reduce errores silenciosos relacionados con any, null y llamadas mal tipadas.

¿Tengo que migrar todo a ESM de inmediato?

No. La recomendación es migrar gradualmente: empuja módulos que ya usan bundlers modernos, mantén compatibilidad para paquetes legacy y transpila a CommonJS solo donde sea imprescindible.

¿Cómo empiezo a usar Temporal sin romper producción?

Introduce Temporal en módulos nuevos o en PRs pequeños. Usa el polyfill @js-temporal/polyfill en entornos que no lo soporten nativamente y añade pruebas para conversiones de zona horaria e intervalos.

¿Qué hago con dependencias que solo expone CommonJS?

Mantén wrappers de interop o transpila esos paquetes en tu pipeline. Prioriza reemplazos si la dependencia es crítica y no tiene roadmap hacia ESM.

¿Qué pruebas debo priorizar durante la migración?

Prioriza tests sobre parsers de entrada, handlers de API, webhooks y cualquier lógica que deserialice datos externos. Asegura que el CI falle si TypeScript en strict da errores.

¿Cómo evitar que un cambio de tsconfig rompa CI?

Haz la activación de strict en un branch con su propio pipeline, clasifica errores y crea PRs pequeños que corrigen grupos de errores. No merges hasta que el build en strict pase.