Concepto clave

Las mejores prácticas para librerías en TypeScript avanzado se centran en crear APIs tipadas de forma segura que sean flexibles para los usuarios pero restrictivas para prevenir errores. Esto implica diseñar tipos que capturen las intenciones del desarrollador y guíen su uso correcto, similar a cómo un manual de instrucciones detallado evita malos usos de una herramienta compleja.

En arquitecturas complejas, una librería bien tipada actúa como un contrato de interfaz entre componentes, donde los tipos definen claramente qué datos se esperan y qué se devuelve. Esto reduce los bugs en tiempo de compilación y mejora la experiencia del desarrollador con autocompletado predictivo y validaciones automáticas.

Cómo funciona en la práctica

Imagina que estás construyendo una librería para manejar solicitudes HTTP con tipos genéricos. En lugar de usar any o tipos básicos, defines tipos parametrizados que se adaptan al contexto específico del usuario.

// Ejemplo: Función genérica para fetch tipado
type ApiResponse = {
  data: T;
  status: number;
};

async function fetchApi(url: string): Promise> {
  const response = await fetch(url);
  const data = await response.json();
  return { data: data as T, status: response.status };
}

// Uso con tipo explícito
interface User {
  id: number;
  name: string;
}

const result = await fetchApi('/api/users/1');
// result.data es de tipo User, con autocompletado para .id y .name

Este enfoque permite que la librería sea reutilizable en diferentes contextos mientras mantiene la seguridad de tipos, evitando errores comunes como acceder a propiedades inexistentes.

Caso de estudio

Considera una librería para validación de formularios donde los tipos reflejan las reglas de validación. En lugar de validar en tiempo de ejecución con comprobaciones manuales, los tipos garantizan que solo se pasen datos válidos.

// Definición de tipos para validación
type ValidationRule = (value: T) => boolean;

class Validator {
  private rules: ValidationRule[] = [];

  addRule(rule: ValidationRule): this {
    this.rules.push(rule);
    return this;
  }

  validate(value: T): boolean {
    return this.rules.every(rule => rule(value));
  }
}

// Uso con tipos específicos
const emailValidator = new Validator()
  .addRule(value => value.includes('@'))
  .addRule(value => value.length > 5);

// TypeScript infiere que emailValidator.validate() espera un string
const isValid = emailValidator.validate('[email protected]'); // true

En este caso, los tipos previenen que se pasen números o objetos a la validación de emails, y el autocompletado ayuda a los usuarios a entender qué métodos están disponibles.

Errores comunes

Sobrecarga de tipos genéricos: Definir demasiados parámetros genéricos que complican la API. Solución: Limitar a 2-3 genéricos por función y usar tipos condicionales para casos complejos.
Tipos demasiado permisivos: Usar any o unknown sin restricciones, lo que elimina los beneficios de TypeScript. Solución: Siempre preferir tipos específicos o genéricos acotados.
Documentación insuficiente de tipos: Asumir que los usuarios entenderán tipos complejos sin ejemplos. Solución: Incluir comentarios JSDoc y ejemplos de uso en la documentación.
Ignorar la inferencia de tipos: Forzar a los usuarios a especificar tipos manualmente cuando TypeScript puede inferirlos. Solución: Diseñar APIs que aprovechen la inferencia automática.
No probar tipos: Confiar solo en pruebas de ejecución sin validar los tipos. Solución: Usar herramientas como tsd para escribir pruebas de tipos.

Checklist de dominio

¿Tu librería usa tipos genéricos para hacer APIs flexibles pero seguras?
¿Los tipos previenen errores comunes como acceder a propiedades inexistentes?
¿La documentación incluye ejemplos de uso con tipos explícitos?
¿Has probado los tipos con herramientas como tsd para garantizar su corrección?
¿Los usuarios pueden aprovechar la inferencia de tipos para reducir código boilerplate?
¿Los mensajes de error de TypeScript son claros y ayudan a depurar?
¿La librería sigue convenciones de nomenclatura consistentes para tipos (ej. sufijos como Config, Options)?

Refactorizar una librería de utilidades con tipos seguros

En este ejercicio, refactorizarás una librería existente que maneja operaciones de array con tipos débiles para usar patrones genéricos y tipado profundo.

Descarga o copia el siguiente código inicial que tiene problemas de tipado:

// Código inicial con tipos débiles
function filterArray(arr: any[], predicate: any): any[] {
  return arr.filter(predicate);
}

function mapArray(arr: any[], mapper: any): any[] {
  return arr.map(mapper);
}

// Uso problemático
const numbers = [1, 2, 3, 4];
const filtered = filterArray(numbers, (x) => x > 2); // Tipo: any[]
const mapped = mapArray(filtered, (x) => x.toString()); // Tipo: any[]

Refactoriza las funciones filterArray y mapArray para usar genéricos. Asegúrate de que:

filterArray acepte un array de tipo T y un predicado que devuelva un booleano para T, devolviendo un array de T.
mapArray acepte un array de tipo T y un mapeador que transforme T a U, devolviendo un array de U.

Escribe ejemplos de uso que demuestren la seguridad de tipos, como operaciones encadenadas con autocompletado.
Opcional: Añade tipos condicionales para manejar casos edge, como arrays vacíos o tipos nulos.

Pistas

Usa T y U como parámetros genéricos para representar los tipos de entrada y salida.
Considera usar Array<T> como tipo de parámetro para mayor claridad.
Prueba tu refactorización con diferentes tipos de datos (ej. strings, objetos) para asegurar flexibilidad.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Quiz: Mejores Prácticas para Librerías

Quiz Interactivo