Kotlin/JS: `dynamic`, `external` y `@JsExport`

Kotlin/JS es el backend más antiguo después de la JVM y también el peor entendido, porque su premisa desafía la intuición: un lenguaje construido sobre la idea de que el compilador debe saberlo todo emite código para una plataforma cuya virtud principal es no saber nada hasta que se ejecuta. La resolución de esa tensión no consiste en imponer el sistema de tipos de Kotlin sobre JavaScript, cosa imposible, sino en trazar con precisión quirúrgica dónde termina el terreno comprobado y empieza el terreno de la promesa. A ese trazado sirven tres mecanismos que conviene no confundir porque resuelven problemas distintos: dynamic renuncia deliberadamente a la comprobación para un valor concreto, external afirma sin demostrar que algo existe fuera con una forma determinada, y @JsExport publica hacia afuera lo que se escribió dentro. Un objeto Kotlin compilado a JavaScript es un objeto JavaScript corriente, y esa identidad de representación es lo que hace barata la travesía y también lo que la hace peligrosa si uno se descuida.

Qué genera el compilador

El compilador produce clases, funciones y propiedades de JavaScript perfectamente normales. No hay máquina virtual intermedia ni capa de emulación de objetos: una clase Kotlin es una clase de JavaScript, y una propiedad con acceso personalizado es un par de funciones de lectura y escritura declaradas en el prototipo. La biblioteca estándar viaja como código JavaScript sometido al mismo proceso de eliminación de código muerto que el resto del programa.

El sistema de módulos elegido cambia la forma de lo publicado más de lo que uno esperaría. Con los formatos heredados la estructura de paquetes se conserva y hay que usar nombres cualificados desde el otro lado; con módulos ES la información de paquete se descarta a propósito, para reducir el tamaño del paquete final y ajustarse a lo que el ecosistema espera, de modo que las declaraciones aparecen como exportaciones nombradas.

// Con modulos ES
import { procesarPedido } from 'mimodulo';
procesarPedido(pedido);

Hay un detalle que sorprende a todo el mundo la primera vez: el compilador deforma los nombres de las funciones para dar cabida a las sobrecargas, que JavaScript no tiene. Una función sobrecargada aparecerá al otro lado con un sufijo derivado de su firma, ilegible e inestable entre versiones. La anotación @JsName sirve para fijar el nombre generado y es obligatoria en la práctica siempre que se exponga una sobrecarga.

dynamic, o la renuncia deliberada

El tipo dynamic desactiva la comprobación estática para el valor que lo lleva. Sobre un valor dinámico se puede invocar cualquier método, leer cualquier propiedad y pasarle cualquier argumento: el compilador acepta la expresión sin objeciones y la traduce de forma literal, dejando que sea el motor quien decida en ejecución si aquello existía.

fun leerPerfil(usuario: dynamic): String {
    // Nada de esto se comprueba en tiempo de compilacion
    val nombre = usuario.perfil.nombre
    usuario.perfil.marcarVisitado(Date())
    return nombre as String
}

Dos propiedades del mecanismo merecen atención. La primera es que el resultado de casi cualquier operación sobre un valor dinámico vuelve a ser dinámico, con lo cual la renuncia se propaga corriente abajo y una sola variable mal contenida puede acabar destiñendo sobre módulos enteros. La segunda es que dynamic no puede usarse como supertipo, lo que impide construir jerarquías sobre él y limita el daño estructural que puede causar.

Hay una tercera propiedad, más sutil, que explica por qué este mecanismo es a la vez tan cómodo y tan traicionero: la conversión con as sobre un valor dinámico no siempre comprueba lo que uno cree. El compilador emite verificaciones para los tipos que sabe distinguir en ejecución, pero JavaScript no conserva información suficiente para separar unos tipos numéricos de otros, de modo que una conversión entre ellos puede tener éxito sobre un valor que no le corresponde y el error emergerá más tarde, lejos del punto donde se cometió.

La disciplina que funciona consiste en tratar lo dinámico como se trata un puerto de entrada sin validar: se admite en el borde, se convierte en la primera línea a un tipo propio y no se propaga ni una función más adentro.

