Evita el Desastre: Tipado de APIs Resilientes con TypeScript y Conditional Types - Dev.

Hace unos días, una actualización silenciosa en el backend transformó un campo id numérico en un uuid (string) sin previo aviso. El resultado fue una cascada de errores de renderizado en producción que los tests unitarios con mocks estáticos no detectaron. Este escenario es clásico cuando confiamos ciegamente en interfaces rígidas. Para garantizar la Estabilidad Frontend, no basta con definir tipos; necesitamos que estos sean lo suficientemente inteligentes para adaptarse o fallar explícitamente durante la compilación, no en el navegador del usuario.

Análisis: Por qué fallan las Interfaces Estándar

El enfoque tradicional de Diseño de tipos API implica replicar manualmente la estructura del JSON del backend en una interfaz de TypeScript. Sin embargo, esto crea un acoplamiento frágil. Si la respuesta puede variar (por ejemplo, un campo data que a veces es un objeto y otras un array, o errores que cambian la estructura del payload), las interfaces estáticas se vuelven un campo minado de any o uniones de tipos infinitas (TypeA | TypeB | TypeC).

El peligro del 'any' implícito

Utilizar any en respuestas API "complicadas" desactiva efectivamente el compilador de TypeScript, eliminando toda garantía de seguridad y autocompletado.

Para resolver esto sin perder la cordura, debemos recurrir a los Tipos avanzados TypeScript. Específicamente, necesitamos mecanismos que infieran la estructura correcta basándose en valores discriminantes (como un código de estado o un flag de éxito) en tiempo de compilación.

La Solución: Conditional Types e Infer

La clave para una arquitectura robusta reside en los Conditional Types. Podemos crear un tipo genérico que "decida" cuál es la forma de la respuesta basándose en sus parámetros de entrada. Además, utilizaremos la palabra clave infer para extraer tipos internos de promesas o estructuras anidadas automáticamente, reduciendo el código repetitivo.

A continuación, implementamos un patrón que discrimina automáticamente entre una respuesta exitosa y una de error, obligando al desarrollador a verificar el estado antes de acceder a los datos.

// Definimos la estructura base de nuestra respuesta
type BaseResponse = {
  timestamp: string;
  path: string;
};

// Definición de éxito
type Success<T> = BaseResponse & {
  status: 'success';
  data: T;
  error: null;
};

// Definición de error
type Failure = BaseResponse & {
  status: 'error';
  data: null;
  error: {
    code: number;
    message: string;
  };
};

// Conditional Type discriminado
// Si T es 'void', asumimos que no hay data, de lo contrario usamos T
type ApiResponse<T = void> = T extends void 
  ? Success<null> | Failure 
  : Success<T> | Failure;

// Utilidad avanzada con 'infer' para extraer el tipo de una Promesa de API
// Útil para uno de nuestros Consejos TypeScript: no repetir tipos manualmente
type ExtractApiData<T> = T extends Promise<ApiResponse<infer U>> ? U : never;

// --- Ejemplo de Uso ---

interface UserProfile {
  id: string;
  email: string;
}

// Función simulada de fetch
async function fetchUser(): Promise<ApiResponse<UserProfile>> {
  return {
    status: 'success',
    data: { id: '123', email: 'dev@example.com' },
    error: null,
    timestamp: new Date().toISOString(),
    path: '/api/user'
  };
}

async function handleRequest() {
  const response = await fetchUser();

  // TypeScript ERROR: La propiedad 'data' no existe en 'Failure'.
  // console.log(response.data.email); 

  // Corrección: El "Type Guard" es obligatorio gracias al Conditional Type
  if (response.status === 'success') {
    // Aquí TypeScript sabe al 100% que response es Success<UserProfile>
    console.log(response.data.email); 
  } else {
    // Aquí TypeScript sabe que response es Failure
    console.error(response.error.message);
  }
}

Buenas Prácticas

Siempre usa Conditional Types para forzar validaciones de nulos. Observa cómo en el código anterior es imposible acceder a data sin verificar primero status === 'success'.

Comparativa de Seguridad

Implementar este patrón mejora drásticamente la mantenibilidad frente a tipados laxos.

Enfoque	Seguridad en Runtime	Experiencia de Desarrollo (DX)
interface Simple	Baja (Permite acceso a propiedades nulas)	Rápida pero peligrosa
Genéricos con Partial<T>	Media (Requiere comprobaciones ? constantes)	Tediosa (Excesivo encadenamiento opcional)
Conditional Types (Discriminated Unions)	Alta (Garantizada por compilador)	Excelente (Autocompletado inteligente)

Consejos TypeScript: Usa la utilidad ExtractApiData definida arriba cuando necesites reutilizar el tipo de dato de una función de servicio en un componente de React o Vue, sin tener que importar la interfaz original manualmente.

Conclusión

El uso de Tipos avanzados TypeScript no es solo una cuestión de estética de código; es una defensa activa contra errores en producción. Al aprovechar infer y las uniones discriminadas, transformamos la incertidumbre de las respuestas HTTP en contratos estrictos que el compilador puede verificar. Esto asegura que cualquier cambio imprevisto en el Diseño de tipos API rompa la compilación localmente antes de romper la experiencia del usuario.