Forem: Peter Szerzo

My year on the frontend, 2020 edition

Peter Szerzo — Mon, 28 Dec 2020 13:27:04 +0000

My, oh my, what a year. Lockdown or no lockdown, the terminal blinked and the projects came and went, clocking in at the following stats for the year:

ongoing maintenance of 5 reasonably complicated apps ranging between 15k and 75k lines. Hi there, NLX Studio!
4 marketing sites, with the lovely voicecompass.ai coming in last.
one reasonably complicated backend.
one Figma plugin (fun!!).
around 15 or so quick interactive prototypes for clients.
one 3d app plus a 3d pet project.
4 app frameworks: React, Elm, Svelte and Vue.
4 styling solutions: ✨Tailwind✨, vanilla CSS4, CSS in JS, elm-ui.

Never would I have imagined there would be so much going on, and it seems next to impossible to sort out a coherent story. Nonetheless, here is a catalog of thoughts:

Elm is wonderful. Elm purism isn't.

Elm is an absolute delight of a language, bringing a strict yet friendly Haskell-like environment to the frontend. The main selling points are a bulletproof type system including type-safe IO, delightful error messages, a spotlessly designed ecosystem, and strong guarantees across the board.

I got invested in Elm way before TypeScript got decent (> v2.6) or React came out with hooks, and for the longest time I thought the best thing was to write as much in Elm as possible:

actor model for ports that are almost always used in a request-response style? Bring it!
sub-views with laborious wiring? No problem, I just use some Vim macros.
no FFI, no local state, no effect modules? Thanks for looking out for me!

Yet today, my idealism is crumbling. I am maintaining a 75k line Elm app with some straaange stuff in it just to keep it sane. Because of the boilerplate, I still find places where subscriptions aren't wired up at the detriment of UX, or even worse, conflict with each other. I re-wrote the dropdown and the list editor about 5 times each, still not happy with either of them.

Time for a change: my next year in Elm will be one that embraces custom elements a whole lot more, limiting Elm to handle sensitive logic, the simpler chunks of UI, and the crucially valuable JSON encoding/decoding. I will no longer write up clickaway handlers or set up dictionaries of dropdown UI states in Elm.

Why? I lost faith that this kind of Elm purism will get me to a level of UI quality I can defend in front of project owners. React makes a painlessly reusable generic drag-and-drop list manager in a few dozen lines. Elm never will.

The narratives of the Elm community continue to confuse me. What in the world did the 'no components' campaign even mean? Do we still advise against nesting model-view-update triplets in favor of the elm-sortable-table pattern, even though drag and drop can't be set up in the latter? Are the guarantees really that strong if people can just pass in proxies and use custom elements as they please?

Elm is definitely here to stay for me. However, I am hoping that a more critical and pragmatic approach to it will help me stay happy in the ecosystem.

React hooks are fantastic

Here's a pattern I have no complaints about: good old React hooks (GORH or something?). I wrote a number of custom hooks this year including one that fully manages a chat experience, and I simply can't think of a better way to package and share effectful, headless UI logic.

My time spent in Elm continues to influence me in the way I write React:

I strive for a limited and (allegedly) thoughtful use of local state.
no matter how good TypeScript is getting, I really miss type-safe IO the way Elm does it. I hope to use io-ts in production someday.
I never got interested in projects like immer and MobX have declined even further, in favor of what I could only call 'vanilla React'. Explicitly immutable code is alright.
this is not to say I have a beef with libraries now: I actually grew really fond of Formik. It does some very thoughtful, semantically sound heavy lifting on forms.

What about Svelte and Vue?

While I kept working on fancy(-looking) architectures in Elm and React, I also built a ton of smaller Svelte and Vue projects this year - all with satisfied owners and mostly happy users. Which got me wondering: just how much better are sites made the 'rigorous way'?

Rich Harris makes the argument that terse code is good on account of research that shows (paraphrasing here):

The bugs/lines of code ratio of software projects is more or less constant.

This is something I didn't think I would pay any attention to, but then here I am, staring at it with curious eyes.

Truth is, Svelte is just very promising right now. I can implement features in no time, the HTML templates are - regardless of how long they it takes me to warm up to them - amazing for dev speed. Best of all, the API is impressively comprehensive (springs even!!) and yet with such a tiny and well-designed total surface.

