Forem: agj

elm-simple-icons: Another Elm package

agj — Tue, 14 Apr 2026 21:40:16 +0000

I released a new Elm package: agj/elm-simple-icons, an Elm conversion of a project called Simple Icons. It's a collection of icon versions of many logos for brands and projects. This is a practical tool to have lying around to, say, put a little Wikipedia icon next to a link pointing to a Wikipedia article, or otherwise visually annotate content related to external services. I sent a PR to the Simple Icons project to add my package to their list of “third party extensions,” and it's already listed on their website next to many other similar packages.

Frankly, the project lies in a bit of a legal gray area, since these logos are their respective owners' copyright and whatnot. The Simple Icons project tries to deflect this problem by offering a legal disclaimer. Some brands are not included precisely because their owners have opted out. So it has a bit of that “piracy vibe” to it, although this being just branding material it's nothing very serious. This is only use of visual material that these brands have chosen to be their public face. Now, on my side I've also linked to their disclaimer, and I made sure to put license and branding information in the documentation for each icon in the package, for those cases in which it's available (admittedly not many).

My package, being a repackaging of the Simple Icons SVGs, is automatically generated from that source data. I briefly considered using elm-codegen for that task, but I concluded that while it would be a great solution for generating the Elm code itself, it would be less ideal for the data munging part of it—I'd probably need to pass data in and out of Elm more than I would like. Also, the setup complexity cost was higher.

So I used Nushell for the code generation. It was actually really easy; the script is under 300 lines. It just reads the SVG data and converts it into Elm syntax, which is made simple thanks to Nushell's support for parsing XML data. Another big part of the script is generating the documentation, which is also simple since the source package includes a big JSON metadata file; I just need to surface that information.

For the user-facing API I researched Elm icon libraries, and ended up loosely basing mine on the Phosphor icons package solution. My package is not a traditional icons library, as each icon has its own brand color associated to it, and they also have a <title> element with the brand name, which shows up as a mouse hover “tooltip” on browsers. So those two things, plus the icon size, were what I allow to configure via a “builder pattern” interface of with* functions, ending in a toHtml function that takes an optional list of HTML attributes. So far, so good.

SimpleIcons.elm
    |> SimpleIcons.withColor "#FF00FF"
    |> SimpleIcons.withSize "50px"
    |> SimpleIcons.withNoTitle
    |> SimpleIcons.toHtml [ Html.Attributes.class "icon" ]

It's still a work in progress, but I'm also coding up a Nushell script to make it easier to keep my package up-to-date with the source package. It uses npm-check-updates to update the version in package.json, regenerates stuff, then tries to update version numbers all around. I'm trying to get it to also update the changelog with added and removed icon names. Might I even put this all in a Github Action, to fully automate the process? Not likely, since I don't trust the automation enough to let it publish a package on my behalf. Maybe to generate a PR, but eh, most likely not worth the trouble.

I also put good effort into making sure that the code and the documentation are solid. For one, I added tests for each configuration function that run on each icon. I didn't go full property-based testing like I did on elm-knobs, since I'm only basically just checking that each function did modify the SVG in the place it's supposed to.

I also used a great elm-review rule: lue-bird/elm-review-documentation-code-snippet. What I use it for is a basic sanity check of all code snippets in the docs. If you take a look at my package docs, you'll see that all example code ends with a comment like: --: SimpleIcons.Icon. This instructs the elm-review rule to check that the preceding bit of code resolves to the stated type. And while checking the type is cool, I'm already happy enough that it will attempt to compile the code at all, as that would be the first likely problem to occur if the API changed and the examples were to get outdated.

One little trick I learned from Dillon Kearn's Idiomatic Elm Package Guide, and which I put into practice in this package, is that I can use elm make --docs=file.json to confirm that the package documentation satisfies the Elm package repository requirements early. What it does is attempt to generate a JSON file that contains all the package documentation, but it will fail if there's missing docs for exported members, if something's incorrectly formatted, etc. So that line is one of the commands that my check task runs, in addition to attempting compilation, running tests, and running elm-review.

This was the second Elm package I release. I think I'm getting the hang of it. Hopefully it'll be helpful to someone other than me, eventually!

dot-into, pipes in TypeScript

agj — Sun, 05 Apr 2026 15:54:46 +0000

So I have a little library for JavaScript and TypeScript called dot-into, which is something I actually every so often use in personal projects I've written using said languages. I've posted about it before back when I launched it, and I've updated it a few times. Here's the short of it:

// This:
third(second(first(data)), moreData);

// Becomes this:
first(data).into(second).into(third, moreData);

I just released version 3.0.0, which breaks ES5 compatibility but fixes some outstanding type inference problems that have existed since I introduced TypeScript support. Basically, it should now work with functions that use generic types. However, it's still broken for functions with multiple type signatures, sadly. But it's an easy fix:

// This breaks inference:
data.into(multiSignatureFn);

// This doesn't:
data.into((value) => multiSignatureFn(value));

I guess I wanted to post about it again because the biggest problem that it had, in my eyes, was that any null or undefined value in the middle of a pipe would cause a runtime exception. This is because the library extends the Object prototype, which those two values don't inherit from, and so the execution throws due to a non-existing object member. But more recently (in this decade or so since it was originally released) there's been two developments that mitigate this issue and make the library more useful:

There's new JavaScript syntax, the ?. optional chaining operator, which precisely short-circuits the chain of invocations and returns undefined instead of throwing.
The rise of TypeScript means that (if set up correctly) we can opt into getting compilation errors when trying to access a member of a possibly nullish value.

I honestly do not love working with JS or even TS, but when I do, I like having something akin to a |> pipe operator available, common in functional programming such as the ML family of languages and Elixir. I'd much rather use a library of nice, functional utility functions that can operate on various forms of plain data (such as the TS-native Remeda) than dealing with objects with state and members and so on.

