Builders con seguridad de tipos

El nombre con el que se conoce a esta técnica, builders con seguridad de tipos, es una respuesta a una pregunta histórica que hoy casi nadie recuerda haber tenido. Durante décadas, la forma habitual de describir una estructura anidada en un programa fue escribirla como texto en otro idioma: XML, JSON, una plantilla, un fichero de configuración. Ese texto era inerte para el compilador, así que un nombre mal escrito o un elemento colocado donde no corresponde no se descubría hasta que el programa llegaba a la línea que lo leía, normalmente en producción y normalmente un viernes. La promesa del builder con receptor es que la estructura se escribe directamente en el lenguaje anfitrión, con la misma apariencia declarativa que tenía el texto, pero cada palabra es una llamada tipada que el compilador comprueba antes de que exista un ejecutable. Lo que sigue es la mecánica precisa de esa promesa, que resulta ser mucho más simple que su reputación.

Las tres líneas del patrón

El núcleo del patrón cabe en una función y no tiene ninguna parte oculta. Se crea una instancia mutable, se le entrega el bloque para que lo ejecute con ella como receptor, y se devuelve el resultado. Todo lo demás son variaciones sobre esas tres líneas.

class ConsultaBuilder {
    var tabla: String = ""
    private val condiciones = mutableListOf<String>()

    fun donde(expresion: String) { condiciones += expresion }

    fun construir(): String =
        "SELECT * FROM $tabla" +
            if (condiciones.isEmpty()) "" else " WHERE " + condiciones.joinToString(" AND ")
}

fun consulta(bloque: ConsultaBuilder.() -> Unit): String =
    ConsultaBuilder().apply(bloque).construir()

val sql = consulta {
    tabla = "usuarios"
    donde("edad >= 18")
    donde("activo = true")
}

Conviene leer con cuidado la línea que hace el trabajo. ConsultaBuilder() crea el acumulador; apply(bloque) invoca el bloque con esa instancia como receptor implícito, de modo que todo lo que el usuario escribe dentro son llamadas sobre ella; y construir() traduce el estado acumulado al valor que realmente interesa. El bloque no devuelve nada útil y por eso su tipo de retorno es Unit: su efecto entero es mutar el builder mientras se ejecuta.

Esa última observación tiene una consecuencia que sorprende a quien viene de la programación declarativa. El bloque de un DSL de construcción no es una descripción evaluada de forma perezosa: es código imperativo que se ejecuta de arriba abajo exactamente una vez, en el orden en que está escrito. Lo declarativo es la apariencia, no la ejecución, y esa diferencia se nota en cuanto alguien escribe un if o un for dentro del bloque y descubre, con alivio, que funciona.

val filtrada = consulta {
    tabla = "pedidos"
    if (soloRecientes) donde("fecha > '2026-01-01'")
    for (estado in estadosPermitidos) donde("estado = '$estado'")
}

Un tipo por nivel del árbol

La estructura anidada aparece cuando un builder ofrece funciones que, a su vez, aceptan un bloque con otro receptor. Cada nivel del árbol tiene su propia clase, y esa clase define exactamente qué puede escribirse allí. Un elemento que solo tiene sentido dentro de otro simplemente no existe como función fuera de él, y esa es la mitad de la seguridad de tipos que da nombre al patrón.

class MenuBuilder {
    private val entradas = mutableListOf<Entrada>()

    fun opcion(texto: String, accion: String) {
        entradas += Entrada.Opcion(texto, accion)
    }

    fun submenu(texto: String, bloque: MenuBuilder.() -> Unit) {
        val hijo = MenuBuilder().apply(bloque).construir()
        entradas += Entrada.Submenu(texto, hijo)
    }

    fun construir(): Menu = Menu(entradas.toList())
}

fun menu(bloque: MenuBuilder.() -> Unit): Menu = MenuBuilder().apply(bloque).construir()

La función submenu es el corazón del asunto y merece leerse instrucción a instrucción. Crea un builder nuevo, independiente del padre; le pasa el bloque del usuario para que lo ejecute con ese builder nuevo como receptor; le pide el resultado ya cerrado; y solo entonces lo añade a su propia lista. El hijo se incorpora al padre después de que su bloque haya terminado por completo, nunca antes, y eso significa que el árbol se construye de las hojas hacia la raíz aunque el código se lea de la raíz hacia las hojas.

sequenceDiagram
participant U as Bloque del usuario
participant P as Builder padre
participant H as Builder hijo
U->>P: submenu texto y bloque
P->>H: crea instancia nueva
P->>H: ejecuta el bloque con H como receptor
H->>H: acumula sus entradas
P->>H: pide construir
H-->>P: devuelve el nodo cerrado
P->>P: anade el nodo a su lista

Acumular y devolver

La distinción entre el objeto que acumula y el objeto que se devuelve es el segundo pilar del patrón, y es el que más veces se omite en el código real. El builder es mutable por necesidad: tiene que poder recibir aportaciones sucesivas desde el bloque. El resultado no debería serlo, porque va a viajar por el programa, a compartirse entre hilos y a servir de clave de comparación o de caché.

data class Menu(val entradas: List<Entrada>)

sealed interface Entrada {
    data class Opcion(val texto: String, val accion: String) : Entrada
    data class Submenu(val texto: String, val contenido: Menu) : Entrada
}

La llamada entradas.toList() dentro de construir no es un detalle cosmético. Sin ella, el Menu devuelto guardaría una referencia a la misma MutableList que el builder sigue teniendo, y cualquiera que conservase el builder podría alterar un menú ya entregado. La copia defensiva rompe ese vínculo y convierte el resultado en un valor cerrado del que nadie puede tirar hacia atrás.

// El builder queda inservible fuera del bloque
class MenuBuilder {
    private var cerrado = false
    fun construir(): Menu {
        check(!cerrado) { "este builder ya produjo su resultado" }
        cerrado = true
        return Menu(entradas.toList())
    }
}

La comprobación explícita es opcional pero educativa: hace visible que el builder tiene un ciclo de vida de un solo uso y que su existencia termina cuando el resultado nace. En un diseño maduro, el builder ni siquiera es público; lo público es la función de nivel superior y el tipo del resultado, de modo que el usuario nunca tiene en la mano una referencia al acumulador.