I will probably keep shying away from writing anything very complicated in it and go by the thinking of this excellent blog post. Additionally, Svelte gets bonus points for powering pretty much all my creative programming these days.

As for Vue, which I never really liked for reasons that are outside the scope of this post to explain, things might be turning around. With the community slowly upgrading to Vue 3 (including a faithful port of React hooks and proper TypeScript support), I might just wind up writing more of it myself. Let's see, let's see.

The hype I still don't buy

This year I fully stopped listening to people preaching vanilla JavaScript or out on a bundle-shaming crusade. I refuse to apologize for shipping 100 kilobytes of react-dom if it means I get to avoid hacking a static site with document.querySelector (I happen to have a site that does that and it literally keeps me up at night).

I am happy to talk about bundle sizes, loading times and the challenges of SSR-hydration as UX issues, as long as we keep in mind that the worst UX issue is and forever will be [drumrolls] [drumrolls] a runtime error. You know, the one caused by a haphazard architecture.

I should mention that more formalized alternatives like Alpine.js or Hotwire do look very promising, hopefully I will get the chance to engage with them in production soon.

Onwards to 2021

I really look forward to this next year. I wonder if I will stay a Vim user in twelve months, what my next terminal color scheme will be, whether there is going to be another super cool 3d project in store for me, and how much of the thoughts and rambles above will still hold. Look forward to writing it all up again in one year's time.

🍾Happy New Year🍾 everybody!

Generics for user interfaces

Peter Szerzo — Wed, 14 Oct 2020 15:32:16 +0000

How often do we write code that manages a list of a certain resource? Despite how common this comes up, I often struggled to find good patterns for setting up dozens of them in the same codebase - manage the recipes, the team members, the invoices - without too much repetition. Recently, I took a hint from TypeScript to set up something in React that I was finally happy with.

Basically, if TypeScript is good at handling this:

interface Recipe {
  title: string
  description: string
}

type Recipes = Array<Recipe>

Then a TypeScript-friendly frontend framework like React could surely do this:

// We get to RecipeEditorProps later in the post
const RecipeEditor: React.FC<RecipeEditorProps> = () => (
  <div>
    {/* TBA */}
  </div>
)

const RecipeListEditor: React.FC<RecipeListEditorProps> = () => (
  <div>
    {/* Some abstraction involving <RecipeEditor/> */}
  </div>
)

tldr for those who would just like to see the thing, here is a CodeSandbox.

What is a sensible abstraction that takes a component responsible for a resource and turning it into a component that handles a list of them? For lack of a better word, I am going to call it a generic UI - one that works on structures comprised of a certain unspecified type of, well, thing.

FP enthusiasts might get excited about fancier names like functor UIs or UI lifting, but I will hold off on those for the time being.

A recipe editor

A component that is responsible for editing a recipe might look like this:

interface RecipeEditorProps {
  value: Recipe
  onChange: (newRecipe: Recipe) => void
}

const RecipeEditor: React.FC<RecipeEditorProps> = (props) => (
  <div>
    <input
      value={props.value.title}
      onChange={(ev: ChangeEvent<HTMLInputElement>) => {
        props.onChange({
          ...props.value,
          title: ev.target.value
        });
      }}
    />
    <input
      value={props.value.description}
      onChange={(ev: ChangeEvent<HTMLInputElement>) => {
        props.onChange({
          ...props.value,
          description: ev.target.value
        });
      }}
    />
  </div>
);

This controlled component allows its parent to manage the resource in question so the state can be flexibly managed high enough in the component hierarchy.

Combining into a list

We can build on this simple editor to create a list of them: simply map over the list of resources and wire up the change events to (immutably) update the list at the right index, with some delete buttons to top it off. I could add some code for it here, but at that point I added another React todo list tutorial onto the pile.

Instead, let's look at a list manager component that doesn't care what is inside the node.

Abstracting a generic list editor

This abstract ListEditor component would take the resource editor component as a prop and do the rest of the work for us. Here's some type definitions for the props of such a component:

export interface Props<T> {
  values: Array<T>;
  onChange: (newValues: Array<T>) => void;
  newValue: () => T;
  newValueLabel?: string;
  Editor: React.FC<EditorProps<T>>;
}