Traduje “la guía” de Elm al español

agj — Sun, 15 Feb 2026 00:52:57 +0000

Escribí una traducción al español de “Introducción a Elm”. Es un libro digital escrito por el mismo autor del lenguaje de programación Elm, Evan Czaplicki, como una forma accesible de aprender a programar usando el lenguaje. No sólo demuestra y explica el lenguaje mismo, sino que también presenta perspectivas y técnicas que yo considero muy valiosas, en un formato extremadamente accesible. Es una excelente manera de aprender programación funcional. Elm es un lenguaje y una comunidad de donde yo he aprendido muchísimo, y creo que el libro condensa una gran parte de ese valor. Con algo de suerte, esta traducción contribuirá un poquito a popularizar Elm y estas ideas dentro de los círculos hispanohablantes de programación.

Viendo el historial de Git, este proyecto de traducción lo empecé en agosto de 2024, o sea más o menos hace un año y medio. Obviamente no estuve constantemente trabajando en ello, sino que ocasionalmente me metía a trabajar en unas cuantas páginas, luego me ocupaba en otras cosas.

Una razón por la que quise traducir este libro es porque tenía ganas de practicar hacer una traducción técnica. Durante la última década y tanto he ocasionalmente hecho traducciones en forma remunerada, y he ido aprendiendo por mi cuenta sobre la disciplina. No me considero realmente un profesional, aunque sí es algo que me gusta hacer ocasionalmente, y no me considero malo haciéndolo. Definitivamente me falta teoría, eso sí.

Al traducir intenté ser muy preciso con lo técnico y consistente con los términos usados, pero también fui bastante libre en reformular la prosa de Evan para conservar ese tono cálido y transparente, que se traduce a un estilo bastante distinto en español. Por ejemplo, decidí usar consistentemente la primera persona plural (“hacemos”), versus una mezcla de segunda singular y primera plural (“you do”/“we do”) que usa el original. Así encuentro que suena menos acusatorio o demandante en español, un poquito más suave.

Hice el esfuerzo de usar lenguaje neutro al género, algo difícil de lograr totalmente en español, donde históricamente el género masculino se toma como “neutro”. El inglés no tiene este mismo problema, ya que en muy pocos casos se necesita ser explícito con el género, pero el texto original del libro sí tiene un enfoque inclusivo que definitivamente quise conservar. Encuentro particularmente importante evitar profundizar este sesgo en una industria tan masculinizada como la del software.

En el repositorio mismo anoté estas y algunas otras directrices que definí para orientar la traducción.

Me tomé la libertad de actualizar vínculos y referencias a recursos perdidos o desactualizados, también de reemplazar vínculos a contenido externo en inglés por una versión en español cuando hacía sentido. En muchos casos no existía esa alternativa, por lo que sería ideal eventualmente, por ejemplo, subtitular los videos usando Amara, pero es una cantidad no trivial de trabajo extra. También estoy considerando traducir los artículos escritos por el mismo Evan, que vincula desde el libro, y dejarlos como apéndices. También faltan los diagramas y bastante código de ejemplo (los comentarios en particular) que aún están tal cual en inglés, lamentablemente.

Pero además de estos puntos, todavía permanece una otra gran limitación, y es que el libro hace uso de un REPL incrustado en varias páginas. El texto te invita a probar expresiones simples de código Elm y ver cómo se resuelven. Actualmente ese REPL no funciona en la traducción, porque depende de un servicio externo que Evan alberga en su servidor. Lo bueno es que ya hablé con él, y le propuse un PR que añade el dominio usado por esta traducción a la lista blanca que tiene el servicio del REPL. Evan me dijo que lo va a actualizar tan pronto se desocupe un poco, pero se nota que está bastante limitado de tiempo, así que seguramente pasará un rato antes de que lo haga.

Hablando de servidores y eso, la traducción la alojé en Github Pages porque es gratis, y así me ahorro un costo monetario que puede no ser grande, pero podría convertirse eventualmente en una razón para dejarla morir, si es que por alguna razón pierdo interés personal en mantenerla. Obviamente no tengo ninguna intención similar, pero tampoco sé en qué voy a estar dentro de unos cuantos años. Es algo que ya he visto ocurrir con sitios web relacionados con Elm, mantenidos presuntamente por gente que se alejó de la comunidad. Pero tal vez cambie de opinión si encuentro una buena solución.

Cielos, y un jam con Gleam

agj — Wed, 21 Jan 2026 02:39:25 +0000

Participé en un game jam, o sea un evento grupal donde cada quien hace un videojuego durante un periodo de tiempo específico. Es el primer jam de juegos en torno al lenguaje de programación Gleam, un lenguaje joven que recién el 2024 llegó a su versión 1.0 y empezó a ganar tracción.

Aquí puedes jugar Cielos, y aquí está el código fuente.

Cielos

El juego que hice (a medias) se llama “Cielos”. El tema para el evento fue “Lucy in the sky with diamonds”. Lucy es el nombre de la mascota de Gleam, una estrellita rosada. Cada quién interpretó el tema a su manera, algunos haciendo mención directa a dicha mascota y a otros elementos de la cultura del lenguaje, otros al nombre Lucy, otros metieron diamantes por ahí.

Yo partí con la idea ambigua de hacer algo tipo Jeff Minter, apropiado al “LSD” de la temática. Al final me quedé con la parte del “cielo”, y decidí hacer algo en un 3D no poligonal tipo Super Scaler o Modo 7. Me interesó finalmente el aspecto técnico de desarrollar este motorcito de visualización, y es en lo que más se me fue el tiempo durante ese espacio de nueve días. La estética de la tecnología de esos juegos de los arcades de Sega o de Super Nintendo la encuentro súper evocadora, y ocasionalmente me dan ganas de experimentar por ahí, como en Cave Trip y (más o menos) en Viewpoints.

