Patrón Builder: Objetos Complejos sin Caos en TypeScript

¿Alguna vez te has encontrado con una clase que tiene un constructor con 10 parámetros, de los cuales 7 son opcionales? A esto se le conoce como el “Constructor Telescópico”, y es una de las formas más rápidas de ensuciar una base de código profesional. El patrón Builder es la solución elegante que la industria usa para resolver este problema.

El Problema: Constructores que Parecen Jeroglíficos

Cuando un objeto necesita muchas configuraciones, instanciarlo se vuelve una pesadilla. Tienes que pasar null o undefined en posiciones específicas solo para llegar al parámetro que sí te interesa. Esto no solo es difícil de leer, sino que es propenso a errores humanos silenciosos.

// ❌ El "Constructor Telescópico": frágil y confuso
const usuario = new Usuario(
  "Juan",
  "juan@email.com",
  null,       // teléfono (no tenemos)
  undefined,  // avatar (opcional)
  "Lima",
  true,       // ¿qué significa este boolean en posición 6?
  false,
);

La Promesa: Hoy aprenderás a implementar el patrón Builder para construir objetos paso a paso, ganando legibilidad, validación centralizada y mantenibilidad a largo plazo.

La Analogía: El Menú de un Restaurante 🍽️

Imagina que vas a un restaurante. El “Plato Principal” es obligatorio, pero la “Bebida” y el “Postre” son opcionales.

En lugar de que el mesero te pregunte por todo en una sola frase interminable, tú vas armando tu pedido: “Quiero este plato de fondo… ah, y agrega esta bebida”. Al final, el mesero “construye” tu orden completa con todo lo que confirmaste. El Builder funciona exactamente así.

Implementación Práctica del Patrón Builder en TypeScript

1. La Clase Objetivo (el Objeto a Construir)

Primero definimos el objeto final. Nota que los campos son readonly para garantizar la inmutabilidad: una vez construido, el objeto no puede ser modificado accidentalmente.

// La clase que queremos construir de forma controlada
class Menu {
  constructor(
    public readonly platoPrincipal: string,
    public readonly bebida?: string,
    public readonly postre?: string,
  ) {}

  displayInfo(): void {
    console.log(`
    TU MENÚ CONTIENE:
    Plato principal : ${this.platoPrincipal}
    Bebida          : ${this.bebida ?? "No seleccionado"}
    Postre          : ${this.postre ?? "No seleccionado"}
    `);
  }
}

2. La Interfaz del Builder

Definir una interfaz primero nos obliga a respetar el contrato y facilita la creación de implementaciones alternativas (útil para testing).

// Contrato que cualquier MenuBuilder debe cumplir
interface IMenuBuilder {
  setPlatoPrincipal(plato: string): this;
  setBebida(bebida: string): this;
  setPostre(postre: string): this;
  build(): Menu;
}

3. La Implementación del Builder

El truco clave es que cada método set retorna this, lo que habilita el encadenamiento fluido (fluent interface).

class MenuBuilder implements IMenuBuilder {
  private platoPrincipal?: string;
  private bebida?: string;
  private postre?: string;

  setPlatoPrincipal(plato: string): this {
    this.platoPrincipal = plato;
    return this; // Retornamos 'this' para permitir el encadenamiento
  }

  setBebida(bebida: string): this {
    this.bebida = bebida;
    return this;
  }

  setPostre(postre: string): this {
    this.postre = postre;
    return this;
  }

  build(): Menu {
    // El método build() es el único punto de validación de negocio
    if (!this.platoPrincipal) {
      throw new Error("El plato principal es obligatorio para construir el menú.");
    }

    return new Menu(this.platoPrincipal, this.bebida, this.postre);
  }
}

4. Ejemplo de Uso: Flexibilidad Total

Mira qué limpio y explícito queda el código al instanciar diferentes tipos de menús. Sin posiciones mágicas, sin null ni undefined innecesarios.

// ✅ Menú completo con bebida y postre
const menuCompleto = new MenuBuilder()
  .setPlatoPrincipal("Arroz con leche verde")
  .setBebida("Chicha morada")
  .setPostre("Mazamorra morada")
  .build();

// ✅ Menú simple saltando la bebida sin ningún problema
const menuSimple = new MenuBuilder()
  .setPlatoPrincipal("Seco de Cordero")
  .setPostre("Postre de cereza")
  .build();

menuCompleto.displayInfo();
menuSimple.displayInfo();

// ✅ El Builder nos protege de instanciaciones inválidas
try {
  const menuInvalido = new MenuBuilder().build(); // ❌ Lanza Error
} catch (e) {
  console.error(e.message); // "El plato principal es obligatorio..."
}

Beneficios Reales en tu Arquitectura Backend

Beneficio	Descripción
Legibilidad	El código cuenta una historia: qué se está configurando y por qué.
Validación	`build()` es el único punto de verdad para garantizar que el objeto es válido.
Mantenibilidad	Añadir un campo nuevo solo requiere actualizar el Builder, sin romper código existente.
Testabilidad	Puedes crear `MockMenuBuilder` para pruebas sin tocar la clase real.
Inmutabilidad	Los campos `readonly` en la clase destino previenen mutaciones accidentales.

Mejores Prácticas al Usar el Patrón Builder

Centraliza las validaciones en build(): Nunca valides en los setters individuales; el Builder debe entregar un objeto siempre válido o fallar explícitamente.
Usa interfaces: Programar contra IMenuBuilder en lugar de MenuBuilder permite sustituir implementaciones en tests sin cambiar el código de producción.
Considera el Director: Para configuraciones muy repetitivas, puedes crear una clase Director que encapsule secuencias de construcción comunes (ej: Director.crearMenuVegetariano(builder)).
No abuses del patrón: Si tu objeto solo tiene 2-3 campos obligatorios, un constructor directo es más simple y preferible.
Aplícalo en integraciones con APIs: Al construir payloads para servicios externos con muchos campos opcionales (Stripe, SendGrid, AWS SDK), el Builder brilla enormemente.

Conclusión

El patrón Builder es esencial cuando manejas configuraciones complejas o integraciones con APIs externas donde muchos campos son opcionales. En el ecosistema de TypeScript y Node.js, es un estándar de la industria para mantener servicios limpios, testeables y fáciles de extender.

¿Sientes que tu proyecto actual tiene clases demasiado complejas o difíciles de mantener? Como Senior Backend Engineer, ayudo a empresas en Perú y el extranjero a refactorizar sus sistemas para que sean escalables y eficientes. Agenda una asesoría técnica de 15 minutos y analicemos juntos cómo optimizar tu arquitectura.

Artículos relacionados: