It includes some detailed examples, explanations, and exercises. I even created a small command-line tool (ellie-app-cli) to let you instantly open and run the interactive exercises with your favorite editor in your local environment. You can try it out on one of the exercises from the elm-ts-interop course:

npm install -g elm-live elm-json ellie-app && ellie-app fQWYRPSQxvsa1

I'm working on some paid Elm courses, so stay tuned for those. My goal is to produce quality content that explores techniques for making Elm applications more maintainable, as well as some tutorials on Elm libraries that go beyond the basics. I hope this will be a valuable resource for Elm devs looking to dive deeper, and I also hope it can help support my continued work on open source projects like elm-pages, elm-graphql, elm-markdown, and other efforts in my mission to make the Elm ecosystem as vibrant as possible.

If you have any feedback on this course, or anything you'd like to see in future courses, I'd love to hear your thoughts!

Having brilliant code design ideas doesn't necessarily help you manage your codebase better. But building in relentless, tiny habits is likely to bring out some brilliant designs.

I think we can generalize this one essential technique a step further. Habits are indeed very powerful, and greater than the sum of their parts. But a habit is just a special case of an automation.

Instead of thinking of myself as a programmer, I like to frame my job as an automator. Programming is a type of automation. I think you can argue that a habit is a kind of automation as well. It's just that we're automating by training the wiring in our brain instead of automating through code or scripts. Thinking of our role as an automator rather than a programmer can deeply change the way you approach your work.

Who Cares If It's "Programmer" or "Automator"?

It's a subtle distinction. I think the power comes from having clarity on what tasks to prioritize, and how to approach your work. Is manually running a set of deployment steps a good use of time for a Programmer? Perhaps. But it's pretty clear that there is some important work to prioritize improving that manual process when you see yourself as an "Automator."

Embrace that role, and use that framing of the role as a cue to step back and make a small investment to automate a repetitive task.

Identifying Automation Opportunities

Examples of Automation

Automation opportunities can take many forms.

• Organizational/process automation
• Grouping code into functions (a function is really a way of automating machine instructions)
• Automated tests instead of manual testing
• Shortcut keys instead of repetitive menu navigation
• Code generation for tasks like internationalization

Signs of Automation Opportunities

There are some broad patterns to look out for.

• Repetitive steps
• Multiple sources of truth
• Context shifts
• Quality issues (frequent bugs from a process or area of code)
• Steps to add quality after (rather than built-in quality)

Stepping back a level, it's important to build the habit of recognizing these signs and taking a moment to identify and address them. There are many ways to do this, like retrospectives or keeping a running list of things that are slowing you down.

Familiar Elm automation tools

• The Elm type system
• elm-test
• elm-program-test
• elm-review
• elm-graphql (and other codegen)
• elm-format

These examples may seem obvious because we're used to them. But those tools weren't necessarily obvious before somebody saw that automation opportunity and took action. Could you find similar opportunities in your own codebase? And what low-hanging fruit could you automate right now? Any time you can automate quality and correctness instead of verifying it manually, it's a huge win.

Continuous Improvement

Fully baked automation tools are great. But code is a lot easier to iterate on than hardware. So the best automation you can invest in is automating your habit of making small improvements as you see them!

If you notice repeatedly doing an action in your editor, you could take a moment to look up the keyboard shortcut. Or move a set of manual commands into a repeatable script. You can even think of Making Impossible States Impossible as a type of automation, providing guardrails and ensuring that future changes don't run into the same issues. In Toyota culture, this concept of automating quality is called poka yoke, or foolproofing.

Importantly, these small habits and automations are greater than the sum of their parts. If you learn a keyboard shortcut for the rename function refactoring, you're not only saving the time you would have spent renaming manually or accessing the refactoring with the mouse. You are reducing the barrier to that action, which leads to better names in your codebase over time.

Toyota Is Not a Car Manufacturer

Toyota is famous for the saying that they're not a car manufacturing company. They're a car manufacturing improvement company. Their product is not cars, it's their automated, continually improving process for manufacturing cars. Quality cars are the by-product.

In the same way, you can apply Systems Thinking to your code. You improve the results you're getting by improving the process that generates those results. That doesn't mean you ignore the results. It's essential to drive improvements based on concrete opportunities and pain points, not theoretical or anticipated ones. But once you have something concrete, step back and look at the system, and automate it.

Top-Down Vs. Bottom-Up Transformations

In my JavaScript days, I remember a particularly tricky area of code where we had a big list of data in a format defined by the server. We needed to take product listings, pull out specific options and inventory information, normalize them, and then apply filters from the UI to show/hide and sort search results.

There were deeply nested fields, and some incongruities in the shape of the data. Some values were nullable. Some had specific normalization we needed to apply to get data from multiple sources to match.

We had a lot of big unit tests to make sure things were working. Even so, it was so difficult to go in to our series of lodash function calls and find where you needed to make a change. And once you did, you would want to make sure you added several new test cases to make sure you didn't miss a spot or mishandle a special case.

We would sit in awe as the person most familiar with the codebase correctly traversed the nested arrays and objects to get to the exact right place and make a change on the first try. It was a lot to hold in our heads, and it was quite error prone.

The challenge was that using that paradigm to normalize JSON data required thinking of the data as a monolith. We certainly abstracted out functions to help with parts of the normalization. And we used lodash to do functional style mapping over the arrays of data and key-value objects. But mapping over arrays and objects only gets you part of the way there. We still needed to keep a map in our heads of the structure of the data so we could go into a specific area, traverse it, and change it.

We weren't using TypeScript at the time, but even if we had been, the challenge would remain of having to navigate the structure from the top down in order to add a new transformation. Type-safety is a huge help, but it only gets you part of the way there to the benefits of localized reasoning.

What is a Combinator?

The term Combinator is used because you can combine the smaller units to build up the whole. A Combinator is the idea of building something up by combining small "base" values into more complex ones. The values could be a JSON Decoder, a syntax parser, a random number generator. The key is that the simplest form can be composed together to build something complex - but (this is important) the simple thing and the complex thing are the same kind of thing!

Combinators share some parallels with the concept of recursion (defining a function in terms of itself).

fibonacci n =
  if n <= 1 then
    n
  else
    fibonacci ( n - 1 ) + fibonacci ( n - 2 )

This recursive definition can be read as what a fibonacci number is (declarative), instead of how it is calculated (imperative). No mention of how to loop over in each iteration - it's simply written in terms of itself, like a math equation. It's pretty close to how you would teach fibonacci to a human. It just so happens that computers can understand it, too!

Recursion is a good analogy for Combinators:

• A Combinator is declarative (not imperative)
• A Combinator is either defined in terms of other Combinators (analogous to a recursive self-invocation), or it is a "base" combinator (analogous to a recursive base case)

Let's look at an example of a Combinator in Elm. The elm/json package is how you turn untyped JSON data into typed Elm data (or an Err Result value if the structure doesn't match).

personDecoder :
    Decoder
        { name : String
        , birthday : Time.Posix
        }
personDecoder =
    Decode.map2
        (\name birthday ->
            { name = name
            , birthday = birthday
            }
        )
        nameDecoder
        birthdayDecoder

What are nameDecoder and birthdayDecoder? They're both some kind of Decoder. We're combining them. Note that we can think about the Decoders here at a high-level, and drop into the details as needed.

At some point, following our Decoder definitions we will find a Decoder that doesn't just compose Decoders, but directly resolves to a value (similar to our recursive base case).

nameDecoder : Decoder String
nameDecoder =
    Decode.string
        |> Decode.field "full-name"

Decode.string is going to resolve to some value. But we can compose Decoders together in more ways than just combining them or reading JSON values within a JSON property (like "full-name").

Another key technique for a Combinator is that we can transform them.

birthdayDecoder : Decoder Time.Posix
birthdayDecoder =
  Decode.field "birthday-date-time" iso8601DateDecoder

If we follow the definitions, we finally end up with a direct "base" Decoder for birthdayDecoder.

iso8601DateDecoder : Decoder Time.Posix
iso8601DateDecoder =
    Decode.string
        |> Decode.andThen
            (\dateTimeString ->
                case iso8601StringToTime dateTimeString of
                    Ok time ->
                        Decode.succeed time

                    Err error ->
                        Decode.fail error
            )

This time, we are transforming the raw String into an Elm Time.Posix value. iso8601StringToTime is a function that takes a String and gives a Result String Time.Posix. When we transform the "base" Decoder (Decode.string), the type changes with it.

These are some of the basic building blocks of a Combinator. Let's explore how these building blocks lend themselves to breaking down a problem into smaller pieces, without needing to pull in all the surrounding context.

Combinators are trees

With the JS code where I was working with JSON from the server, I was working on the data top-down, and carving out new "seams" to transform data as needed. In contrast, with a Combinator you already have a place to work. You can visualize a Combinator as a tree. You build up a complex Combinator from the bottom up, and you can think locally about any sub-problem (think sub-tree). Each sub-problem is like a little box that you can work in. Once you find the right box, you don't need to worry about what's outside of that box, you can just focus on what's inside the box you're working on. You don't need to create a new point to make your transformation, because it already exists.

For example, if we need to normalize the names we're getting from the server, we just find the right box and work within that.

nameDecoder : Decoder String
nameDecoder =
    Decode.string
        |> Decode.map normalizeName
        |> Decode.field "full-name"

Or if the name may have a different format, we just make that change within our box, blissfully unaware of the JSON structure surrounding our box.

nameDecoder : Decoder String
nameDecoder =
    Decode.oneOf [ Decode.string, firstLastDecoder ]
        |> Decode.map normalizeName
        |> Decode.field "full-name"

firstLastDecoder : Decoder String
firstLastDecoder =
    Decode.map2 (++)
        (Decode.field "first")
        (Decode.field "last")

Joël Quenneville has a nice visualization of this concept in his article Elm's Universal Pattern.

Intermediary Data

Another quality of transforming data in an imperative style is that it can happen in multiple passes. Each iteration to transform the data can yield an intermediary data format that isn't useful except as input to the next transformation phase.

By using a Combinator, you can avoid passing data through various transformation stages. A Combinator represents a set of operations/transformations. You don't actually use the Combinator until you've built it up. If you need to tweak something, you transform the Combinator. So the data is never exposed in your app in an intermediary format.

We are building up both the JSON Decoder and its type information at the same time. Since the types and operations/transformations are in sync, we are guaranteed to either

1. End up with well-typed data (happy path), or
2. End up with a clear error

I really love this quality of the Combinator pattern. This gives you explicit, clearly defined paths, with types fully describing the possibilites. Take a look at Alexis King's article Parse, Don't Validate for some great insights about that.

Combinators Beyond JSON Decoders

This pattern isn't specific to a language, like Elm, or a domain, like JSON.

You can use these same concepts in TypeScript with a library like io-ts. And you can apply this thinking to a lot more problems than JSON. Some examples in the Elm ecosystem:

• elm/random
• elm/parser
• Creating fuzzers (property-based test data) in elm/test
• elm-graphql
• elm-validate

Next Post

Thanks for reading! In the next post, I will share lessons learned about this technique and how it made me realize why I loved one type-safe library I built, and am now rebuilding another to learn these lessons a few years later.

This week I have some improvements to announce for elm-ts-interop. In particular, I've been focused on making it easier to get started with the free Community Edition. And I've also shipped some new APIs for building up your type-safe Encoders and Decoders.

If you're not familiar with elm-ts-interop, it's a tool that generates TypeScript types from your custom JSON Decoders and Encoders to ensure that the types are in sync between your Elm app and TypeScript code. If you're not using TypeScript in your project, you can even benefit from the improved type-safety using vanilla JavaScript by using JSDoc comments ([typescript-without-transpilation]).

You can learn more about how elm-ts-interop works and find some learning resources.

Starter Repo with ViteJS and TypeScript

There is now a starter setup for the elm-ts-interop Community Edition. It uses a simple ViteJS config to load in Elm and TypeScript code, and it also has an eslint rule to enforce exhaustive switch statements so you can add a new FromElm port (Cmd port) and get a type error reminding you to handle that new data in TypeScript. It feels just like adding a new Msg variant and handling it in your Elm update function.

The starter repo is at github.com/dillonkearns/elm-ts-interop-starter. And if you're a pro user, you can see the example Pro setup on the pro branch.

elm-ts-interop Community Edition Setup Guide

You can find the newly published docs which inclue a thorough walkthrough for how to get started with elm-ts-interop. To make it easier to get set up, I've also added an elm-ts-interop init command that will scaffold the two Elm files you need to get started. Try it out and let me know how it goes!

elm-ts-interop Watch Mode

You can run elm-ts-interop with a --watch flag to have it re-run any time your Elm code changes. That helps speed up the feedback loop and get compiler errors as you change your InteropDefinitions module.

Codec and Pipeline APIs

The elm-ts-json Elm package is the secret sauce for getting type information from your Decoders and Encoders. The core API remains the same, but version 2.0 of the package now comes with a Codec API (thank you miniBill for the great API design!) as well as a port of the NoRedInk/elm-json-decode-pipeline API. The Codec API also includes a new addition from miniBill's Codec API for customizing the names of fields (rather than having custom types encoded as an Array of positional values). Check out the new TsJson.Codec API and TsJson.Pipeline API.

Simplified Discriminated Union Decoder

If your using the convention of having a string field that is used to determine the type of decoding to use (Discriminated Unions), there's now a helper that makes it a lot easier to do that with elm-ts-json.

import TsJson.Decode as TsDecode

type User
    = Admin { id : Int }
    | Guest

TsDecode.discriminatedUnion "role"
    [ ( "admin"
        , TsDecode.succeed (\id -> Admin { id = id })
        |> TsDecode.andMap (TsDecode.field "id" TsDecode.int)
        )
    , ( "guest", TsDecode.succeed Guest )
    ]
    |> TsDecode.runExample """{"role": "admin", "id": 123}"""
--> { decoded = Ok (Admin { id = 123 })
--> , tsType = """{ id : number; role : "admin" } | { role : "guest" }"""
--> }

As always, feel free to ask me questions on Twitter @dillontkearns, or on Slack (we have an #elm-ts-interop channel). Happy type-safe coding!

securelySaveSSN : String -> Cmd Msg

reportError : String -> Cmd Msg

You might wrap it in a type wrapper like so:

module SSN exposing (SSN(..))

type SSN = SSN String

securelySaveSSN : SSN -> Cmd Msg

reportError : String -> Cmd Msg

The SSN type wrapper is a good start. But how do you know it won't be unwrapped and passed around somewhere where it could mistakenly be misused?

storeSSN : SSN -> Cmd Msg
storeSSN (SSN rawSsn) =
    genericSendData (ssnPayload rawSsn) saveSsnEndpoint

genericSendData : Json.Encode.Value -> String -> Cmd Msg
genericSendData payload endpoint =
-- generic data sending function
-- if there's an HTTP error, it sends the payload
-- and error to our error reporting service
-- ⚠️ Not good for SSNs!

Whoops, somebody forgot that we had a special securelySaveSSN function that encrypts the SSN and masks the SSN when reporting errors. Do you dare look at the commit history? It could well have been your past self (we've all been there)!

Humans make mistakes, so let's not expect them to be perfect. The core issue here is that the SSN type wrapper has failed to communicate the limits of how we want it to be used. It's merely a convention to use securelySaveSSN instead of calling the generic genericSendData with the raw String. In this article, you'll learn a technique that gets the elm compiler to help guide us towards using data as intended: Exit Gatekeepers.

🔑 Exit Gatekeepers

So how do we make sure we don't log, Tweet, or otherwise misuse the user's SSN? We control the exits.

There are two ways for the raw data to exit. If raw data exits, then we don't have control over it. So we want to close off these two exit routes.

🔓 Unsecure Exit 1 - Public Constructor

If you expose the constructor, then we can pattern match to get the raw SSN. This means that enforcing the rules for how we want to use SSNs leaks out all over our code instead of being in one central place that we can easily maintain.

-- the (..) exposes the constructor
module SSN exposing (SSN(..))

🔓 Unsecure Exit 2 - Public Accessor

Similarly, you can unwrap the raw SSN directly from outside the module if we expose an accessor (also known as getters) which returns the /raw data/. In this case, our primitive representation of the SSN is a String, so we could have an unsecure exit by exposing a toString accessor.

module SSN exposing (SSN, toString)

toString : SSN -> String
toString (SSN rawSsn) = rawSsn

The public accessor function has the same effect as our publicly exposed constructor did, allowing us to accidentally pass the raw data to our genericSendData.

storeSsn : SSN -> Cmd Msg
storeSsn ssn =
    genericSendData (ssnPayload (SSN.toString ssn)) saveSsnEndpoint

The role of a gatekeeper

Think of a Gatekeeper like the Model in Model-View-Controller frameworks. The Model acts as a gatekeeper that ensures the integrity of all persistence in our app. Similarly, our Exit Gatekeeper ensures the integrity of a Domain concept (SSNs in this case) throughout our app.

How to control the exits

To add an Exit Gatekeeper, all we need to do is define every function needed to use SSNs internally within the SSN module. And of course, each of those functions is responsible for using it appropriately. (And on the other side of that coin, that means that the calling code is free of that responsibility!).

Let's make a function to securely send an SSN. We need to guarantee that:

• The SSN is encrypted using the proper key
• It is sent to the correct endpoint
• It is sent with https
• It is masked before being being sent to our error reporting

We don't want to check for all those things everywhere we call this code every time. We want to be able to make sure the code in this module is good whenever it changes, and then completely trust it from the calling code.

module SSN exposing (SSN)

securelySendSsn : Ssn -> Http.Request
securelySendSsn ssn =
    Http.post
    { url = "https://yoursecuresite.com/secure-endpoint"
    , body = encryptedSsnBody ssn,
    , expect = ...
    }

Now we can be confident that the calling code will never mistakenly send SSNs to the wrong endpoint, or forget to encrypt them!

Displaying the SSN

What if you only want to display the last 4 digits of the SSN? How do you make sure that you, your team members, and your future self all remember to do that?

You could vigilantly put that in a code review checklist, or come up with all sorts of creative heuristics to avoid that mistake. I like to reach for the Exit Gatekeeper pattern as my first choice. Then you need to check very carefully any time you are modifying the SSN module itself, and you can trust the module and treat it as a blackbox when you're not modifying it.

It's very likely that you'll miss something if you have to think about where SSNs are used throughout your codebase. But it's quite manageable to keep the entire SSN module in your head and feel confident that you're not forgetting anything important.

Here's a simple implementation of our last 4 digits view:

module SSN exposing (SSN)

lastFourView : SSN -> Html msg
lastFourView ssn =
    Html.text ("xxx-xx-" ++ lastFour ssn)

Takeaways

You can start applying the Exit Gatekeeper pattern to your elm code right away!

Here are some steps you can apply:

1. Notice some data in your codebase that you have to be careful to use safely or correctly
2. Wrap it in a Custom Type (if you haven't already)
3. Expose the constructor at first to make the change small and manageable
4. Get everything compiling and committed!
5. One by one, copy each function that is consuming your new Custom Type and call it from the new module
6. Once that's done, you can now hide the constructor, and you now have a proper Exit Gatekeeper for your type!

How do you get started on a 1,000-piece jigsaw puzzle? I'll bet you get the obvious pieces out of the way quickly: the corners and edges. It turns out that your jigsaw puzzle strategy can teach you a lot about how to write elm code effectively and easily!

The Jigsaw Approach - Frame Then Fill In

Once you've built out the Frame of a jigsaw puzzle, you've actually accomplished a lot in very little time! You've placed less than 10% of the 1,000 pieces. But in starting with those pieces, you've gained several advantages:

• You placed those pieces very quickly.
• You now have a frame of reference that will make it faster to place the remaining pieces.
• You know the scale of the entire puzzle so you can anchor things like "halfway down" or "at the very top."

Frame then Fill In your code

What's the equivalent of a puzzle's Frame in elm code?

• Type definitions
• Type annotations

In other words, Types! Types create a Frame for your elm code, giving you a reference point that provides feedback as you work through the details.

Frame Then Fill In a JSON Decoder

How do you build up a JSON Decoder using the Frame then Fill In technique? Let's walk through the steps.

You're given a JSON endpoint which gives you a list of Attendees for an Event. Attendees always provide their first name, but may not have provided their last name. Here's the Frame for Attendees.

type alias Attendee =
    { first : String
    , last : Maybe String
    }

decoder : Decoder (List Attendee)
decoder =
    Debug.todo "Implement this"

With this tiny step, you've just built a compiling Frame! This gives you exactly the same benefits as with the jigsaw's Frame:

• You could write the Frame (type definition and type annotation) far faster than the details for it.
• You now have a frame of reference that gives you feedback if you take a step in the wrong direction.
• You know the general shape, now you just have to fill in the details.

Avoid intertwining Framing and Filling In. You'll move a lot faster that way.

Fill In the Frame As Simply As Possible

You have a special advantage in elm that you don't get with the jigsaw puzzle. The puzzle only has a single Frame. But with your elm code, you can break out several sub-problems and use Frame and Fill In to solve each sub-problem. So let's take the smallest step to Fill In our Frame. That way we can create a "Sub-Frame" to move through the rest of the problem even faster!

Your code is compiling and crashing (as is often the case with a Frame). So let's take the smallest step to get it compiling and not crashing. What's the Shortest Path there? It's so obvious you may not even think of it!

decoder : Decoder (List Attendee)
decoder =
    Decode.succeed []

It would have been a longer path if you tried to actually get a Decoder for the Attendee. This small step is like a waypoint, allowing you to get feedback before venturing out on the next small step.

Frame the Next Sub-Problem

You'll need to decode a single Attendee. So you have a "puzzle" (the next sub-problem). Now you just need a Frame!

decoder : Decoder (List Attendee)
decoder =
    Decode.list attendeeDecoder

attendeeDecoder : Decoder Attendee
attendeeDecoder =
    Debug.todo "TODO"

Again, this Frame is compiling but crashing. So again, the next step is to Fill In the Frame as simply as possible to get it compiling and not crashing.

attendeeDecoder : Decoder Attendee
attendeeDecoder =
    Decode.succeed { first = "John", last = Nothing }

Completing the Frame

You've just got one more step before you have your complete jigsaw Frame. After that, you'll just have to fill in the details!

attendeeDecoder : Decoder Attendee
attendeeDecoder =
    Decode.map2 Attendee firstNameDecoder lastNameDecoder

firstNameDecoder : Decoder String
firstNameDecoder =
    Decode.succeed "John"

lastNameDecoder : Decoder (Maybe String)
lastNameDecoder =
    Decode.succeed Nothing

Finally, Just Fill In the Blanks

At this point, you've done the "easy part". The 10% of the puzzle that makes the other 90% way faster and easier. You've built your Frame. Now you just need to get the details right for the first and last name decoders. But you could actually run this decoder and see whether you get back the correct number of Attendees. They would all be named John for now, but hey, you would know that you're on the right track!

Does Elm fill in your business logic and build your app for you, or fix bugs in your code's logic? If not, then how can it be that "if it compiles, it works?"

Finding the boundaries

Let's set a bounding box around this statement as a starting point. I think we can agree that on the one extreme, Elm does not fix your bugs or write your business logic for you. So if it means anything, the phrase "if it compiles, it works" at least has a limit to its scope.

On the other extreme, when our Elm code is compiling there are some basic things that we expect (at least in practice):

• No runtime exceptions (possible, but rare enough for us to be confident)
• Types are what they say they are (we can't fool the Elm type system to bypass typechecking)

So "if it compiles, it works" is somewhere between meaningless and true without caveats.

If It Compiles, The Refactoring Worked

People often talk about the experience of safe refactoring in Elm. You can do a sweeping change and feel confident that you didn't break anything once you get it compiling again.

If It Compiles, Every Case Is Handled

Even though Elm doesn't write our business logic for us, it does have a lot of tools to remind us of cases to consider. When you add new functionality, it's a common experience to have the compiler walk you through several places that now have an inexhaustive case expression. You can bypass this, so it doesn't come for free. It's our job to use the tools that Elm gives us so the compiler can safely guide us through adding new functionality (see [when-it-compiles-but-doesnt-work]).

Opaque Types also help us feel confident about our wiring beyond just having the right type of data. It can help give meaning to this data, and to give us guarantees about things like the origin of the data and how/where the data is used. See [exit-gatekeepers] and [entry-gatekeepers].

If It Compiles, It's Wired Correctly

Can working from a clean slate give us the feeling that if it compiles it works? If Elm isn't writing our code for us, then it can't get us all the way there. But I have often experienced the feeling of writing an Elm custom type, being sure to wire it up (through update, view, etc. - of course it won't work if I forget that), and then once it's wired in it does seem to "just work."

My personal experience with this is that it applies to wiring, which in other languages is often something that I have to take a lot of care to get right and spend a lot of time debugging as I build features from scratch. When it comes to building up sophisticated business logic, I start by writing unit tests and iterate on that, so that's far from "if it compiles, it works." It's more of an iterative process where it goes through several stages of completion where it's compiling but doesn't handle all of the cases (it only does enough to make my test cases pass).

So for me, the phrase "if it compiles, it works" doesn't apply to writing my business logic from scratch, but it does apply to the wiring and that in turn lets me focus on my business logic more.

If you use tools to help you wire external systems safely to your Elm code ([types-without-borders]), then you can extend this confidence about correct wiring to the parts of your code that communicate with external systems.

If The Tests Pass, It Works

When I'm writing my unit tests in Elm, I also feel more confident that "if my tests pass, it works." Why would this be different in Elm than working in other languages? One major factor is that Elm doesn't need mocks (nor does it have the ability to do mocks since it's not a dynamic language). You can use dependency injection. In fact, this is baked into the paradigm with things like random numbers, the current date, or other non-deterministic data: the only way to get it is to receive it in update from the Elm runtime.

Because I know my Elm code doesn't depend on global environment, implicit side effects, and non-deterministic functions, I can trust the green I get when my unit tests pass. Testing that an input gives an output removes many testing pitfalls and painpoints. The Elm language makes testing easy and safe, so that's all the more reason to test your Elm code.

That's also a good reminder that type-safety is a complement to automated tests, not a replacement for it. I can say for certain that my confidence changing my Elm applications would be very low if I didn't have automated tests.

What Do You Think

What does "If it compiles, it works" mean to you? And what are the limits? When does it compile, but not work? I'd love to hear your experiences.

We've all experienced routines that set us up for success in our day. For some, starting with a workout makes everything else fall into place. They're more likely to eat healthy, stay on top of emails, and follow other good habits if they start our day with that one keystone habit.

The specific keystone habit will vary from person to person, but the concept is the same. That one habit is worth putting in the extra effort to maintain because it will act as a force multiplier.

With a growing Elm codebase, one keystone habit that keeps all the other habits on track is unit testing. If you follow [[tdd]], you're likely to form better habits around data modeling, code organization, function names, and almost every meaningful measure of code quality.

Let's look at why test-driven development has this effect.

Extract Modules

What do I even test here? If I asked you to go test an area of your code, what functions would you call? In what module? Are you going to call a function in your Page/Projects.elm module from your test? Oh wait, but that function takes in the Page.Projects.Model, so I'll need to change the function signature so it just passes in the Project and returns a Project.

If you sit down to test something, you will naturally feel the pain of using code that's intertwined with your UI code and other unrelated domains. And feeling that pain is a good thing.

Read the Signals the Pain is Sending

Pain is a good thing. If you are able to respond to it. Imagine if you didn't have the ability to feel physical pain. Then imagine that your arm is twisted in a "painful" position. But you're not feeling that pain. By the time you notice, you'd have a broken arm.

The pain is there to send you a message. When you receive that message, you respond, adjust your arm, and avoid harm. No broken arm.

If you're not using test-driven development, you're not feeling the pain of code with lots of dependencies, too many responsibilities in one module, and other code maintainability issues. You're missing the message. Test-driven development lets you tune into that message so you can avoid harm before it's too late. When you sit down to write a test, you will feel these pain points more acutely, which gives you the opportunity to respond.

Feel pain sooner, then you can respond to small pains with ease, not big ones that are hard to mend.

Freedom to Change and Experiment

Sure, Elm code is known for being very easy to refactor because of the language design itself. But as your codebase grows, you'll run into more complex business logic. Unit tests give you more confidence to try out different ways of modeling your data. So even when it comes to trying to [[Make Impossible States Impossible]] using data modeling techniques, you're going to feel more confident to try many different ways of modeling the data if you're supported by a test suite.

Great design isn't just about thinking hard and coming up with the perfect solution. It's an evolutionary process, and it requires experimentation. The better you are at experimenting, the better your designs will be over time (you can't skip the over time part, because good design is a process not a destination). Test-driven development improves your ability to experiment, so it enables better designs to emerge.

Emergent Design

Unit tests are essential for allowing you to focus on one case at a time instead of trying to get everything working all at once. This approach of doing the simplest thing that could possibly work allows you to avoid unnecessary abstractions. You can design for your current needs instead of anticipating lots of future needs. Without test-driven development, it's very difficult to slice things down to small steps. With a unit test, you can write a failing test for the simplest possible case (an empty list when sorted is an empty list). Once you get that case working, you can move on to the next case. And at each small step, you have a simple design perfectly suited towards solving that problem (not every possible problem you might encounter in the future). So test-driven development is going to lead you towards a simpler codebase with more lightweight abstractions tailored towards exactly what the code needs.

Continuous Improvement

There's going to be more friction coming back to code and revisiting a design or making a small change if you don't have tests. And if you're changing the behavior in a small way (fixing a bug or adding a feature), then it will of course be a lot easier to be confident that you've made the desired change without other unintended changes if you have a suite of tests to support you.

Getting Started

If you want to learn more about the Red-Green-Refactor cycle and applying those techniques in Elm, you can listen to the Elm Radio episode on testing. Or reach out to me and let me know your questions! Happy testing!

Why use tiny steps? Simple! Because we want to write Elm code faster, and with more precise error messages to guide us through each step.

Setting Up Your Environment

The point of taking tiny steps is that you get constant, clear feedback. So before I walk through the steps, here are some things to set up in your editor to help you get more feedback:

• See Elm compiler errors instantly without manually running a command. For example, have elm-make run whenever your files change. Or run elm-live, webpack, or parcel in watch mode.
• Even better, get error messages in your editor whenever you save. Here are some instructions for configuring Atom with in-editor compiler errors.
• Note that with both of these workflows, I recommend saving constantly so you get instant error messages.
• Atom also gives you auto-completion, which is another helpful form of feedback. intellij-elm is another good option for this.

The Problem

We're doing a simple blog page that looks up articles based on the URL. We've already got the wiring to get the article name from the URL (for example, localhost:8000/article/articlePath). Now we just need to take that articlePath and use it to look up the title and body of our article in a Dict.

The Tiny Steps

If you'd like to see a short video of each of these steps, or download the code so you can try them for yourself, just sign up here and I'll send you a link.

Okay, now let's walk through our tiny steps for building our Dict!

Step 0

Always respond with "Article Not Found."

We start with the failure case because it's easiest. This is sort of like returning 1 for for factorial(1). It's just an easy way to get something working and compiling. Think of this as our "base case".

view : Maybe String -> Browser.Document msg
view maybeArticlePath =
    articleNotFoundDocument

articleNotFoundDocument : Browser.Document msg
articleNotFoundDocument =
    { title = "Article Not Found"
    , body = [ text "Article not found..." ]
    }

We've wired up our code so that when the user visits mysite.com/article/hello, you'll see our "Article Not Found" page.

Step 1

Hard code an empty dictionary.

view : Maybe String -> Browser.Document msg
view maybeArticlePath =
    Dict.get articlePath Dict.empty
        |> Maybe.map articleDocument
        |> Maybe.withDefault articleNotFoundDocument

Why bother? We know this lookup will always give back Nothing! So we haven't changed the behavior at all.

This step is actually quite powerful. We've wired up our entire pipeline to reliably do a dictionary lookup and get back Nothing every time! Why is this so useful? Well, look at what we accomplish with this easy step:

• We've made the necessary imports
• We know that all the puzzle pieces fit perfectly together!
• So even though we've done almost nothing, the work that remains is all teed up for us! This is the power of incremental steps. We've stripped out all the risk because we know that the whole picture ties together correctly.

When you mix in the hard part (building the actual business logic) with the "easy part" (the wiring), you end up with something super hard! But when you do the wiring first, you can completely focus on the hard part once that's done. And amazingly, this small change in our approach makes it a lot easier.

Step 2

Extract the dictionary to a top-level value.

view : Maybe String -> Browser.Document msg
view maybeArticlePath =
    Dict.get articlePath articles
        |> Maybe.map articleDocument
        |> Maybe.withDefault articleNotFoundDocument

articles =
    Dict.empty

This is just a simple refactor. We can refactor at any step. This is more than a superficial change, though. Pulling out this top-level value allows us to continue tweaking this small area inside a sort of sandbox. This will be much easier with a type-annotation, though…

Step 3

Annotate our articles top-level value.

view : Maybe String -> Browser.Document msg
view maybeArticlePath =
    Dict.get articlePath articles
        |> Maybe.map articleDocument
        |> Maybe.withDefault articleNotFoundDocument

articles : Dict String Article
articles =
    Dict.empty

This step is important because it allows the Elm compiler to give us more precise and helpful error messages. It can now pinpoint exactly where things go wrong if we take a misstep. Importantly, we're locking in the type annotation at a time when everything compiles already so we know things line up. If we added the type annotation when things weren't fully compiling, we wouldn't be very confident that we got it right.

Step 4

Use a "synonym" for Dict.empty.

articles : Dict String Article
articles =
    Dict.fromList []

What's a synonym? Well, it's just a different way to say the exact same thing.

Kent Beck calls this process "Make the change easy, then make the easy change." Again, this is all about teeing ourselves up to make the next step trivial.

Step 5

Add a single item to your dictionary

Dict.fromList
    [ ( "hello"
        , { title = "Hello!",
            body = "Here's a nice article for you! 🎉"
          }
        )
    ]

Now that we've done all those other steps, this was super easy! We know exactly what this data structure needs to look like in order to get the type of data we need, because we've already wired it up! And when we finally wire it up, everything just flows through uneventfully. Perhaps it's a bit anti-climactic, but hey, it's effective!

But isn't this just a toy example to illustrate a technique. While this technique is very powerful when it comes to more sophisticated problems, trust me when I say this is how I write code all the time, even when it's as trivial as creating a dictionary. And I promise you, having this technique in your tool belt will make it easier to write Elm code!

Step 6

In this example, we were dealing with hardcoded data. But it's easy to imagine grabbing this list from a database or an API. I'll leave this as an exercise for the reader, but let's explore the benefits.

When you start with small steps, removing hard-coding step by step, it lets you think up front about the ideal data structure. This ideal data structure dictates your code, and then from there you figure out how to massage the data from your API into the right data structure. It's easy to do things the other way around and let our JSON structures dictate how we're storing the data on the client.

Thanks for Reading!

You can sign up here for more tips on writing Elm code incrementally. When you sign up, I'll send the 3-minute walk-through video of each of these steps, and the download link for the starting-point code and the solution.

Let me know how this technique goes! I've gotten a lot of great feedback from my clients about this approach, and I love hearing success stories. I'd love to hear how you're able to apply this in your day-to-day work!

Elm's Opaque Types are a powerful tool for narrowing the surface area where you check a constraint. TypeScript's Branded Types give similar functionality but without closing outside use, so you can't be sure the constraints are enforced everywhere. Let's explore the differences to better understand why Elm's Opaque Types are such an important tool.

Strictly speaking, opaque types don't make Elm's type system more sound. Instead, they help you narrow your thinking of how a particular type is used to within a single module. They allow you to check that a constraint is enforced in a single module, rather than having to ensure that a constraint is enforced throughout your entire codebase, both now and in the future.

For example, if you want to ensure that a String actually represents a confirmed email address, that has nothing to do with type soundness - the type is just a String. But if the only way to get a value with type ConfirmedEmailAddress = ConfirmedEmailAddress String is through an HTTP request to a specific server endpoint, then you can trust any value of that type after checking the ConfirmedEmailAddress module and the API endpoint. You just need to make sure that you trust that server endpoint and the ConfirmedEmailAddress module. It's the same idea as [exit-gatekeepers].

module ConfirmedEmailAddress exposing (ConfirmedEmailAddress, checkEmailAddress)

type ConfirmedEmailAddress = ConfirmedEmailAddress String

checkEmailAddress : (Result Http.Error ConfirmedEmailAddress -> msg) -> String -> Cmd msg
checkEmailAddress toMsg emailAddress =
  Http.post
    { url = "https://example.com/confirm-email-address.json?email="
          ++ Url.percentEncode emailAddress
    , body = Http.emptyBody
    , expect = Http.expectJson toMsg
        (Json.Decode.string
            |> Json.Decode.map ConfirmedEmailAddress
        )
    }

Compare this with Branded Types in [typescript].

type ConfirmedEmailAddress = string & { __brand: "ConfirmedEmailAddress" };

// uh oh, any code can brand it
const unconfirmedEmail = "unconfirmed-email@example.com" as (string & {
  __brand: "ConfirmedEmailAddress");
};

So some drawbacks to Branded Types in TypeScript are:

• They are open and can be branded by code anywhere in the codebase
• They use casting to intersect two contradictory types. This allows you to create an artificial type that can only be created through "branding", but it feels like a little bit of a hack. It also illustrates that the branding occurs through casting which allows you to tell the TypeScript compiler what the type of a value is, but this can be error prone because you could tell it incorrect type information

Checking Currency

Another example of a Branded Type in TypeScript is marking a type as representing a specific currency.

type Usd = number & { __brand: "USD" };

function fromCents(cents: number): Usd {
  return cents as Usd;
}

This Usd type allows us to brand a number so we know it represents US Dollars. That's great because we want to:

1. Ensure that the currency is not mistakenly combined with a different currency
2. Ensure that we use a consistent representation (for example, if the number represents cents as an integer rather than dollars as a float)

For point 2, we want to make sure that there is a single place that builds up currency. For example, we don't want someone to accidentally use dollars as a float somewhere. But since a Branded Type in TypeScript is "open" and uses casting to create it, there is no single place that we can enforce as the only place the logic for creating and dealing with that type. So any outside code can brand it like this:

// whoops, (fromCents(150) === 150), (fromCents(150) !== 1.5)
const aDollarFifty = 1.5 as number & { __brand: "USD" };

Compare that with an Opaque Type in Elm.

module Money exposing (Money, Usd)

type Money currency = Money Int

type Usd = Usd

fromUsDollars : Int -> Money Usd
fromUsDollars dollarAmount = Usd (dollarAmount * 100)

fromUsCents : Int -> Money Usd
fromUsCents usCents = Usd usCents

Our Elm Usd type cannot be created outside of that module. If we want to see how that type is being used, we only have one place to look: within the Money module where it's defined. Since it isn't exposed to the outside world, we know that we've limited the possible ways that outside code can use that type.

Branded Types and Unique Symbols

The technique described above is the idiomatic approach to branded types in TypeScript (used in the official TypeScript examples and in the TypeScript codebase). There is another technique that allows you to provide unique brands that are enclosed within a given scope using Unique Symbols.

module Email {
  declare const confirmedEmail_: unique symbol;

  type ConfirmedEmail = string & {[confirmedEmail_]: true};

  export function fromServer(emailAddress: string): ConfirmedEmail {
    // validate email address
    return emailAddress as ConfirmedEmail;
  }
}

const unconfirmedEmail = "unconfirmed-email@example.com" as // ??? there's no exported type to use here

This technique succeeds in ensuring that the ConfirmedEmail type cannot be constructed outside of the scope of Email (assuming you don't use any types of course).

However, now we have no exported type to use to annotate values to ensure that the correct type is used. That means we can't write code like this outside of the scope of Email:

function sendEmail(email: Email.ConfirmedEmail) {
  // ...
}

You could certainly implement sendEmail within the scope of Email. But I think being able to annotate values is an important feature that is likely to become a roadblock when we want to ensure we receive our unique branded type as a parameter somewhere outside of Email.

We could export the ConfirmedEmail type to outside of the Email module, but then that gets us back at the initial challenge with branded types: the type can be used to cast a value that is constructed anywhere in our codebase.

const unconfirmedEmail =
  "unconfirmed-email@example.com" as Email.ConfirmedEmail;

The TypeScript language could have a specific feature for opaque types (like Flow's Opaque Type Aliases), but it seems that they plan to stick with the current branded types approach as the recommended solution.

More Resources

Opaque Types in Elm are a powerful tool to let you narrow the scope of code you need to think about to make sure you've gotten your constraints right.

• Check out our Opaque Types Elm Radio episode.
• We also have an Elm Radio episode where we do a thorough comparison of Elm and TypeScript's Type Systems
• Joël Quenneville's talk A Number by Any Other Name has some great examples as well.
• [typescript-blind-spots] catalogs all the ways that you can introduce unsound types in a TypeScript program

Your development habits and processes are perfectly designed to give you exactly the results you're getting. Do you wish something was different about those results? You'd like it to be easier to understand code, or add new features? The solution is simple and unglamorous. Focus on building the right habits. And step back to look at your development processes to consider how they support or hinder building those habits.

So what do those habits look like? The key to manageable code is not applying big, complex ideas occasionally (you know, those 4 week refactoring branches). Instead, it comes from applying very simple ideas persistently. Relentlessly. No seriously, turn that dial up all the way to 11.

Things That Get in the Way of Relentless Habits

Habits are key. But in order to build these habits, you need to double down on rewarding those habits by removing friction. Habits form when you get that positive signal when you perform the habit.

If your build server is very slow, then you won't build a habit of refactoring as soon as you see the opportunity. If you don't have unit tests, then you won't build the habit of changing your underlying data types to better reflect your domain. If setting up a unit test is cumbersome then you won't write tests.

Anything that increases confidence or otherwise reduces friction to making changes is a [[keystone habit]]. That is, getting in the habit of improving your feedback loops and safety nets will enable you and your team to build other good habits faster. Keystone habits are a key ingredient to Relentless, Tiny Habits.

The Core Habits

What are those core habits that keep Elm code manageable? Again, these aren't big, complex ideas applied occasionally. They're simple. The hard part isn't the ideas and the techniques, it's building the habits and applying them relentlessly.

Also keep in mind that these are not destinations, but rather directions. These do not represent perfection, but a direction to move towards. Don't let the perfect be the enemy of improvement. Improvement is the goal at every step.

Narrow the source of truth

• Move things into modules
• Use opaque types to move responsibility to a single pinch point
• Remove "Impossible States" from your data types
• Depend on fewer things. Decouple your code. Narrow down the types that you can accept, or can return.
• Turn redundant state that can get out of sync into derived state that can't be out of sync

These may sound like very fundamental techniques, and they are! But that's the point. It's not any individual step that's profound, it's the result of applying these steps constantly. The more you narrow the source of truth, the easier it will be to read and change code. Move in that direction 100 times, and now you have a transformation that was composed of several mundane changes.

Name Things Better

Naming is a process. Again, don't let finding the perfect name get in your way. In fact, grouping things together (i.e. extracting a value, function, or module) and giving that group a ridiculous name, is an improvement over not grouping them.

Once you have a cohesive grouping, move towards finding a better name.

Tiny Steps That Maintain a Working State

As you move in the right direction, you want to build-in and ensure quality at every step, rather than adding or verifying quality after the fact. That means having feedback loops, like tests and foolproof automation. You can learn more about some of these processes for building-in quality and reducing friction in [[Continuous Delivery]]. Make smaller steps, and keep things in a working state at each point along the way.

• Refactor with several small steps that keep your tests (and compiler) green
• Use automated refactorings in your IDE
• Use an elm-review rule to catch code quality with a shorter feedback loop

Getting Started

Want to try applying some Relentless, Tiny Habits? Here's a simple way to start. Open up your project. Find one of the simple changes above, like a function name that could be more clear. We constantly find these small opportunities for improvements as we read through code.

Now use your IDE's automated refactoring to rename the function. And here's the scary part. Commit it. Right now. And push it all the way through to production. If you can't do that, then write down a list of reasons you can't. Now you've got a todo list of things that are getting in the way of building relentless tiny habits to improve code. Once you've gotten through your todo list and are able to push that tiny improvement through to production, you're off to a great start!

Now do that more. Not bigger, not more complex. Just more frequently. Once that's a habit, congratulations, you're now using a Tiny Habit to improve your codebase! Now, just keep doing it. Relentlessly.

Have you ever sat down to try to test some code and not known where to start? There's a bug in production, and you want to reproduce it in a unit test before working on the fix. But what do you even test? Where is the problem?

I run into this issue often in Elm codebases. What code is responsible for the bug? The problem is this: the responsibility is diluted, there's not a single point of responsibility. Why? Because if anyone can use the code, if they can depend on it, then they will. And so over time, all the callers of the code become dependent on the internals. The concrete implementation, the data structure. Does it need to have an empty list at the end before you send it off to the server? What's the name of the field? Does it need to be ordered a certain way when you present it? Do you hide certain entires, or display them a certain way? How can you even test it... there's no single it... there are dozens of "it"s across your app in all the places it is used.

So if you don't define a single clear module that is responsible for a part of your domain, then everyone becomes responsible.

So how can you even test that? Do you test every single invocation? You can't. The solution is to make it so that there's only one possible place where you can call the code. It's important that you narrow it down, because again, Murphy's Law for calling code... Any internals that can be depended on, will be depended on. So the solution: modules!

How do modules help? Well, modules give us two things. 1) They allow us to organize a set of values/functions/types together. And 2) we can choose to hide some of those as internal details that can't be used outside the module. That's literally all that an Elm module does. And those two mechanics unlock a huge tool for avoiding Murphy's Law of Code Internals.

Let's say we have a fuzzy search dropdown in our app. We have a bug where the fuzzy searching isn't handling non-ASCII characters, like é or ø. Where do you go to fix it?

This is the code we're working with:

module AdminPage

type Msg
= FuzzyInputText String

fuzzySearchDropdown : Html Msg
fuzzyFilter : String -> Bool

We have one type of fuzzy filter function that we use in the AdminPage. But what about other pages? They do fuzzy filtering with a lot of the same logic, but it differs just a little bit.

We can find all the call sites and make sure to update those to fix the bug. And we can make sure that the test case we add is a good representation of all the call sites. Something doesn't feel right about that somehow. And for good reason, there's a problem: what about future call sites? This doesn't give us any confidence that our fuzzy search will stay fixed. It's a bug waiting to happen.

It's essential to think about not only what will this code do now, but what will the compiler and structure of the code guide people towards when they add or change behavior in the future?

And if we fix all the call sites, we don't even have the confidence that our tests mean anything! What have we even tested? We could write a test that doesn't give us confidence about all the fuzzy drop downs in our app.

So let's say that we have a bug where our fuzzy search is not handling unicode characters, and just shows no results if you have a non-ascii character.

What's the fix?

We need a FuzzyDropdown module.

module FuzzyDropdown

view : Html Msg
filter : String -> Bool

Notice that the function names become much shorter because in the context of this module the meaning is clear. That's a good sign that you've found a cohesive grouping (and also a good technique for looking for opportunities for splitting modules).

"In elm, you only test your business logic."

In other words, in the context of a JavaScript app, you have to be really careful to test wiring, and in many ways you have to emulate the role of a type system in your tests.

So a JavaScript/Ruby/other untyped test suite may include checks for:

• Does it give an error if you pass an unwanted type as an argument?
• Does it ever return null when it shouldn't?
• Does it ever enter into an "Impossible State"

What to test in elm?

So is it as simple as that in elm? You don't need to unit test your wiring, impossible states, or constraints expressed in your types (e.g. non-nullable)?

Yes, I think it is that simple! It's important to understand some context first, though. You can write your code in such a way that it doesn't really seem like business logic. Because the business logic gets buried, so it seems like something else.

It's common for wiring code to get intimately intertwined with core business logic. For example, you can have a view helper function that knows about how to display currency, or how to apply a discount code to a product. So do you test the view code in order to make sure your business logic is correct?

Flip it around

Instead of testing the business logic that's accessible to test in your code, make the business accessible and test it.

• Keep all your interesting business logic decoupled from wiring and display logic.
• Given your nice, independent business logic modules, write unit tests for those.

Test-first guides you to decouple business logic

Writing unit tests before versus after writing your implementation is fundamentally different. One of the core benefits of Test-Driven Development is that it guides you to keep your business logic decoupled from your wiring and view logic. Because you're writing tests first, you will naturally write testable code, since you're thinking about how to test it before you think about how to implement it.

At Elm Conf 2018, I gave a talk called [types-without-borders]. In the talk, I discussed the idea of preserving type information when crossing the boundary between languages or environments.

I gave a demo of two different libraries that follow that principle: elm-graphql, and elm-typescript-interop. elm-graphql has stood the test of time quite well.

elm-typescript-interop was a solid idea at the time, but it missed something fundamentally that elm-graphql got right. So I'm rethinking it from scratch and introducing a new incarnation of that project that I'm, creatively, calling elm-ts-interop. In this post, I'll explore the missing piece, which needed a fresh look after a few years to discover: using a Combinator approach. I wrote about Combinators in-depth in last week's tip, [combinators]. Before I explain the new approach in elm-ts-interop, let me describe the original approach of elm-typescript-interop.

The original elm-typescript-interop

The idea of elm-typescript-interop is to look at your Elm source code and find all the ports and their type information. In Elm, a port is a way to send messages to or from JavaScript. Since JavaScript doesn't have the same guarantees that Elm does, ports are a way to have an environment with sound types and no runtime exceptions. But you can still communicate with JavaScript, just by sending messages with the concept of the Actor Model - messages can go out, and messages can come in.

You define a port with a type annotation like this:

-- this gives you a function to send a message to JavaScript
reportEvent : { title : String, message : String, kind : String } -> Cmd msg

-- this gives you a subscription to listen for messages from JavaScript
gotLocalStorage : ( { key : String, value : Json.Decode.Value } -> msg ) -> Sub msg

You can learn more in the Elm Guide's section on ports.

And in your app, you would call

reportEvent
    { title = "Could not find that discount code"
    , message = "Could not found discount code " ++ discountCode ++ "."
    , kind = "Warning"
    }

elm-typescript-interop takes that type information and generates TypeScript type definitions for setting up your Elm code. This is quite handy because it gives you

• Intellisense for autocompletions when you wire up your ports in your JavaScript entrypoint
• TypeScript errors if you pass in incorrect data
• TypeScript type information about the incoming data from Elm

Wiring up your ports looks something like this:

const app = Elm.Main.init({ flags: flagData });

app.ports.reportEvent.subscribe(function (data) {
  // report event based on `data` we got from Elm
});

elm-typescript-interop generates TypeScript declarations to bring some type-safety to this process. In hindsight, this type-safety is great, but the overall approach misses the bigger picture.

The problem with the original approach

People would often ask, "what's the best way to send your Elm Custom Types through a port?" Elm automatically sends basic types through ports, like String, Int, records, lists, etc. You can also send generic JSON data through a port. You'll have to use the elm/json package to turn your data to or from typed Elm data. If you're wondering why Elm doesn't just automatically convert any type to JSON, Evan Czaplicki's document describing his vision for data interchange is worth a read.

Initially, I thought that I would eventually come up with a way to automatically serialize more advanced Elm types, again by statically analyzing your Elm source code. Then you could serialize that data into TypeScript types automatically. I tried sketching out some design ideas, but never came up with anything that felt satisfying.

So what that left you with was using elm-typescript-interop to be a serialization/de-serialization layer. But you would then need a second layer to convert that into proper Elm data.

Let's take our example from above

reportEvent
    { title = "Could not find that discount code"
    , message =
        "Could not found discount code "
            ++ discountCode
            ++ ". Please try again."
    , kind = "Warning"
    }

What if our ideal data type in Elm doesn't have that exact shape that we want to send to TypeScript? Let's say our ideal Elm type is this

type Error
  = FatalError ErrorCode
  | Warning { title : String, message : String }

Now we need a translation function to turn that data type into a format that our port can serialize.

reportElmErrorType : Error -> Cmd msg
reportElmErrorType error =
    case error of
        FatalError errorCode ->
            reportEvent
                { title = "Internal Error"
                , message =
                    "Please contact support with code "
                        ++ errorCodeToString errorCode
                , kind = "Error"
                }

Just as we couldn't use our ideal data type in Elm because it used an advanced type that can't be automatically serialized, our ideal TypeScript type that we want to serialize to can't be expressed directly. We can't use expressive TypeScript types like discriminated unions.

But specific limitations with serializing to/from advanced data types isn't the root problem. Regardless of those limitations, we can't assume that the data format needed in TypeScript and the ideal format in our Elm code are the same. So we need to transfer the data, while also transforming it. If you read yesterday's post, this may all ring a bell. You guessed it - it's time for a Combinator!

Getting the best of both worlds with Combinators

Let's say our ideal type that TypeScript would like to work with looks like this

type Event = Error | PageNavigation;
type Error = {
  kind: "Error";
  errorId?: string;
  message: string;
  context?: string;
};

type PageNavigation = {
  kind: "PageNavigation";
  path: string;
};

Our elm-ts-interop Encoder would look something like this:

import Json.Encode as JE
import TsJson.Encode as TsEncode exposing (Encoder)


type Event
    = ErrorEvent Error
    | PageNavigationEvent Url


type alias Url =
    { path : String }


eventEncoder : Encoder Event
eventEncoder =
    TsEncode.union
        (\vPageNavigation vError value ->
            case value of
                PageNavigationEvent url ->
                    vPageNavigation url

                ErrorEvent errorData ->
                    vError errorData
        )
        |> TsEncode.variant pageNavigationEncoder
        |> TsEncode.variant errorEncoder
        |> TsEncode.buildUnion


pageNavigationEncoder : Encoder Url
pageNavigationEncoder =
    TsEncode.object
        [ TsEncode.required "kind" identity (TsEncode.literal <| JE.string "PageNavigation")
        , Encode.required "path" .path Encode.string
        ]


errorEncoder : Encoder Error
errorEncoder =
    rawErrorEncoder
        |> TsEncode.map
            (\value ->
                case value of
                    FatalError errorCode ->
                        { errorId = Just (errorCodeToString errorCode)
                        , message = "Fatal error."
                        , context = Nothing
                        }

                    Warning details ->
                        { errorId = Nothing
                        , message = details.message
                        , context = Nothing
                        }
            )


rawErrorEncoder :
    Encoder
        { errorId : Maybe String
        , message : String
        , context : Maybe String
        }
rawErrorEncoder =
    TsEncode.object
        [ TsEncode.optional "errorId" .errorId TsEncode.string
        , TsEncode.required "message" .message TsEncode.string
        , TsEncode.optional "context" .context TsEncode.string
        , TsEncode.required "kind" identity (TsEncode.literal <| JE.string "Error")
        ]

Just by writing this Elm code, we have the exact TypeScript type type Event = Error | PageNavigation that was our ideal TypeScript type! This allows us to express much more nuanced types between Elm and TypeScript (in this case we have a TypeScript Discriminated Union, for example). The type information from this Encoder is synced by running an elm-ts-interop command-line tool.

This Encoder does two things:

• Acts as an Adaptor to get the formats to line up (think American-to-European power adaptor)
• Preserves type information on both sides as it does this!

This is crucial. In building up the adaptor, the API builds up type information about what data it expects to come in, and what data types can go out. This is the missing piece from Types Without Borders! Why is this so important? There are several benefits:

• We can express much more nuanced type information through this API
• This is a Combinator, so we can build up very complex transformations by composing together easy-to-understand building blocks (see yesterday's post on Combinators, [combinators])

Because of this new approach, we now have the added benefit that we can use a single Elm port to send all possible messages to TypeScript, and a single port to receive all messages from TypeScript.

That means instead of remembering to register each port, but getting no warning if we forget one, we can use TypeScript to guarantee that we've handled every incoming message!

app.ports.fromElm.subscribe((fromElm) => {
  switch (fromElm.tag) {
    case "reportEvent":
      AnalyticsService.notify(fromElm.data);
      break;
    case "scrollIntoView":
      document.getElementById(fromElm.id)?.scrollIntoView(fromElm.data);
      break;
    // exhaustive check will fail if there are unhandled cases
  }
});

Again, this is because of the power of the Combinator pattern. Since a Combinator is just built up of other Combinators, we can build up very complex data serialization out of smaller pieces, and then combine them into one type that's nice to work with in an exhaustive switch statement!

Sneak peak of elm-ts-interop

Thanks for reading! I'll be releasing elm-ts-interop in 1 week (March 1, 2021)!, so stay tuned. If you want a sneak peak, you can browse Elm package documentation preview of the documentation. I'd love to hear your thoughts. Let me know what you think on Twitter @dillontkearns!

It would be quite dangerous to drive a car with blind spots, but not know exactly where those blind spots are. You still need to be extra careful, even with a full awareness of the blind spots. But at least you know where to put that extra care.

I look at using TypeScript in much the same way. Knowing its blind spots helps me know when to trust it and when to quadruple check. If you can drive a car without blind spots, then by all means go for the safest option. But if you are in a car with blind spots, learn its blind spots to reduce the risk. As Elm developers, we stay in Elm as much as we can. But we do need to reach out to JS/TS to leverage built-in web APIs, use the NPM ecosystem, etc. So for those times we need it, it's best to understand the blind spots.

In this post, I'll catalog the areas where TypeScript allows incorrect types to pass through.

The any type

The biggest culprit for type blind spots in TypeScript is the any type.

The any type is similar to Elm's Debug.todo "", which has type a (a type variable that could refer to anything). But there are some key differences:

• Debug.todo statements can't be used in production optimized code (elm make --optimize)
• Debug.todo can't be published in Elm packages
• Even if you managed to use Debug.todo, your code stops there!

This is a huge distinction. With Elm, even if you manage to "fool" the type system with a Debug.todo (or a hack like infinitely recursing to get any type), your code will not proceed with faulty assumptions. It's impossible to write Elm code that will continue on with incorrect types.

As an Elm developer, using TypeScript can feel like shaky ground because of this escape hatch. It's good to understand common sources of any types to know where to look out for this kind of blind spot.

Implicit any

By default, TypeScript will use an any to describe types that it can't infer, like function parameters without annotations.

function inspect(argument) {
  argument("Careful! `argument` is implicitly `any`");
}

Using the noImplicitAny option in your tsconfig.json prevents this problem by giving an error in these situations and requires you to add an annotation. I recommend using the strict option in your tsconfig.json, which includes the noImplicitAny option.

Explicit any

Even with the noImplicitAny option, TypeScript will allow you to use explicit any types. One useful technique here is to use the unknown type as a substitute for any. You can think of unknown as a type-safe alternative to any. unknown doesn't create a blind spot in the type system that allows anything to flow through. Rather, it is much like a Json.Decode.Value in Elm. You can't use it until you check its types.

function prettyPrint(value: unknown): string | null {
  if (value === null) {
    return "<null>";
  } else if (value === undefined) {
    return "<undefined>";
  } else if (typeof value === "string") {
    return value;
  } else if (value && typeof value === "object") {
    return "Object with keys: " + Object.keys(value).join(", ");
  } else {
    return null;
  }
}

You can pass any value in to prettyPrint, just like you would be able to if the argument was annotated as any. But you must check the value before using it because it is unknown.

You can use @typescript-eslint/no-explicit-any to prevent explicit any types in your own code. You can even configure it to auto-fix any types in your code and change them to unknown.

any in core JavaScript APIs

Some of the core JavaScript APIs have built-in any types. Json.parse is a common source of any's leaking into your code:

JSON.parse(text: string): any

const definitelyNotAFunction = JSON.parse(
  `"Parsing JSON can never return a function, right?"`
);
definitelyNotAFunction();
// TypeError: definitelyNotAFunction is not a function

Yikes! Not only can you assume the parsed JSON is any valid JSON value, but you can even treat it as something besides JSON! Even worse, this can escape into the depths of your code and result in type errors that are far away from their point of origin. In a nutshell, any makes it hard to trust any of your code.

You can improve the safety of JSON parsing with tools that are similar to elm/json decoding.

• io-ts
• ajv
• runtypes

There are many different approaches to safer JSON parsing in TypeScript, and it's worth looking at different options and seeing if one is a good fit for your use case and has an API that suites your tastes.

Be on the lookout for any types in core JS APIs. Any time you're dealing with dynamic runtime data you're likely to see this. The eval function is a classic case of a function that truly does have any type. That's a reminder of why any is baked into TypeScript: JavaScript is inherently dynamic and dynamically typed.

any types coming from NPM packages or type definitions

Also be aware that TypeScript's declaration functionality allows you to declare the types of existing JavaScript code. These type declarations (usually bundled with an NPM package, or installed with npm install --save-dev @types/<package-name>) often use any types. And even without using any, they could be incorrect because they are declaring types, not proving them soundly through typed code, as we are forced to do in Elm code and Elm packages.

Imports

Another place to be extra careful is the wiring of imports. When you do an import in Elm, you know that it has resolved if your code compiles. With TypeScript, you can describe how to resolve modules using the paths configuration in your tsconfig.json. This can be convenient or necessary at times, but it's another instance where the TypeScript compiler trusts you to do things correctly and guarantee correctness.

The same is true for defining the lib option to describe the types/runtime that you have available (for example, dom APIs, es2020, node). TypeScript takes your word for setting this up correctly, but this could lead to incorrect type checking if you have libs declared that won't be there in your runtime.

The type systems in Elm and TypeScript are operating in fundamentally different ways, built to serve their intended use cases.

Elm is a sandbox where nothing can enter with assumptions about its types. You have to prove everything to the Elm type system.

TypeScript is built in a way that's meant to be good at gradual typing, allowing you to add type information to existing JavaScript code in an incremental way.

Runtime exceptions

Any TypeScript code can throw an exception without the types indicating they might fail.

There's no way to tell by the types, which feels very different than Elm's errors as data. In particular, be on the lookout for functions around file IO and network requests.

Mutation by reference

If two references point to the same object reference, you can mutate the references according to their respective types, but they both modify the shared reference. This can lead to incorrect runtime types.

let numbers = [1, 2, 3];
let mixedValues: (number | string)[] = numbers;
mixedValues.push("Uh oh, this is not a number");

numbers.map((number) => number * 2);
// [2, 4, 6, NaN]

Index access

TypeScript assumes that the index you access is there.

const thisWillBeNull = [1, 2, 3][100];
thisWillBeNull * 2; // NaN

The type of thisWillBeNull is number (it is not nullable).

Inexhaustive switch statements

By default, TypeScript doesn't require you to exhaustively handle all cases in switch statements.

This can be improved with typescript-eslint switch-exhaustiveness-check.

Non-null assertions

TypeScript's non-null assertion syntax (!) is another place where TypeScript trusts you rather than proving correctness. You can disallow this in your own code with @typescript-eslint/no-non-null-assertion

Casts

Casts, also known as TypeAssertions, are another place where the TypeScript compiler will trust you and not check types. See Assertion Considered Harmul

Type Coercion

There are several places where JavaScript will coerce types. This is often used as a feature, but it is bug-prone and warrants extra care.

• Falsy values used in conditionals (see this handy table of truthy and falsy values)
• String concatenation

Gary Bernhardt's famous Wat video shows some amusing examples of unexpected type coercion. The type system doesn't stop most of these, so they're worth extra attention.

Can you trust an unsound type system?

Any chipping away at confidence means that you have to have a skeptical eye at every turn.

Let's think of it in reverse, though. Unit tests don't give us 100% certainty that our code is correct. Even Elm types don't give us 100% certainty that our types our correct. There are plenty of cases where we don't express every single constraint in the type system, and there's a point where it becomes so verbose to constrain your types that its more pragmatic to stop short of perfect types. Jeroen and I discuss this in our Make Impossible States Impossible Elm Radio episode.

Yes, TypeScript's type system is far less robust than Elm's. But it's far more robust than the type-safety you get in vanilla JavaScript! And I'll take all the added safety I can get! So any time I find myself reaching for JavaScript, I try to take advantage of TypeScript's added safety.

As much as I like to strive for soundness, correctness, and certainty, I will take any tool that can boost my confidence. None of these tools guarantee correctness at every level. But if you know what guarantees they offer, you can understand what suite of tools to use to give you as much confidence as possible.

The first rule of Elm is that you want to write everything in Elm. But sometimes we need to reach out to JavaScript, whether we're using ports, Custom Elements, or serverless functions. Sometimes JavaScript is just the right tool for the job.

If you're going to use JavaScript, then you may as well get the improved safety and tooling that TypeScript provides. Except that it adds an extra transpilation step. Working in Elm, that often feels like an unnecessary burden. As you may have guessed already, there is a way to get the best of both worlds!

Running TypeScript on your .js files

I've been using this approach in all my projects lately and really enjoying the simplicity. Here's how it works:

• Add a tsconfig.json to your project as usual
• Enable the checkJs and allowJs options in your tsconfig.json

You'll now get type checking in your editor for the .js files you're working on! Alternatively, you can add a // @ts-check comment to the top of your .js files, but I prefer setting it for the whole project in my tsconfig.json.

You can also set the noEmit option in your tsconfig.json to make sure there is no transpilation output.

Be sure to run tsc in your builds to make sure that new code doesn't make it to production if there is a TypeScript compiler error. This is one of the reasons that transpiling may feel safer, because you won't even get JavaScript output when there are errors (unless you overide noEmitOnError in your tsconfig 😳). I feel comfortable with that tradeoff, but it's very important to make sure your builds fail if there is a compiler error!

Sidenote: I recommend setting the strict option in your tsconfig to true to avoid pitfalls like implicit any. There are still pitfalls where you may have type errors even when TypeScript says your program compiles, but at least it gets you a lot closer to a sound type system. In a future post, I'll discuss when you can trust TypeScript and where it has blindspots.

Here's a sample tsconfig.json with this setup:

{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,
    "noEmit": true,
    // make the compiler as strict as possible
    "strict": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "noUncheckedIndexedAccess": true,
    // get intellisense for the available platform APIs
    "lib": ["dom", "es2020"],
  }
}

Adding TypeScript types to your .js files with JSDoc comments

Once you've got the TypeScript compiler wired in for your project, you'll need to add type annotations and define TypeScript types so that you can work with TypeScript and use strict, explicit type checks.

You can include type information in JSDoc comments.

/**
 * @param {Language} language
 * @param {string} name
 * @type {import("./user")} user
 * @returns {string}
 */
function greet(language, name, user) {
  /** @type {string} */
  let greeting;
  greeting = `${helloInLanguage(language)} ${name}`;
  const username = user.username;
  if (username) {
    greeting += ` (@${user.username})!`;
  }
  return greeting;
}

/** @typedef {"english" | "spanish"} Language */

Let's break down what's happening here.

• /** ... */ defines a JSDoc comment
• @param defines a parameter (name is a parameter name for the greet function). You write one @param line for each parameter.
• The values between the {}'s (like {string}) can be any valid TypeScript type, including unions and other advanced types, or types defined in other files
• We can't import TypeScript types directly in code as we can in .ts files, but we can use import within the {}s in JSDoc comments to refer to types in other files or NPM packages
• The @type JSDoc comment lets us declare the type of the greeting variable
• We're using @typedef to define a union type called Language, then specifying that the language parameter has that type.

In VS Code, you can start typing /** and it will code complete for all the parameter names in the function's parameter list. Also, since this is JSDoc, you can include documentation here and it will show up in your editor tooltips.

You can find a full list of supported JSDoc TypeScript directives, and take a look at the official TypeScript guide on using TypeScript in .js.

What are the downsides?

Most TypeScript functionality is available using JSDoc comments. And, importantly, you can enforce TypeScript rules with the exact same strictness that a .ts file would allow.

The main limitation is that you don't have access to some TypeScript-specific syntax.

• as, also known as type assertions (or casts)
• is, also known as type predicates
• !, non-null assertions

However, non-null assertions and as (casts) are two unsafe operators that, as the TypeScript docs say, let you tell the compiler "trust me, I know what I'm doing." As Elm developers, we want to avoid these as much as possible. So while there are some syntax features that aren't available in JSDoc-typed .js files, you can get most of what you need to take advantage of the added safety of TypeScript. And you can use the @type directive to perform type casts using JSDoc syntax as well.

TypeScript in Elm

I'm writing this series of posts about using TypeScript with Elm in preparation for the upcoming launch of my redesigned elm-ts-interop tool. If you missed it, I wrote a post introducing some of the concepts in my post Types Without Borders Isn't Enough. I'll be launching elm-ts-interop on March 1st, with a free set of core features, and some paid pro features to help with code generation.

Got any TypeScript for Elm users questions? Send them my way and I'll do my best to answer them!

In Elm code, "if it compiles, it works." Does that come for free? Let's see if we can find Elm code where "it compiles, but it doesn't work" to see what we can learn about writing maintainable Elm code.

Violins and Vuvuzelas

Do violins make beautiful sounds? As a non-violinist who has tried a violin, I'm living proof that sometimes the sounds they create are not so beautiful. But there's plenty of proof that they make beautiful sounds as well.

Does a vuvuzela make beautiful sounds? I don't think it's controversial to say that it's probably not even possible. So violins are something special without a doubt. While a violin can't make beautiful sounds without the right technique, it is equipped with several tools that give it unique expressive power. By changing the angle of the bow, how close to the bridge you play, the speed of the bow, and by moving our fingers on the fingerboard (vibrato, intonation), there is as much expressive power as almost any musical instrument in the violin.

The Expressive Power of a Vuvuzela

Elm doesn't give you safe code for free. It does help you avoid several footguns through its explicit semantics and strict type system. But just as importantly, it provides tools for you to express the constraints of your system. And when you express those constraints in Elm, you can really trust them. There is no way to bypass the constraints or fool the type system. So having the expressive power of a vuvuzela will limit you. But tools are only as good as our ability to make use of them. Elm's guarantees are 100% not 99%. But it can't enforce constraints that are specific to your domain. So remember that it's up to you to write custom tailored guarantees for your domain. As an Elm developer, you're like the violinst - you have a beautiful tool in your hands but its up to you to use it to its full potential.

To make the most of these tools for enforcing constraints, lets see what happens when we don't make use of them. Lets try to pinpoint the key techniques for leveraging those tools to make Elm code feel like "if it compiles, it works."

Defaults, Squelched Errors, and Catch-Alls

username
    -- this should never happen
    |> Maybe.withDefault ""

I'm guilty of writing code like this. And if you're like me, you know the feeling of spending too much time debugging a problem only to find a line of code like this and realizing that you should always expect the unexpected.

This can be particularly elusive when these default values trickle their way through the system to end up in states that otherwise seemed impossible. It can also lead to silent runtime failures instead of a descriptive compiler error (inexhaustive case errors, type errors, etc.).

That can mean the difference between Elm being a helpful and alert assistant and Elm becoming a lazy assistant. Elm can only help you enforce the constraints you tell it about.

Also be on the lookout for catch-all clauses like this in your code:

type Membership
    = Pro
    | Free

case membership of
    Pro ->
      "Pro"

    _ ->
        "Free"

This will fall through to the correct value now, but if you add a new Membership level then you'll end up with code that "compiles, but doesn't work."

type Membership
    = Pro
+   | Premium
    | Free

Note that catch-all's can be what you want in some cases, so you need to use your judgement to make sure it's what you want. For example, perhaps an isFree : Membership -> Bool could safely use a catch-all. Though the cost of handling it explicitly is low, and there's always a risk that the catch-all could cause you to miss something important (like adding a FreeTrial level of Membership).

As an alternative to default values, squelched errors, and catch-alls, you can consider using Debug.todo statements as a placeholder for unhandled cases during development. Then you are reminded to handle those cases before your code goes live (since elm --optimize will fail if there are any uses of Debug).

Types With Borders

If you've ever iterated on writing an elm/json Decoder then you know that you can easily write JSON Decoders (or encode JSON values) where it "compiles, but doesn't work." That's because within the local scope of your Elm application everything is consistent, and you've handled the possible errors in your Decoding or HTTP requests.

Using [types-without-borders] can help avoid this case of "compiles, but doesn't work," by keeping your types in sync across the boundaries of your frontend. Some helpful tools for that include:

• Lamdera
• elm-graphql
• Custom code generation
• elm-ts-interop
• elm-protocol-buffers

Making Impossible States Possible

This topic comes up a lot in the Elm world, so by now we have plenty of great resources that show how these Impossible States can cause our code to "compile, but not work."

So be sure to [make-impossible-states-impossible]. Reduce states to valid states as much as possible. Keep in mind that it's not just about valid combinations of state. Make the smallest amount of state possible to express (and no less). A useful technique is to count the cardinatlity of your types. You can construct a table of values you can express with your types to help identify invalid ones.

Primitive Obsession

The code smell often referred to as Primitive Obsession is when values like String or Int are over-used. Under the hood, you'll need Strings and Ints, but you can give better semantics and enforce more constraints if you create new Custom Types to wrap those primitives. For example, instead of a String we could use type Username = Username String and instead of an Int we could use type UserId = UserId Int.

Here's some code that "compiles, but doesn't work" because it allows an Int instead of a more constrained Custom Type:

getUserProfileInfo :
    (Result Http.Error User -> msg)
    -> Int
    -> Cmd msg

update msg model =
    -- ...
    ( model,
      getUserProfileInfo
        GotUserProfile
        product.id
    )

If we use a Custom Type, we could turn this into "it doesn't compile, so it doesn't work":

getUserProfileInfo :
    (Result Http.Error User -> msg)
    -> UserId
    -> Cmd msg

update msg model =
    -- ...
    ( model,
      getUserProfileInfo
        GotUserProfile
        product.id -- compiler error
        -- need to use model.currentUser.id to fix it
    )

Don't forget to [wrap-early-unwrap-late] - the goal is to have the best representation of our data for the entire life of the value.

Opaque Types

A UserId like the example above only helps us if we use an Opaque Type to help us enforce the constraint. If we can use UserId product.id then there's not much improvement.

An Opaque Type helps you reduce the surface area where you need to think about a constraint ([opaque-types-let-you-think-locally]). That means you can trust that a UserId is what it says it is.

Use Opaque Types to help enforce constraints about:

• Where the data came from
• How the data can be used
• How the data has been validated (especially helpful with the concept of [parse-dont-validate])

For example, if a username must be non-empty, representing usernames as Strings or as a Custom Type that can be freely created outside of a Username module (non-opaque types) means you need to be careful about that constraint everywhere in your codebase.

By hiding the constructor from outside of the Username module, you can enforce that guarantee in one place and have confidence in that guarantee everywhere outside of that module.

module Username exposing (Username, fromString)

type Username = Username String

fromString : String -> Maybe Username
fromString rawUsername =
    if isValid rawUsername then
        rawUsername |> Username |> Just
    else
        Nothing

isValid : String -> Bool

If you need to be careful about upholding constraints on a huge surface area in your codebase, then you won't be able to make changes with confidence. If you have a small surface area with clear responsibilities enforced within opaque types, then you can be confident the constraints will still be enforced when you change code outside the Opaque Type's module.

Getting to "If It Compiles, It Works"

We're still human, and we can still introduce bugs. And these techniques work best in tandem with automated tests, not instead of tests. But if you keep these techniques in mind, you'll get the feeling of making bulletproof changes to code that comes from using the tools Elm gives us to their full potential.