Escribir tu propio delegado

Los delegados de la biblioteca cubren los casos genéricos precisamente porque no saben nada de tu dominio. En cuanto la regla que quieres imponer menciona una clave de almacenamiento, un esquema, una unidad de medida o un ciclo de vida, ya no hay delegado prefabricado que valga y toca escribir el tuyo. La buena noticia es que el listón técnico es bajísimo: dos funciones y un tipo. La mala es que el listón de diseño es alto, porque un delegado convierte una llamada a función en algo que parece un campo, y esa apariencia es una promesa implícita —barato, sin efectos, sin fallos— que tu implementación debe honrar o desmentir con mucha claridad.

Los dos contratos con nombre

Nada te obliga a implementar una interfaz, pero hacerlo da un tipo nombrable al delegado y documenta dónde puede usarse:

public fun interface ReadOnlyProperty<in T, out V> {
    public operator fun getValue(thisRef: T, property: KProperty<*>): V
}

public interface ReadWriteProperty<in T, V> : ReadOnlyProperty<T, V> {
    public override operator fun getValue(thisRef: T, property: KProperty<*>): V
    public operator fun setValue(thisRef: T, property: KProperty<*>, value: V)
}

La varianza no es decorativa. T es contravariante, así que un delegado declarado sobre Any? sirve en cualquier clase y también en propiedades locales o de nivel superior, donde thisRef llega como null. Si en cambio lo declaras sobre una clase concreta, el compilador te garantiza que ese delegado jamás se usará fuera de ella —una restricción muy útil cuando el delegado necesita colaborar con su dueño—. V es covariante en la versión de solo lectura y forzosamente invariante en la de lectura y escritura, porque aparece en posición de entrada y de salida.

La tercera pieza es el proveedor, que ya viste en la primera lección y que ahora tiene un uso claro:

public fun interface PropertyDelegateProvider<in T, out D> {
    public operator fun provideDelegate(thisRef: T, property: KProperty<*>): D
}

flowchart LR
A[Construccion del objeto] --> B[provideDelegate una sola vez]
B --> C[Trabajo caro y metadatos]
C --> D[Delegado ya configurado]
D --> E[getValue en cada lectura]
D --> F[setValue en cada escritura]
style B fill:#f9e2af,color:#11111b
style D fill:#a6e3a1,color:#11111b

Los metadatos, y lo que cuestan

El segundo parámetro de los accesores es la joya del mecanismo, pero sus campos no valen todos lo mismo. property.name es prácticamente gratis: el compilador incrusta el nombre en el objeto de referencia que genera, sin tocar la reflexión. En cambio property.returnType, property.annotations, property.visibility o property.isLateinit exigen la librería kotlin-reflect completa en la JVM, cuestan órdenes de magnitud más y no están disponibles en todos los objetivos de compilación.

De ahí la regla de oro de esta lección: la información cara se consulta en provideDelegate y se guarda en el delegado; los accesores solo leen campos ya calculados. Un delegado que llama a property.annotations en cada lectura es un delegado que convierte un acceso a campo en una operación de milisegundos, y nadie que lea el código de llamada sospechará por qué.

El patrón de configuración por anotación, hecho bien, se parece a esto:

@Retention(AnnotationRetention.RUNTIME)
@Target(AnnotationTarget.PROPERTY)
annotation class Clave(val nombre: String)

// caro: solo desde provideDelegate, nunca desde getValue
fun claveDe(propiedad: KProperty<*>): String =
    propiedad.annotations.filterIsInstance<Clave>().firstOrNull()?.nombre
        ?: propiedad.name

Dos avisos sobre esa ruta. La anotación debe declararse con retención de ejecución y objetivo de propiedad, o simplemente no estará ahí cuando la busques. Y si el mismo código debe compilar para Kotlin/Native o Wasm, la reflexión completa no está disponible con las mismas garantías, así que la configuración por anotación deja de ser portable y el camino recomendable pasa a ser un parámetro explícito o la generación de código con KSP.

Un caso real: ajustes persistidos

El escenario es universal: una pantalla de preferencias respaldada por un almacén clave-valor, con tipos reales en el código y cadenas en el disco. Sin delegados acaba siendo un getter y un setter repetidos por cada ajuste, con la clave escrita a mano y por tanto susceptible de erratas.

import kotlin.properties.PropertyDelegateProvider
import kotlin.properties.ReadWriteProperty
import kotlin.reflect.KProperty

interface Almacen {
    fun leer(clave: String): String?
    fun escribir(clave: String, valor: String)
    fun registrar(clave: String)
}

interface Codec<T : Any> {
    fun decodificar(texto: String): T?
    fun codificar(valor: T): String
}

class Ajuste<T : Any>(
    private val clave: String,
    private val porDefecto: T,
    private val codec: Codec<T>,
    private val almacen: Almacen,
) : ReadWriteProperty<Any?, T> {

    override fun getValue(thisRef: Any?, property: KProperty<*>): T =
        almacen.leer(clave)?.let(codec::decodificar) ?: porDefecto

    override fun setValue(thisRef: Any?, property: KProperty<*>, value: T) {
        almacen.escribir(clave, codec.codificar(value))
    }
}

Y el proveedor, que es donde ocurre lo interesante: deriva la clave del nombre de la propiedad, la valida y la registra una única vez, al construir el objeto.

fun <T : Any> ajuste(
    porDefecto: T,
    codec: Codec<T>,
    almacen: Almacen,
    claveExplicita: String? = null,
) = PropertyDelegateProvider<Any?, Ajuste<T>> { _, propiedad ->
    val clave = claveExplicita ?: propiedad.name.aSnakeCase()
    require(clave.isNotBlank()) { "clave vacia para ${propiedad.name}" }
    almacen.registrar(clave)
    Ajuste(clave, porDefecto, codec, almacen)
}

class Preferencias(almacen: Almacen) {
    var temaOscuro: Boolean by ajuste(false, Codec.Booleano, almacen)
    var tamanoFuente: Int by ajuste(14, Codec.Entero, almacen)
    var idioma: String by ajuste("es", Codec.Texto, almacen, claveExplicita = "locale")
}

Lo que se ha ganado no es brevedad. Se ha ganado que la clave y el nombre no puedan divergir, que el valor por defecto viva junto a la declaración, que el conjunto de claves quede registrado sin mantener una lista aparte y que añadir un ajuste sea una línea que no puede olvidarse de nada. La decisión deliberada de exponer claveExplicita es el escape para cuando el nombre en disco ya está fijado por versiones anteriores.

Cuatro errores de diseño que se repiten

• Prometer barato y cobrar caro. Una propiedad parece una lectura de memoria. Si tu getValue hace entrada y salida, bloquea o puede lanzar, estás mintiendo con la sintaxis; ahí una función con nombre de verbo es más honesta.
• Guardar thisRef en un campo. Ya te lo entregan en cada llamada. Almacenarlo crea un ciclo de referencias entre objeto y delegado y convierte al delegado en una fuga potencial.
• Olvidar los hilos. Los accesores pueden invocarse concurrentemente. Si el delegado guarda estado mutable, es tuyo el deber de protegerlo; y si el proveedor devuelve una instancia compartida, ese estado pasa a ser global sin que se note en el código de llamada.
• Ignorar la serialización. El campo real de la clase es el delegado, no el valor. Cualquier herramienta que serialice por campos verá un objeto Ajuste donde esperaba un Boolean; los serializadores que trabajan sobre propiedades no tienen ese problema, pero conviene comprobarlo antes de descubrirlo en producción.