Ports de salida: mandar datos a JavaScript desde un Cmd

De las dos direcciones de la frontera, la de salida es la que primero se necesita y la que mejor enseña el mecanismo, porque en ella la iniciativa es tuya y el recorrido del dato se sigue sin ambigüedad. Quieres que algo ocurra fuera de Elm: guardar una preferencia, copiar al portapapeles, pedir a una biblioteca de gráficas que se redibuje, escribir en un registro de telemetría. La tentación es pensar en ello como en una llamada, y el nombre no ayuda porque un port de salida se declara con la apariencia de una función corriente. Pero la firma dice otra cosa: no devuelve el efecto realizado, devuelve un Cmd. Es decir, devuelve un valor inerte que describe un envío y que no hará nada hasta que update lo entregue al runtime. Entender esa distinción es entender por qué el mecanismo preserva la pureza que el capítulo anterior defendía.

La firma delata la naturaleza del envío

Un port de salida se declara en un módulo marcado como port module y consiste en una firma sin cuerpo: el compilador genera la implementación. Lo que tú escribes es el nombre, el tipo del dato que quieres mandar y el tipo de retorno, que siempre es un comando. Fíjate en que el parámetro del comando se deja genérico: como el envío no produce ninguna respuesta que reentre en la aplicación, ese comando no puede generar mensajes de ningún vocabulario concreto, y por tanto encaja en cualquiera.

port module Almacen exposing (guardarNota, borrarNota)


-- Un dato sale, ningún mensaje vuelve: por eso el msg es libre
port guardarNota : String -> Cmd msg


-- Sin carga útil, se envía la unidad
port borrarNota : () -> Cmd msg


-- Con varios campos, un record de tipos permitidos
port registrarEvento : { nombre : String, valor : Int } -> Cmd msg

La restricción sobre qué puede cruzar es tan importante como la firma. Por un port viajan valores que el runtime sabe convertir a datos de JavaScript sin ambigüedad: números, cadenas, booleanos, la unidad, listas y arreglos, Maybe, records cuyos campos sean a su vez de tipos permitidos, y Json.Encode.Value para lo demás. Lo que no puede cruzar es tan revelador como lo que sí: no cruzan funciones, porque una función que atravesara la frontera sería exactamente la puerta de ejecución arbitraria que el diseño evita, y no cruzan tipos unión definidos por ti, porque su representación interna es un detalle del compilador que ningún contrato externo debería fijar.

El ciclo completo: persistir estado en el navegador

El caso canónico es guardar una parte del modelo en el almacenamiento local del navegador para recuperarla en la siguiente visita. Elm no tiene acceso a esa API y no lo tendrá, porque es una API imperativa, síncrona y con efectos sobre un espacio compartido: justo el tipo de superficie que el lenguaje delega en el anfitrión. El diseño habitual codifica la porción relevante del modelo, la manda por el port y deja que unas pocas líneas de JavaScript hagan la escritura.

port guardarEstado : Json.Encode.Value -> Cmd msg


codificar : Model -> Json.Encode.Value
codificar model =
    Json.Encode.object
        [ ( "tema", Json.Encode.string model.tema )
        , ( "volumen", Json.Encode.int model.volumen )
        ]


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        CambioTema nuevo ->
            let
                siguiente =
                    { model | tema = nuevo }
            in
            -- El modelo nuevo se persiste, no el viejo
            ( siguiente, guardarEstado (codificar siguiente) )

        Silenciar ->
            ( { model | volumen = 0 }, Cmd.none )

Del lado del anfitrión, el objeto de la aplicación expone cada port de salida con un método de suscripción al que se le pasa la función que recibirá el dato. Esa función se ejecuta cada vez que el runtime despacha un comando de ese port, con el valor ya convertido a un objeto ordinario de JavaScript.

const app = Elm.Main.init({
  node: document.getElementById("raiz"),
});

app.ports.guardarEstado.subscribe(function (datos) {
  try {
    localStorage.setItem("estado", JSON.stringify(datos));
  } catch (e) {
    // El almacenamiento puede estar lleno o bloqueado
    app.ports.fallo.send("no se pudo guardar");
  }
});

sequenceDiagram
participant U as update
participant R as runtime
participant J as anfitrion JS
participant S as almacenamiento
U->>R: Cmd de guardarEstado
R->>J: dato ya convertido
J->>S: escritura imperativa
S-->>J: exito o excepcion
J->>R: send por port de entrada
R->>U: Msg de confirmacion

Sin retorno: cómo se obtiene confirmación

Un port de salida no informa de nada. No devuelve un valor, no produce un mensaje de éxito y no falla si el otro lado revienta: la excepción que lance el oyente de JavaScript se propaga por el bucle de eventos del navegador y la aplicación Elm ni se entera. Esta asimetría desconcierta al principio, pero es la consecuencia directa de que el envío sea un Cmd y no una petición. Cuando necesitas saber si la operación funcionó, la respuesta no llega por donde salió: llega como cualquier otro evento externo, es decir, por un port de entrada que produce una Sub y termina en un Msg.

El diseño resultante conviene planificarlo desde el principio en lugar de improvisarlo. Si cada operación externa tiene su propio port de salida y su propio port de respuesta, un proyecto mediano acumula veinte declaraciones y una superficie de contacto difícil de auditar. La alternativa más limpia es un solo port de salida que transporte un valor con una etiqueta y una carga, y un solo port de entrada que devuelva respuestas con la misma forma. El anfitrión se convierte entonces en un pequeño despachador y la frontera queda reducida a dos líneas en la fachada del módulo.

-- Una sola puerta, con la operación etiquetada dentro
port haciaFuera : Json.Encode.Value -> Cmd msg


peticion : String -> Json.Encode.Value -> Json.Encode.Value
peticion etiqueta carga =
    Json.Encode.object
        [ ( "op", Json.Encode.string etiqueta )
        , ( "datos", carga )
        ]


guardar : Model -> Cmd msg
guardar model =
    haciaFuera (peticion "guardar" (codificar model))