data class Perfil(val nombre: String, val edad: Int)

fun adaptar(bruto: dynamic): Perfil = Perfil(
    nombre = bruto.nombre as String,
    edad = (bruto.edad as Number).toInt(),
)

external: describir lo que ya existe

Una declaración external es una promesa sin cuerpo: le dice al compilador que en el entorno hay algo con ese nombre y esa forma, y a partir de ahí el sistema de tipos trabaja con normalidad sobre una realidad que nadie ha comprobado. Es el mecanismo con el que se describe una biblioteca ajena para poder usarla con comprobación de tipos en lugar de con dynamic.

external interface Opciones {
    var reintentos: Int
    var tiempoLimite: Int
}

external class Cliente(opciones: Opciones) {
    fun enviar(ruta: String, cuerpo: String): Promise<String>
}

external val version: String

La anotación que indica el módulo de procedencia es lo que conecta la declaración con la dependencia instalada, y sin ella el compilador supone que el nombre vive en el ámbito global.

@file:JsModule("@stripe/stripe-js")

external fun loadStripe(clave: String): Promise<Stripe>

external interface Stripe {
    fun elements(opciones: Opciones): Elements
}

Las interfaces externas son una construcción puramente de compilación: no tienen información de tipos en ejecución, así que no pueden aparecer en comprobaciones con is, no valen como argumento de tipo reificado y una conversión con as hacia ellas siempre tiene éxito, lo cual significa que no comprueba nada. Son útiles precisamente por eso, para dar forma a un objeto de configuración sin generar código, pero conviene saber que no protegen de nada en ejecución.

flowchart TD
A[Codigo JavaScript existente] --> B{Como lo describo}
B -->|Sin tipos| C[dynamic]
B -->|Con tipos afirmados| D[external]
C --> E[Comprobacion en ejecucion por el motor]
D --> F[Comprobacion estatica sobre una promesa]
G[Codigo Kotlin propio] -->|JsExport| H[Visible desde JavaScript]
H --> I[Definiciones de tipos generadas]

@JsExport: publicar hacia afuera

Por omisión nada de lo que se escribe en Kotlin es visible desde JavaScript, y esa reserva es intencionada: permite al compilador eliminar sin miedo todo lo que no se use y renombrar lo que le convenga. La anotación @JsExport marca las declaraciones de nivel superior que deben sobrevivir con su nombre y aparecer en la superficie pública, y puede aplicarse a todo un fichero.

@JsExport
class Carrito {
    private val lineas = mutableListOf<Linea>()
    fun anadir(sku: String, cantidad: Int) { /* ... */ }
    fun total(): Double = lineas.sumOf { it.importe }
}

@JsExport
@JvmInline
value class Correo(val direccion: String) {
    init { require(direccion.contains("@")) { "Correo invalido" } }
}

No todo tipo puede exportarse. Los primitivos y las cadenas cruzan sin más; las colecciones se exponen mediante envoltorios que ofrecen vistas hacia los tipos nativos; Throwable se ve como un error; los tipos enteros sin signo no son exportables. Un valor de clase en línea sí puede exportarse y aparece al otro lado como una clase corriente, lo que permite conservar la validación del constructor a través de la frontera. Para interfaces existe además una anotación que las proyecta como interfaces puras del sistema de tipos, sin residuo en ejecución, a cambio de renunciar a comprobarlas con is.

El compilador puede emitir un fichero de definiciones de tipos a partir de lo exportado, lo que convierte a un módulo Kotlin en una dependencia de primera clase para un equipo que trabaje en TypeScript. Ese fichero es también el mejor documento de revisión disponible: si lo generado resulta ilegible, la API estaba mal diseñada.

Merece la pena insistir en el carácter de contrato que adquiere lo exportado. Mientras una declaración no lleve la anotación, el compilador es libre de renombrarla, de moverla o de eliminarla si nadie la usa; en cuanto la lleva, ese nombre pasa a formar parte de la superficie pública del módulo con las mismas obligaciones de compatibilidad que cualquier API publicada. Exportar de más no es una imprudencia menor: aumenta el tamaño del artefacto porque impide descartar código, y compromete a mantener nombres que quizá solo existían como detalle interno.