No me dio tiempo para permitir movilidad en las tres dimensiones (estaba pensando en algo un poco tipo el all-range mode de Star Fox), pero traté que el movimiento se sienta placentero de controlar. Tuve que usar una estrategia totalmente diferente para el teclado y las pantallas táctiles. Para tacto usé rotación tipo “scroll”, que hoy no me convence del todo, se hace un poco engorroso de controlar.

Dadas las limitaciones de la librería gráfica que usé (paint), creé una tipografía muy simple usando líneas rectas en una grilla de 12×12, con los caracteres definidos directamente en el código. Por supuesto, sólo dibujé los caracteres que necesitaba para el juego.

Fui iterando y mucho se me quedó pendiente, pero en definitiva, hice algo que podría ser la base para un futuro juego más ambicioso. Quién sabe.

Y qué tal ese Gleam

Gleam es un lenguaje que empecé a aprender recién ahora en noviembre, pero la verdad es que el proceso fue súper fluído. Me fui directo al carril de aprendizaje en Exercism (aquí mis resultados) y avancé sin ningún problema. Hoy día, después de este jam y de un par de semanas de experimentar usando la librería Lustre para desarrollar frontend, me siento bien cómodo programando con él. Gleam puede compilar a dos objetivos: BEAM (que lo pone en compañía con Erlang y Elixir) y JavaScript. Yo solamente conozco su lado JavaScript por ahora, hasta que me toque programar algún backend o algo por el estilo.

Es un lenguaje que parece heredar de OCaml, Elixir, Elm y Rust. Yo tengo bastante experiencia con Elm, un poquito con OCaml, y sólo he hecho algunos ejercicios con Rust y Elixir. Pero aunque no tuviera esa experiencia, Gleam sigue siendo un lenguaje súper simple, diseñado para ser fácil de aprender.

Voy a enumerar algunas cosas que me gustan de Gleam.

Primero lo más obvio, tiene un sistema de tipos muy simple pero muy sólido, con tipos de datos algebraicos (ADTs) e inferencia de tipado a la Hindley-Milner, heredados de la familia de lenguajes ML. El sistema de tipos se parece bastante al de Elm, pero más simple aún, donde los tipos de registro son tipos de suma con una sola variante.

type MiRegistro {
  MiRegistro(un_campo: Int, otro_campo: String)
  // Aquí pueden ir otras variantes, y esto sería un tipo de suma.
}

Gleam tiene tan pocos conceptos que aprender que ni siquiera tiene “if/then/else”. Pero sí tiene un muy poderoso “pattern matching”, o búsqueda de patrones, que se puede usar con el mismo efecto:

case mi_condicion {
  True -> cuando_si()
  False -> cuando_no()
}

Está muy pulida la experiencia de desarrollo. El CLI gleam es una herramienta todo en uno: inicializa tu proyecto, compila, formatea y tiene servidor de lenguaje para tu editor. El formato además sigue la filosofía de go fmt y de elm-format, o sea que nos evitamos tener que configurarlo, porque permite un sólo formato transversal y estándar.

Como último punto positivo no puedo dejar de mencionar su comunidad. Lamentablemente la mayoría de comunidades de software se concentra en lo técnico, en desmedro de lo humano. En el caso de Gleam, la comunidad es mucho más explícitamente inclusiva de lo que he visto hasta ahora, lo cual también implica ser excluyente a las voces intolerantes. Esta es una cita directa de su web:

Black lives matter. Trans rights are human rights. No nazi bullsh*t.

Y bueno, Gleam definitivamente tiene mucho que me gusta, pero también tiene aspectos que me desilusionan. Esos aspectos que carece son justamente las cosas que me gustan de Elm, y que busco y espero en nuevos lenguajes funcionales, en lo posible.

Gleam no es un lenguaje puro. Cualquier función puede causar efectos, como hacer una llamada remota o yo qué sé. Me encantaría que tuviera gestión de efectos, y la librería Lustre al menos ofrece esa capacidad, pero no hay verificación a nivel del lenguaje. Además, la manera en que funciona su interfaz foránea con Erlang o JavaScript, que es arbitraria y sin chequeo de tipos, implica que el tipado no es sólido.

Estos puntos en contra son una real lástima, pero tomo lo bueno, y adopté Gleam como un lenguaje que toma mucho de lo que me gusta de Elm y lo hace un poco más versátil, pudiendo usarse en el backend sin problemas, por ejemplo. Su desarrollo es más sano y vigoroso, también, lo cual lo hace más fácil de promover con los pares y en el contexto laboral. Seguiré programando Gleam, seguro.

Experimentando con Elm en mi trabajo

agj — Sun, 31 Aug 2025 02:56:20 +0000

Llevo trabajando cuatro años como desarrollador full-stack en una empresa cuyo producto es un “SaaS”, o sea, básicamente una aplicación web. La empresa ha sufrido varios cambios internos de estrategia, y eso ha impactado al lado técnico también. En una de esas ocasiones se vio posible el reconsiderar varios aspectos técnicos que llevábamos en el front-end, y quise probar suerte proponiendo mi tecnología preferida para este ámbito: Elm.

Para bien o para mal, los planes fueron otros, y hoy día Elm no se usa en la empresa en ninguna capacidad. Igual, quiero compartir un poco mi experiencia construyendo esta propuesta de integrar Elm en un sistema preexistente. Lo que sigue está escrito bajo la suposición de que tienes cierto conocimiento del lenguaje y algo de experiencia trabajando el front-end.

El proyecto partió después de una conversación con el “ingeniero principal” de la empresa, quien me propuso que haga la prueba migrando algún trozo pequeño de la aplicación como prueba de concepto. Quedamos en que tomaría una página interna: el explorador de usuarios. Esta página la usan el equipo de soporte y el área comercial para revisar y corregir problemas en los datos de nuestros usuarios, aunque aparentemente no se usa muy frecuentemente. La página merecía ser mejorada porque funcionaba muy lento, y siendo una página de uso exclusivo interno, el riesgo de intervenirla era bajo.