// The props for the item editor, parameterized by T
export interface EditorProps<T> {
  value: T;
  onChange: (newValue: T) => void;
}

At this point, everything is parameterized by T, which we can later fill in as Recipe, User etc. In addition to values and onChange, the component will also need a few peripheral props like how to create a new value when the add button is clicked, and what label said button should have.

The implementation looks roughly like this:

function ListEditor<T>(props: Props<T>) {
  return (
    <div>
      <div>
        {props.values.map((item, index) => (
          <div>
            <props.Editor
              value={item}
              onChange={(newItem) => {
                // Use a helper to immutably change item at an index
                props.onChange(setAt(index, newItem, props.values));
              }}
            />
            <button
              onClick={() => {
                // Use a helper to immutably remove an item at an index
                props.onChange(removeAt(index, props.values));
              }}
            >
              Delete
            </button>
          </div>
        )}
      </div>
      <button
        onClick={() => {
          props.onChange([...props.values, props.newValue()]);
        }}
      >
        {props.newValueLabel || "Add new"}
      </button>
    </div>
  );
}

We finally get the instantiate a <props.Editor /> instance with the appropriate props, and add all the peripheral UI like add and delete buttons that would then look consistent wherever this component is used.

Adding UX goodies in peace

Now that we have a generic list editor component, we can add fancy UX features knowing that they will propagate for every single list editor in our codebase.

In the CodeSandbox, I added react-beautiful-dnd to allow simple rearranging for both the recipes list and the users list. The individual editors never found out they were being pushed around 🤓.

Conclusion

What can we do with this? I don't think it pattern makes sense as some kind of importable package - it is still quite coupled to styled UI code, and decoupling it would lead us down the road of fancy custom hooks, more custom component props or functions-as-child. I think we will be better off just setting up these few dozen lines of code in our projects and customize it to our own needs.

Perhaps more important is the general idea: components that manage a constellation of things without needing to know what the things themselves are. This kind of decoupling has saved me countless hours of maintenance work on complex projects well beyond lists. I hope it's useful for you as well!

Introducing Arborist, the tree editor for Elm

Peter Szerzo — Wed, 30 Oct 2019 09:41:56 +0000

Two years ago, I published the first version of elm-arborist, a package for editing generic tree structures in Elm. I didn't advertise it too much at the time so it quietly went through 2 major re-writes and elm bump-ed all the way up to version 8.2.0. All the while, it kept supporting more and more sophisticated needs in the NLX Studio app, where I use it to visually define conversational logic for chatbots.

Whether you have a complex use-case or not (after all, tree structures are everywhere), the goal of the library is to make editing trees smooth, contained and flexible:

Arborist takes care of editing the structure (adding new nodes, rearranging subtrees etc.).
you take care of editing the internals of each node.
divide and conquer any use-case by combining the two together with minimal glue code. And since I can't help it: #functor.

We will look into how this works in this post. But first, a quick origin story.

Where It All Began

In a previous career in the architecture world, I spent a lot of time working with a tool called Grasshopper, a visual programming extension for the 3d modeling program Rhino:

In this environment, variables are represented as sliders, connected to boxes that either did transformation on their values or used them as coordinates to draw shapes. The resulting cable salads - found in countless other tools such as cables.gl - were beautiful and weird and full of possibilities. Finally, the structure of the 'code' was visual in a way a static folder structure could never truthfully represent.

When NLX Studio, my current startup, developed a need for a tool to model conversation logic, we thought of something similar, yet simpler and easier to organize. Instead of Grasshopper's directed graph, how about a (non-binary) tree? This is what Arborist wound up supporting: utilities to create a tree holding a generic data structure, a fully flexible way to render it, along with an event handling machinery allowing users to expand and alter the structure visually.

Let's see how it all works.

Creating an Editable Tree

tldr; this section runs through a simple Arborist example. Feel free to just read the example on its own.

We start by defining a Node type, and build up a starting tree using the Arborist.Tree module.

import Arborist
import Arborist.Tree as Tree

type alias MyNode =
  { question : String
  , answer : String
  }

startingTree : Tree.Tree Node
startingTree =
  Tree.Node
    ( MyNode "How are you?" "Fine, thanks" )
    [ Tree.Node
        ( MyNode "Great. Would you like coffee?" "Absolutely" )
        []
    ]

We can define each tree with the Tree.Node constructor that takes the root node and an array of child nodes that are of the same recursive structure.

Creating trees in Elm this way is nothing new or special. It is, in fact, a very common example when talking about the language's type system.

Next, we lay out a Model that contains this tree, as well as some internal state that Arborist will need:

type alias Model =
  { tree : Tree.Tree MyNode
  , arboristState : Arborist.State
  }

init : Model
init =
  { tree = startingTree
  , arboristState = Arborist.init
  }

The editor will need some initial settings:

arboristSettings : List (Arborist.Setting MyNode)
arboristSettings =
    [ Settings.keyboardNavigation True
    , Settings.defaultNode (MyNode "A" "Q")
    , Settings.nodeWidth 100
    , Settings.level 80
    , Settings.gutter 20
    ]

Arborist will send a single message that updates the model like so:

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        Arborist updater ->
            let
                ( newState, newTree ) =
                    updater model.arborist model.tree
            in
            ( { model
                | arborist = newState
                , tree = newTree
              }
            , Cmd.none
            )

Instead of new state and tree values, Arborist's message comes with a function that computes them based on the current values. This is set up this way in order to prevent potential frequently fired mouse events from undoing each others' changes.

Finally, the view:

view : Model -> Html.Html Msg
view model =
    Arborist.view
        []
        { state = model.arboristState
        , tree = model.tree
        , nodeView = nodeView
        , settings = arboristSettings
        , toMsg = Arborist
        }

See the full example to see how these pieces fit together exactly.

Towards a Full-featured Editor

The simple example is a few steps behind the full-featured Arborist home page example. Here are the most important methods from the library that will get us there:

activeNode and setActiveNode: when a tree node is focused, you can retrieve it using activeNode and use it to render a piece of UI responsible for editing its internals. Use setActiveNode in the update method to persist changes in the tree.
subscriptions: like the updater from the update method above, Arborist's subscriptions take a bit of type-fu to set up. In the end, though, they won't take up that much space, and add a lot of goodies like animations and keyboard navigation outlined in the remainder of this post.

See the full example for details.

The UX Features that Count

The first few versions of the package focused on making things work and making sure that the tree could be completely separated from the Node data type it is used with. With v8.0.0, it was UX time: making complicated trees intuitive to edit.

Keyboard Navigation

Instead of laboriously panning and padding around to find nodes, trees can now be traversed using arrow keys:

Clustering

What I really loved in Grasshopper is that you could take a portion of a cable salad and pull it together in a single box with the appropriate number of inputs and outputs, the visual equivalent of factoring out a pure function. Arborist can do this for subtrees:

To implement this feature, simply add the isNodeClustered logic in settings, 'teaching' the layout algorithm whether the subtree under a node should be hidden. Edit the corresponding flag for any given node with setActiveNode.

The Minimap

The clustering feature, effective for grouping a logically coherent subtree, is not effective for making large trees easy to navigate. To cover that front, Arborist makes it easy to create synced minimaps like the ones we are used to in our IDE's:

To create a minimap in Arborist, simply re-use the arborist internal state on a new piece of Arborist.view with new settings for a smaller geometry and new views for nodes. The design of this internal state makes sure that when you interact with your tree in either views, the viewport stays in sync:

Adding these goodies to the library has been very exciting - and hopefully, there is a lot more to come.

Next up for Arborist

The next steps for the library will likely focus on performance for very large trees. My workplace needs up to this point did not include trees larger than 50 nodes, but I would be curious to look for windows of optimization in the library's codebase to become a whole lot more ambitious than that.

Do you have other ideas? Let me know by opening an issue or reaching out to me under @peterszerzo on Elm Slack or Twitter. Until then!

Rich interactive notebooks with elm-markup

Peter Szerzo — Thu, 03 Oct 2019 15:37:01 +0000

Whether it's Observable, Google Colab or Jupyter, I love interactive notebooks. If none of these names are familiar, such notebooks are documents where regular text snippets, headings etc. mingle with working code snippets. They are great communication tools and allow a kind of fluid play with code that is hard to get inside regular IDE's.

I have been interested in making my own interactive notebooks for a long time not because there was anything missing in existing solutions, but because a lot of the times I find them to be too flexible: if a notebook allows its user to change everything, they can also be break its logic pretty easily and with little help towards recovery.

And besides, how much effort would it take to make an interactive notebook on my own terms anyway...

Well, without good crutches, probably a lot, so I didn't attempt it right until I stumbled upon a package in the Elm programming language called elm-markup. Turns out, making a basic interactive notebook in it is much simpler than I had imagined: just under 200 lines and without even touching the package's more involved modules.

This experiment is what brings me to writing this series of blog posts, covering a delightful journey looking at interactive notebooks using elm-markup. We will start with a simple counter app, working our way up to some interactive drawings.

What is `elm-markup`?

It is officially described as the Elm-friendly markup language, one that brings Elm's promise of type safety and friendly error messages into the world of markup languages. Roughly speaking, I would sum it up as a kind of markup language that exposes its own internal structure (AST) so we can render it as we please: plain text, HTML, elm-ui, or any other Elm value really. Spoiler: in this post, we will be turning markup into functions.

tldr the full example with comments is available in this Ellie. The rest of the post will go over it in detail.

A basic `elm-markup` document

Let's define a simple Title block. This block would tell elm-markup that whenever it sees this piece of text:

|> Title
    Interactive counteradder

It should render the indented text inside an h1 tag. The code for that would look like this:

titleBlock : Mark.Block (Html msg)
titleBlock =
    Mark.block "Title"
        (\str ->
            h1 [] [ text str ]
        )
        Mark.string

Using this block, we can create a document like so:

Mark.compile
  (Mark.document identity titleBlock)
  """
|> Title
    Interactive counteradder
"""

Rendering this into a running Elm app involves a few more steps that will become clear later in the post. If you're curious, the package docs are your friends.

Adding a counter

The second block we will define is a named counter that renders some UI and emits the updated value as a message. The markup syntax looks like this:

|> Counter
    name = var1

And without further ado, here is the code for it:

counterBlock : Mark.Block (Html ( String, Float ))
counterBlock =
    Mark.record "Counter"
        (\name ->
            let
                -- This is a placeholder value
                -- We'll wire this up to proper state values in the next step
                val = 0
            in
            div
                []
                [ text (name ++ " = ")
                , button
                    [ onClick ( name, val - 1 )
                    ]
                    [ text "-"
                    ]
                , text (String.fromFloat val)
                , button
                    [ onClick ( name, val + 1 )
                    ]
                    [ text "+"
                    ]
                ]
        )
        |> Mark.field "name" Mark.string
        |> Mark.toBlock

Adding interactivity

So far, this elm-markup document looks pretty static. In order to make it interactive and link counters to actual values by name, we will parse these them into functions that will allow us to inject values stored in the application model. This mind-bend is probably best illustrated by this shift in type signatures for the rendered block:

-- before
counterBlock : Mark.Block (Html ( String, Float ))
counterBlock = _

-- after
type alias Values = Dict.Dict String Float

counterBlock : Mark.Block (Values -> Html ( String, Float ))
counterBlock = _

There is nothing inherent in elm-markup that would stop us from taking this shift: if we're in charge of what value a piece of markup renders to, it might as well be a function. We can use this function to inject a dictionary of Values directly from our model and wire up the (String, Float) events that changes it in response to interacting with the counter buttons.

Our finished counter block looks like this:

-- We will use this helper throughout the rest of the example
getValue : String -> Values -> Float
getValue name values =
    values
        |> Dict.get name
        -- Values that are not kept track of yet are assumed to be the default
        |> Maybe.withDefault 0


counterBlock : Mark.Block (Values -> Html ( String, Float ))
counterBlock =
    Mark.record "Counter"
        (\name values ->
            let
                value = getValue name values
            in
            div
                []
                [ text (name ++ " = ")
                , button
                    [ onClick ( name, value - 1 )
                    ]
                    [ text "-"
                    ]
                , text (String.fromFloat value)
                , button
                    [ onClick ( name, value + 1 )
                    ]
                    [ text "+"
                    ]
                ]
        )
        |> Mark.field "name" Mark.string
        |> Mark.toBlock

Doing something with our values

Now that our wiring is complete, we can simply define a Sum block that works with this markup:

|> Counter
    name = var1

|> Counter
    name = var2

|> Sum
    arg1 = var1
    arg2 = var2

What this block will do is simply take the values from the two named counters, add them together, and communicate the result as var1 + var2 == 3.

The sum block implementation looks like this:

sumBlock : Mark.Block (Values -> Html ( String, Float ))
sumBlock =
    Mark.record "Sum"
        (\arg1 arg2 values ->
            let
                res =
                    getValue arg1 values + getValue arg2 values
            in
            div
                []
                [ text (arg1 ++ " + " ++ arg2 ++ " == ")
                , text (String.fromFloat res)
                ]
        )
        |> Mark.field "arg1" Mark.string
        |> Mark.field "arg2" Mark.string
        |> Mark.toBlock

Wiring it all up

Now that we have our blocks, we can write a method that compiles a document like this one:

markup : String
markup =
    """
|> Title
    Interactive counteradder

|> Counter
    name = var1

|> Counter
    name = var2

|> Sum
    arg1 = var1
    arg2 = var2
"""

The compiler for it would look like this:

compileMarkup : String -> Result String (Values -> Html ( String, Float ))
compileMarkup markdownBody =
    Mark.compile
        (Mark.document
            identity
            (Mark.manyOf
                [ titleBlock
                , counterBlock
                , sumBlock
                ]
            )
        )
        markdownBody
        |> (\res ->
                case res of
                    Mark.Success blocks ->
                        Ok
                            (\data ->
                                div []
                                    (List.map
                                        -- Inject data into each block
                                        -- This makes them into regular `elm-html` nodes
                                        (\block -> block data)
                                        blocks
                                    )
                            )

                    _ ->
                        Err "Compile error"
           )

And finally, the main model, update and view:

type alias Model =
    { values : Values
    }


type Msg
    = SetValue ( String, Float )


update : Msg -> Model -> Model
update msg model =
    case msg of
        SetValue ( key, val ) ->
            { model
                | values =
                    Dict.insert key
                        val
                        model.values
            }


view : Model -> Html Msg
view model =
    case compileMarkup markup of
        -- The success case yields a function that takes the current `Values` dictionary
        Ok viewByData ->
            viewByData model.values
                -- Map to the program message
                |> map SetValue

        Err err ->
            text err

For a full implementation, head to the full example Ellie or the same code as a gist.

Where will we go next?

I know, I know, adding numbers is not that exciting. Eventually, we'll add sliders to make elm-webgl drawings like this one, interactive.

Until then ☺️

Safe functional IO in TypeScript: an introduction

Peter Szerzo — Wed, 04 Sep 2019 14:42:26 +0000

I spend most of my time programming in Elm these days, enjoying (while it lasts) type-safe IO and a rich type system that guarantee no runtime exceptions. And then, just last week, a fairly complex TypeScript project landed in my lap. Excited and optimistic, I spent some time looking into offering the same guarantees on this new terrain using the lovely io-ts and fp-ts packages.

This series sums up this learning journey, and goes by the name Safe Functional IO in TypeScript. It starts out with some pain points of my previous TypeScript experience, and hopefully lands someplace nice.

The need for safe IO

TypeScript's type system has gotten so good that around v3.1 and upwards, I felt comfortable making surgical changes to a 3000 loc React app relying on just the compiler and a few dozen unit tests. However, that kind of benefit only worked as long as data coming into the application behaved as I assumed it to:

interface Fruit {
  name: string;
  sweetness: string;
}

fetch("https://some.endpoint/fruit.json")
  .then(res => res.json())
  .then((fruit: Fruit) => {
    // do something with `fruit`
    // although I'm a bit worried 😨
  })

Guaranteeing that fruit is of the right shape when comes back from the server is tricky, especially since it's tempting to trust the backend team's documentation, annotate UI code like in the snippet above and move on.

But then, there is the inevitable miscommunication, mismatched versions of deployments, unpredictable caching, and the resulting bug does what bugs do best: hit hard and deliver a kind of message/stack trace that does little to narrow down its location.

Not for me, and not for the users of this next product.

Enter `io-ts`

This clever package exposes a language to define the Fruit interface above in a way that surfaces not only a static type, but also a highly graceful runtime validator. For our example, it would look like this:

import * as t from "io-ts";

// Validator object, called `codec`
const Fruit = t.type({
  name: t.string,
  sweetness: t.string
});

// Static type, constructed from the codec
type Fruit = t.TypeOf<typeof Fruit>;

There is a bit of advanced TypeScript sorcery going on here, but for now, it suffices to know that we have a static Fruit type that behaves the same as the simple interface from before. And with the Fruit object, we can do our validation:

// Instead of the optimistic `Fruit`, we can now properly annotate as `unknown`
const someValue: unknown = {
  name: "apple",
  sweetness: "somewhat"
};

const validatedApple = Fruit.decode(someValue);
console.log(validatedApple);

What comes out in the console is this:

{
  "_tag": "Right",
  "right": {
    "name": "apple",
    "sweetness": "somewhat"
  }
}

Looks like the object is trying to tell me, somewhat awkwardly and with lots of repetition, that something was right. But are we really expected to work with this?

Yes we do, but with lots of elegant help and definitely no response._tag === "Right" checks.

Enter `fp-ts`

io-ts works with the data structures of general-purpose functional programming toolkit called fp-ts, both internally and in its public API. Using the package, the object above can be constructed like so:

import * as either from "fp-ts/lib/either";

const validationFromBefore = either.right({
  name: "apple",
  sweetness: "somewhat"
});

And if we were to annotate it, it would look like this:

either.Either<t.Errors, Fruit>

Either represents a type that can go down two roads: the left, parameterized by one given type, and the right, parameterized by another. Either a folder with documents in it, or a basket with apples in it: there is always a container, and rest assured there won't be any flattened apples in that folder.

To make things a bit more concrete, the left side usually holds some error (t.Errors in our case), while the right some payload resulting from a successful operation (Fruit). In a friendlier worded language like Elm, the either-left-right triad is called result-err-ok.

Either uses discriminated unions in TypeScript so that the compiler can help us use these containers and values correctly.

Working with `Either`

As I promised earlier, fp-ts exposes some convenience functions to work with Either values comfortably. To turn the decoded result into a friendly string to display in a UI, we can use a single either.fold function that additionally takes two functions:

onLeft: a function that turns the error into string
onRight: a function that turns the successfully decoded fruit into a string

In essence, the compiler simply forces us to handle both success and error cases before it lets us interact with our program. In our case, it would look like this:

import * as t from "io-ts/lib/either";
import * as either from "fp-ts/lib/either";

// Decode an arbitrary value
const validation = Fruit.decode({
  name: "apple",
  sweetness: "somewhat"
});

const result: string = either.fold(
  (errors: t.Errors) => "Something went wrong",
  (fruit: Fruit) => `${fruit.name} ~ ${fruit.sweetness} sweet`
)(validation);

console.log(result);
// Logs "apple ~ somewhat sweet"

If we replace the value in the sweetness field with 65 (reasonably assuming that sweetness should go on a 0-100 scale), the validation would fail and you would get "Something went wrong" instead, as expected.

I set up a CodeSandbox containing some of this code. Feel free to play around with validations there. It is somewhat in flux and may contain all kinds of other goodies by the time you get to it, but isn't it more fun that way 🤓.

Conclusion

In this post, I went through how make sure that a random value in TypeScript conforms to a static interface using the io-ts package, and how to work with the resulting safe value afterwards using fp-ts.

Next up, I will set up a small app that talks to a mock server and handles all the errors. There will be some state modeling in fp-ts, with more functional tricks to enjoy. Until then!

Forem: Peter Szerzo

My year on the frontend, 2020 edition

Elm is wonderful. Elm purism isn't.

React hooks are fantastic

What about Svelte and Vue?

The hype I still don't buy

Onwards to 2021

Generics for user interfaces

A recipe editor

Combining into a list

Abstracting a generic list editor

Adding UX goodies in peace

Conclusion

Introducing Arborist, the tree editor for Elm

Where It All Began

Creating an Editable Tree

Towards a Full-featured Editor

The UX Features that Count

Keyboard Navigation

Clustering

The Minimap

Next up for Arborist

Rich interactive notebooks with elm-markup

What is elm-markup?

A basic elm-markup document

Adding a counter

Adding interactivity

Doing something with our values

Wiring it all up

Where will we go next?

Safe functional IO in TypeScript: an introduction

The need for safe IO

Enter io-ts

Enter fp-ts

Working with Either

Conclusion

What is `elm-markup`?

A basic `elm-markup` document

Enter `io-ts`

Enter `fp-ts`

Working with `Either`