Como parte de este experimento, también estuve algunos días haciendo “pair programming” con dos colegas, para que conozcan Elm y puedan hacerse una opinión que compartirían con el resto del equipo, aunque a ellos los integré una vez que ya estaba todo mayormente armado. (Un error de cálculo fue que estos dos colegas se fueron de la empresa poco tiempo después, obviamente por razones sin relación con este proyecto). El resto lo hice durante semanas de “cooldown” entre proyectos, y también algunos fines de semana.

Integración con Webpack

Ese entorno “legacy” sobre el que trabajaría es un monolito hecho en PHP, con Vue en algunos lados, y el JS empaquetado usando Webpack. Por eso, la verdad fue bastante fácil integrar Elm usando un plugin de nombre elm-webpack-loader. Sólo tuve que crear un punto de entrada main.js, donde instancio la aplicación Elm con sus flags y puertos, y agregarlo en el archivo de configuración de Webpack como entry. Lo demás consiste en poner en la página la etiqueta <script> que carga el .js generado, y otra etiqueta con un ID específico que luego le pasaremos a Elm para que la use.

Como se ve abajo es como estructuré los archivos, finalmente. Nótese que permite tener múltiples miniaplicaciones Elm, cada una definida en un directorio elm/Entrypoint/*, que incluye su propio punto de entrada y rutas.

elm/
  Api/            Comandos de llamada a la API.
  Data/           Tipos de datos.
  Entrypoint/
    */            Cada punto de entrada tiene un submódulo.
      Route/
        *.elm     Rutas, cada una un “mini TEA”.
      Main.elm    Un punto de entrada en Elm.
      Route.elm   Tipo que define la ruta actual.
      main.js     Punto de entrada para Webpack. Instancia `Main`.
  Util/           Utilidades varias.
  View/           “Componentes”.
  Layout.elm      Constantes de la vista, como colores y tamaños.
  Ports.elm       Puertos, lado Elm.
  Run.elm         Envoltorio sobre `Browser.element`.
  ports.js        Puertos, lado JS.

El archivo elm.json queda en la raíz del proyecto, con el directorio elm/ configurado en source-directories. Cada elm/Entrypoint/*/main.js es vinculado en la configuración de Webpack. Este archivo se encarga de inicializar su Main.elm respectivo, pasándole flags, y configura los puertos usando una función exportada desde elm/ports.js.

Puertos para enrutar

Mencioné la reconstrucción de una página (la de usuarios), pero este módulo en realidad comprende dos páginas: el listado de usuarios, y la página de visualización y edición de un usuario individual. Por eso hacía falta tener alguna solución para el manejo de rutas, o sea que funcione como una “single-page application”, si bien para sólo dos rutas.

Normalmente, si uno hace una aplicación Elm independiente, uno usa Browser.application (doc.), que permite definir las funciones onUrlRequest y onUrlChange para reaccionar ante clicks en links y cambios en la ruta. Lamentablemente, en este contexto no es posible, ya que Browser.application se apodera de la página completa. En este caso tenemos una aplicación Elm incrustada dentro de una aplicación más grande, con menús alrededor que funcionan de forma independiente, así que fue necesario solucionarlo de otra forma.

Lo que hice fue usar Browser.element (doc.), que sólo toma poder de un elemento dentro de la página, y para manejar los cambios de ruta usé puertos. Desde el lado de JS escuché el evento "popstate" (MDN) emitido desde window para registrar cambios en la ruta y gatillar el puerto correspondiente, y escuché un puerto de Elm para cambiar la ruta usando window.history.pushState (MDN). Esto sirve para cambiar parámetros de búsqueda en la URL tipo ?param=value, también.

Usé sólo dos puertos, uno de entrada y otro de salida, ambos cuales transmiten un tipo así:

type alias JsMsg =
    { kind : String
    , value : Value
    }

Este es un patrón usualmente recomendado en la comunidad Elm, aunque hay distintas maneras de implementarlo. También usamos decodificadores JSON para manejar los valores recibidos en forma estricta.

Manejo centralizado de rutas

Para simplificar la manera en que se construye una miniaplicación Elm, creé una abstracción: Envolví el uso de Browser.element en una función que llamé Run.elementWithFlagsAndRoute, con la siguiente firma.

elementWithFlagsAndRoute :
    { init : route -> flags -> ( model, Cmd msg )
    , flagsDecoder : Decoder flags
    , routeDecoder : AppUrl -> Maybe route
    , view : model -> Html msg
    , update : msg -> model -> ( model, Cmd msg )
    , subscriptions : model -> Sub msg
    , routeChanged : route -> model -> ( model, Cmd msg )
    }
    -> Program Value (InitModel (RouteModel route model)) (RouteMsg msg)

Esta función centraliza la decodificación de “flags” y, por supuesto, se hace cargo de los detalles del manejo de puertos para el enrutamiento. Esta estrategia está un poco inspirada en un artículo por Ju Liu de NoRedInk, y en otro blog de por ahí cuyo link no logré desenterrar, que también habla de esto mismo.

Internamente, esta función administra los puertos mencionados más arriba para saber cuándo hay un cambio en la URL. routeDecoder : AppUrl -> Maybe route es la manera en que determinamos cuál es la nueva ruta (aquí usé lydell/elm-app-url para esto). Si esta función retorna Nothing esto significa que navegamos hacia algo externo, entonces la navegación se defiere al navegador, y gatillamos la carga de otro recurso.

La función routeChanged : route -> model -> ( model, Cmd msg ) que mencioné arriba es parecida a update, pero dedicada a manejar cambios de ruta. En este primer acercamiento quedó una solución relativamente manual para manejar rutas, pero en todo caso, la idea es que esta función se responsabiliza de almacenar la ruta actual en el modelo y de inicializar el modelo de la ruta actual, potencialmente llamando comandos que la ruta necesita al inicializarse.

Arquitectura Elm anidada

Existe un módulo Entrypoint.*.Main para cada miniaplicación, que se encarga de manejar el estado global y de orquestrar los cambios de ruta. Opté por usar una arquitectura Elm anidada, de modo que este módulo es el encargado de delegar al init, update y view de cada ruta, que está definida en cada módulo Entrypoint.*.Route.*.

De hacerlo de nuevo, seguramente separaría entre un modelo global, compartido entre rutas, y otro modelo específico para cada ruta. Lo que hice, sin embargo, fue usar un sólo modelo central para cada miniaplicación, y en cada ruta usé “registros extensibles” para definir un subconjunto de llaves del mismo modelo. Por ejemplo, para el listado de usuarios dentro del módulo Entrypoint.Usuarios.Route.List:

type alias Model a =
    { a
        | usuarios : RemoteData Http.Error Usuarios
        , apiConfig : Api.Http.Config
    }

Estas llaves usuarios y apiConfig están definidas también en el Model central. El módulo Main le pasa el modelo completo al update de esta ruta, pero gracias a que definimos su “submodelo” como un registro extensible, la ruta sólo ve lo que le interesa dentro de él. El problema de esta estrategia es que hay que tener cuidado en qué datos deben limpiarse al cambiar de ruta y cuáles no, y también implica repetir las mismas llaves en el Model central y el de la ruta.

Por ejemplo, si tenemos un tipo Route así:

type Route
    = List RouteListQuery.Query
    | Detail String

Podemos actualizar el modelo así en Main, mapeando duplas de ruta + mensaje:

type Msg
    = RouteListMsg Entrypoint.Usuarios.Route.List.Msg
    | RouteDetailMsg Entrypoint.Usuarios.Route.Detail.Msg


update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case ( model.route, msg ) of
        ( Route.List query, RouteListMsg routeMsg ) ->
            let
                ( newModel, cmd ) =
                    Entrypoint.Usuarios.Route.List.update routeMsg model query
            in
            ( newModel
            , Cmd.map RouteListMsg cmd
            )

        ( Route.Detail _, RouteDetailMsg routeMsg ) ->
            let
                ( newModel, cmd ) =
                    Entrypoint.Usuarios.Route.Detail.update routeMsg model
            in
            ( newModel
            , Cmd.map RouteDetailMsg cmd
            )

        _ ->
            ( model, Cmd.none )

Este tipo de repetición por el uso de “pattern matching” para cada ruta se replica en otras funciones del módulo Main, como init y view. Hay maneras de hacer esto un poco menos repetitivo, pero en general es lo que pasa cuando uno empieza a anidar arquitecturas Elm, y la razón por la que no se suele recomendar.

Eso por ahora. Tal vez en otro artículo escribiré sobre la vista, o sea la estrategia que usé para crear “componentes” y su documentación usando ElmBook.

On my elm-knobs Elm package

agj — Tue, 26 Aug 2025 04:03:34 +0000

Two years ago I made a simple Elm package to scratch my own itch, named agj/elm-knobs. I wanted a simple interface to tweak constants dynamically in order to see how they affect a visual algorithm (which was just a project I was working on for fun; I'll post about it if I actually get around to finishing it). I found a few packages that get close to what I wanted, but nothing matching precisely my needs, so I just coded the thing and eventually turned it into a simple package.

The intended use-case for the package is squarely prototyping, so I didn't put effort into making it look nice or visually versatile. What I did though is add “knobs” (interactive controls) for primitive types (Int, Float, String, Bool) and a few non-primitives.

The way it works is through a Knob a type value, where a could be any type at all, as long as you have the means to create it. This knob value contains the current value of a and a view function that returns HTML and emits updates to itself as an event whenever the controls get manipulated. Below is a quick rundown on how to use a knob.

knob : Knob Int
knob =
    Knob.int { step = 1, initial = 0 }

knobValue : Int
knobValue =
    Knob.value knob

type Msg =
    KnobUpdated (Knob Int)

knobView : Html Msg
knobView =
    Knob.view [] KnobUpdated knob

Please note that this example code and the rest of this post are actually based on unreleased v2 code. I guess I'll have to release that version soon, though.

And then there's ways to compose, transform and create custom knobs. You can also serialize and deserialize a knob into a string, in order to persist its value using the Web Storage API or however else you like. Some omissions I can think of are knobs for dates, and for data structures such as lists and dictionaries.

In the remainder of this blog post I'll describe a couple of ways in which I “over-developed” this package, beyond its content proper.

Interactive documentation

This was my first Elm package, and I put a lot of effort into the documentation, taking it as a chance to learn and just make it as useful as possible. Elm core package documentation is way above average, so I took a lot of inspiration from it. I think that the package docs I wrote are pretty clear and organized, meant to almost work as a tutorial.

One way I tried to improve the documentation was by creating “interactive documentation” using ElmBook. It's comprised of code examples for each of the knob functions, whose resulting HTML you can see live in your browser. It's interactive in the sense that the example code shows up as interactive HTML, not in that you can tweak the code yourself, though.

One of the interesting things I did there was making sure that the example code matches what you see exactly, and that I don't have to forget to copy & paste something. Elm has no metaprogramming capabilities, so using an external tool to do this was necessary—here comes Comby to the rescue! (Think sed, but for manipulating code syntax instead of plain text.)

Take a look at the Elm code below, describing an example for Knob.float. Using a very short script I wrote using Comby, the string value in the code field gets filled with what's in the init_ field automatically. Having these two synchronized makes sure that example code is always valid, since otherwise the interactive docs would not compile either.

floatDoc : KnobDoc Float Model
floatDoc =
    { name = "float"
    , link = Nothing
    , description = Nothing
    , init_ =
        Knob.float { step = 0.01, initial = 0 }
    , code =
        """
        Knob.float { step = 0.01, initial = 0 }
        """
    , get = \model -> model.float
    , set = \model new -> { model | float = new }
    , toString = String.fromFloat
    }

Another thing you might notice from the code block above is that I used some tricks to make writing the documentation more DRY (i.e. more consistent, less error-prone). With ElmBook you write markdown to define the content of each page. I generate this markdown from records like the one you see above. Here's the module I wrote for that purpose, although it might be a bit hard to follow, especially given that it's written to accomodate the ElmBook API. But at any rate, something like the above turns into what you see here.

I'm not happy with having to split the “API docs” and the “interactive docs”, so at some point I might figure out a way of automatically parsing the Elm comment docs and inserting that content into the interactive documentation, to keep it all in one place. Sounds like a lot of effort for such a relatively useless package, so if I ever end up going through the trouble, it'll be for the learning opportunity (or perhaps my OCD.)

Property-based tests

I test all knobs using property-based tests (which in elm-test are called “fuzzers”, although that is the wrong term). The idea is that instead of each test checking for one or a few input values one by one against an expected result, we automatically generate a whole range of inputs, so we can make sure that our function behaves the way we expect given any possible input in the range. This technique receives this name because we can't use the same strategy for standard unit tests and just check one input against one result; we need to instead test that a given property holds.

For instance, I have a suite of serialization tests, of which there's two types:

Something I called “transitive equality”, for lack of a better term: If two knobs correspond to the same value, the result of serializing them should also be equal, and vice-versa.
A classic round-trip test: We serialize and then deserialize, and expect the value of the input knob and of the result to be identical.

Other tests check messages emitted when a user manipulates the controls, the behavior for invalid inputs, and such.

Individualizing versions

Let me give you an example of a problem I frequently run into when using third-party library code. At my day job, we're using Vue and a component library called shadcn-vue. We are using v1, and recently they released v2. As soon as they did, the documentation for v1 disappeared.

I don't like this experience. I want to decide when to upgrade, and as long as I'm using an old version, I want to have access to its documentation. Two libraries in the JavaScript space that do great in this respect are Ramda and date-fns. Elm packages automatically keep docs available for every version, so this is much less of a problem in our ecosystem. However, if I point a link at a latest URL, I'm effectively making my documentation expire.

So, all of the links to places in the documentation, including the package docs and the interactive docs, are versioned. And in order to make sure I don't forget to update any version string whenever I release a new version, I've implemented checks across the repo. For links in the readme, the Docs.UpToDateReadmeLinks elm-review rule works great. For other cases, I wrote a Nushell script that even checks the git tag and the changelog.

Interactive docs for older versions are also kept available in Github Pages and in compiled form in the repo.

Cómo uso Nix, Nushell y Just para configurar mis proyectos de código

agj — Tue, 12 Aug 2025 00:08:08 +0000

Desde hace un tiempo que en cualquier proyecto personal de código que empiezo, termino usando tres tecnologías: Nix, Nushell y Just. En este artículo quiero presentar estas tres herramientas, y compartir la forma en que las uso para configurar las dependencias del proyecto, escribir scripts, y definir sus tareas de desarrollo. Asumo que entiendes cómo usar tu terminal, que trabajas en un entorno tipo Unix, y que sabes programar.

Vamos a partir viendo el manejo de dependencias usando Nix.

Nix para declarar dependencias

Nix es un ecosistema enorme y muy versátil, pero en este contexto lo que nos interesa es que podemos usar esta herramienta para declarar todas las utilidades necesarias para correr un proyecto, compilarlo, hacer linting, etc., y sin usar contenedores. Es compatible con casi cualquier entorno tipo Unix, o sea Linux, macOS y Windows bajo WSL.

En particular, lo que uso es algo llamado “flake”. Este es un archivo de nombre flake.nix que se pone en la raíz del proyecto, y es donde declaramos los paquetes que necesita.

Partamos con un ejemplo simple:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
  };

  outputs = {nixpkgs, ...}: let
    pkgs = import nixpkgs {system = "aarch64-darwin";};
  in {
    devShell."aarch64-darwin" = pkgs.mkShell {
      buildInputs = [
        pkgs.elmPackages.elm
        pkgs.elmPackages.elm-format
        pkgs.elmPackages.elm-test
        pkgs.just
        pkgs.nushell
      ];
    };
  };
}

Con esto, hemos definido un entorno que contiene algunas herramientas para un proyecto Elm, además de los binarios de Nushell y Just, a los que me voy a referir más abajo. Así como está, esto sólo va a funcionar en un Mac de los con procesador Apple Silicon. Después vamos a desarrollar este ejemplo para entenderlo mejor y hacerlo más versátil, pero por ahora partamos viendo en qué nos ayuda tener este archivo.

Si corremos el comando nix develop vamos a entrar a un shell Bash que contiene todas las herramientas declaradas en nuestro flake.nix. Para salir basta con correr el comando exit, y veremos que ya no tenemos disponibles las herramientas—son totalmente locales al proyecto.

$ nix develop
$ which elm
/nix/store/6hx8g6k7ihgaqvy1i0ydiy7v13s04pf4-elm-0.19.1/bin/elm

$ exit
exit

$ which elm
elm not found

La primera vez se generará un archivo flake.lock, el cual podemos integrar en Git (o tu VCS preferido) para mantener la versión exacta de estas dependencias. Luego se descargarán algunos binarios en caché o se compilarán las dependencias desde su código fuente. Pero eso ocurrirá sólo la primera vez, o cuando quieras cambiar las dependencias, ya que se almacenará todo en el “store” global de Nix.

Un poco más en profundidad

Puedes saltarte esta sección si no te interesa. Aquí voy a explicar un poquito cómo hacer funcionar el ejemplo de arriba para ti, ya que no quise complejizar con ciertos detalles.

Primero, hace falta especificar que esta funcionalidad llamada “flakes” es, al momento en que escribo esto, considerada experimental, y por lo tanto no está activada por defecto: hay que configurarla.

Si no tienes Nix instalado aún, te recomiendo usar el instalador experimental. Es mejor que el “normal” en varios aspectos, entre ellos, funciona mejor en macOS, y también incluye una forma fácil de desinstalar. Corre el script de abajo en tu terminal para instalarlo (o copia el script de la dirección vinculada arriba).

curl -sSfL https://artifacts.nixos.org/nix-installer | sh -s -- install --enable-flakes

Nótese que le pasamos la opción --enable-flakes para inmediatamente dejar activa esta funcionalidad.

Editado 2026-04-11: Quité la recomendación de instalar usando el “Determinate Nix Installer”, ya que perdió soporte para instalar Nix original, ya sólo sirve para instalar su fork, el cual no recomiendo. 👎

Si por otro lado ya tienes instalado Nix y no te funcionan los flakes, necesitas añadir un poco de configuración. Abre o crea un archivo ~/.config/nix/nix.conf y ponle esto:

experimental-features = flakes nix-command

Ya con todo configurado correctamente, te pongo una versión ajustada del archivo flake.nix:

{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = {
    nixpkgs,
    flake-utils,
    ...
  }:
    flake-utils.lib.eachDefaultSystem (
      system: let
        pkgs = import nixpkgs {system = system;};
      in {
        devShell = pkgs.mkShell {
          buildInputs = [
            pkgs.elmPackages.elm
            pkgs.elmPackages.elm-format
            pkgs.elmPackages.elm-test
            pkgs.just
            pkgs.nushell
          ];
        };
      }
    );
}

Lo que hicimos fue declarar una nueva entrada bajo inputs, de nombre flake-utils, y más abajo usar la función eachDefaultSystem que provee, la que nos ayuda a configurar un shell de desarrollo para múltiples entornos simultáneamente. Lo demás está igual.

Para agregar otros paquetes, los encuentras en la búsqueda de Nixpkgs. Una vez que encuentres el nombre de lo que quieres, lo puedes agregar en la lista en tu flake.

Y esto es todo lo esencial que necesitas saber para empezar, aunque por supuesto, hay muchos detalles que podrás ir descubriendo por tu cuenta. Como dije al principio, Nix es un mundo muy grande por explorar. Y de hecho, si Nix te parece muy complejo, existen herramientas que funcionan con Nix por debajo, pero proveen una interfaz más intuitiva para este caso de uso; te recomiendo que le eches una mirada a Devbox, Flox y Devenv.

Nushell para escribir scripts

Nushell es una alternativa a Bash o zsh. La diferencia es que en vez de seguir los lineamientos POSIX e interactuar sólo con texto plano, trabajamos con datos estructurados. Básicamente, es un shell y lenguaje que reemplaza la necesidad de Bash, grep, sed, awk, jq, curl y muchas otras utilidades de línea de comandos frecuentemente usadas para procesar datos.

Igual se ajusta hasta cierto punto a nuestras expectativas como usuarios de Bash y similares. Por ejemplo, en un shell Nushell el comando ls funciona como es de esperarse:

$ ls
╭───┬────────────┬──────┬───────┬─────────────╮
│ # │    name    │ type │ size  │  modified   │
├───┼────────────┼──────┼───────┼─────────────┤
│ 0 │ flake.lock │ file │ 569 B │ 8 hours ago │
│ 1 │ flake.nix  │ file │ 405 B │ 7 hours ago │
╰───┴────────────┴──────┴───────┴─────────────╯

Pero esta salida no es puramente texto. En realidad lo que hemos obtenido es una tabla con filas y columnas. Mira el tipo de cosas que podemos hacer con sólo Nushell:

$ ls | where name =~ '[.]lock$' | get 0.name | open
::: | from json | get nodes.nixpkgs.locked.lastModified
::: | $in * 1_000_000_000 | into datetime
Tue, 5 Aug 2025 11:35:34 +0000 (2 days ago)

Obviamente este ejemplo es puramente demostrativo, pero fíjate: estamos listando archivos, filtrando en base a un regex, sacando el nombre del primero en la lista, leyendo el contenido del archivo, interpretándolo como JSON, recuperando un valor numérico dentro del JSON, multiplicando para convertir segundos a nanosegundos, y finalmente convirtiendo eso a una fecha.

Es tan práctico que lo tengo como mi shell por defecto. Pero para el caso de este artículo, lo relevante es su utilidad para escribir scripts simples y legibles que transforman archivos, levantan servicios, recuperan datos de internet, y más. Los archivos llevan la extensión .nu.

Veamos un pequeño ejemplo. Este es un script que actualiza una lista de exclusiones para evitar visitas de robots de IA, con datos que descargamos del Github del proyecto ai.robots.txt.

# Algunas constantes.
let aiRobotsTxtBaseUrl = "https://raw.githubusercontent.com/ai-robots-txt/ai.robots.txt/refs/heads/main"
let startMarkerLine = "# Start ai.robots.txt"
let endMarkerLine = "# End ai.robots.txt"

# Una pequeña función para simplificar el código más adelante.
def splitLines [] {
  split row "\n"
}

# Función que procesa los datos para un archivo específico, ya que son
# dos los que queremos actualizar.
def updateFile [$filename] {
  # Leemos el archivo local y lo dejamos en la variable como una lista
  # de líneas.
  let localLines = open $"./public/($filename)" | splitLines
  # Lo mismo para el archivo remoto.
  let updateLines = http get $"($aiRobotsTxtBaseUrl)/($filename)" | splitLines

  # El archivo local tiene líneas que marcan el comienzo y el final
  # del contenido que queremos actualizar, marcados por las constantes
  # de arriba de nombre `$startMarkerLine` y `$endMarkerLine`. En base
  # a ese contenido, cortamos la lista para recuperar el contenido
  # que queremos mantener, el cual viene antes y después dentro del
  # archivo.
  let firstSplit = $localLines | split list $startMarkerLine
  let linesBeforeUpdate = $firstSplit | get 0
  let secondSplit = $firstSplit | get 1 | split list $endMarkerLine
  let linesAfterUpdate = $secondSplit | get 1

  # Insertamos las líneas provenientes del archivo remoto en la mitad,
  # concatenando todo en una misma lista.
  let updatedLines = (
    $linesBeforeUpdate
    ++ [$startMarkerLine]
    ++ $updateLines
    ++ [$endMarkerLine]
    ++ $linesAfterUpdate
  )

  # Sobreescribimos el archivo antiguo con las nuevas líneas.
  $updatedLines | str join "\n" | save --force $"./public/($filename)"
}

# Usamos la función definida arriba para procesar dos archivos.
updateFile ".htaccess"
updateFile "robots.txt"

No sé lo que pienses tú, pero yo creo que queda un código extremadamente legible y conciso. Es fácil de escribir, trae “pilas incluídas” como quien dice, con soporte para procesar muchos formatos de archivo. Y cuando hay algo que no se puede hacer con Nushell, puedes echar mano a cualquier herramienta de línea de comandos, idéntico a como haríamos en un script de Bash.

El lenguaje Nushell toma las “pipes” (|) de los shell Unix y las combina con estructuras de datos inmutables. Es un lenguaje bastante funcional, de tipado dinámico pero estricto, o sea que si una función recibe un valor con un tipo inesperado, la ejecución falla con un mensaje bien explícito, como este:

$ ["hola", "cómo", "estás"] | date to-timezone "UTC"
Error: nu::parser::input_type_mismatch

  × Command does not support list<string> input.
   ╭─[entry #6:1:31]
 1 │ ["hola", "cómo", "estás"] | date to-timezone "UTC"
   ·                             ────────┬───────
   ·                                     ╰── command doesn't support list<string> input
   ╰────

Just para definir tareas

Just es una herramienta con un alcance muy moderado: permitir definir tareas repetibles para un proyecto. Lo típico es definir una tarea “build” para compilar el código, o una “dev” para ejecutarlo localmente, o una “test” para correr los tests. La manera en que funcionaría usando Just es con los comandos just build, just dev y just test, cuyas tareas uno mismo define en un archivo de nombre justfile.

Seguro que hasta ahí no hay nada nuevo, es lo mismo que uno haría con Make o con npm run, por ejemplo. Y es verdad, Just no ofrece un paradigma novedoso. Lo único que ofrece es simpleza.

El modelo de Just es Make. No sé tú, pero yo al menos he escrito muchos makefile para definir tareas para un proyecto. El problema con eso es que Make tiene muchas asperezas para este objetivo. Por ejemplo, si defines una tarea test para correr tus tests, y resulta que tienes una carpeta test en el mismo directorio, no se va a correr la tarea. Esto es porque Make está hecho para compilar cosas, donde el nombre de la tarea es el nombre del archivo, y cuando el archivo o directorio ya existe, simplemente no se ejecuta la tarea.

La razón por la que me gusta Just es porque es como un Make pero hecho para correr tareas, con todas sus asperezas pulidas. La sintaxis de un “justfile” es igual a la de un makefile, pero un poquito mejor. Por ejemplo, puedes indentar usando espacios en vez de tabs, y puedes poner comentarios de documentación. Además puedes listar tareas usando just --list.

Te pongo un ejemplo. Este archivo lleva el nombre justfile.

port := "1237"

[private]
default:
  just --list

# Compila archivos.
build: install
  rm -rf dist
  pnpm exec vite build

# Levanta el servidor de desarrollo.
develop: install qr
  pnpm exec vite --port {{port}} --host

[private]
install:
  pnpm install

[private]
qr:
  #!/usr/bin/env nu
  let ip = sys net | where name == "en0" | get 0.ip | where protocol == "ipv4" | get 0.address
  let url = $"http://($ip):{{port}}"
  qrtool encode -t ansi256 $url
  print $url

En la línea 4 definí la primera tarea, a la que le puse nombre default porque es la que se ejecutará por defecto si uno escribe just. Puede ser cualquier tarea, pero a mí me gusta que la primera tarea sirva para ver la lista de tareas disponibles, por eso la hice “escondida” usando el modificador [private]. Mira cómo se ve:

$ just
just --list
Available recipes:
    build   # Compila archivos.
    develop # Levanta el servidor de desarrollo.

Bastante bonito, ¿no? Te puedes dar cuenta de que los comentarios escritos sobre cada tarea sirven como documentación de esa tarea, y que aparecen al usar el comando --list.

Otras aspectos notables:

En la primera línea definí una constante que después uso escribiendo {{port}} en dos lugares.
Hay una tarea install que definí como prerrequisito de dos otras, o sea que cuando, por ejemplo, llame just build, se ejecutarán primero los comandos en install.
La tarea qr comienza con la línea #!/usr/bin/env nu, la cual sirve para definir con qué programa quieres que se ejecuten los comandos de esa tarea. En este caso, escribí un pequeño script de Nushell. Puedes usar Python si quisieras, o Clojure vía Babashka, o cualquier otro lenguaje aquí. Esta funcionalidad es súper útil.

Esa fue mi presentación sobre estas herramientas que uso para configurar mis proyectos. Hay una otra herramienta que no mencioné: direnv, la cual hace que sea mucho más placentero trabajar con entornos Nix. Tal vez otro día escribiré algo al respecto, no sé.

Ojalá que te haya sido útil, y cuéntame si encontraste algo incorrecto o confuso.