
This was my third time on the Canary Islands, second time on the island of
Tenerife. I really love the 17º – 24º C (63º – 75º F) weather every day of the
year is pretty amazing. If the terrain weren't so taxing – sooo hilly!! – I
might consider moving there. I had been winking at JS Day Canarias over Twitter
("twinking"?) for several years, and I finally got to meet the organizers at
[React Alicante](https://reactalicante.es) last year, so I was delighted to be
invited this year.

Ever since I saw
[David K. 🎹's talk from React Rally 2019](https://www.youtube.com/watch?v=tpNmPKjPSFQ),
I've been curious about model-based testing. As he is want to do, his demo was a
little, let's say, "set in the future", so it took a few years for Reality to
catch up, but last year at the
[first ever Remix Conf](https://erikras.com/blog/remixconf-2022), I learned more
about [Stately](https://stately.ai)'s
[`@xstate/test`](https://xstate.js.org/docs/packages/xstate-test/) from
[Matt Pocock](https://twitter.com/mattpocockuk), who was working on the alpha
docs at the time.

This was the first year where I submitted talks before actually having any
content behind the proposals, so when I had two _different_ talks accepted
back-to-back in the same week of May, it was a little stressful. By March, I had
actually built the project that confirmed that `@xstate/test` was a way to build
tests. My friendship from Croatia the previous year with
[Debbie O'Brien](https://debbie.codes) made [Playwright](https://playwright.dev)
the obvious choice for my demo.

## Talk

Sadly, this talk was not recorded...or if it was, the video was never published.
The last video on their YouTube channel is
[the promo for the event](https://www.youtube.com/watch?v=6VHUmy-6x-g).

## Food

The day before the conference began, I went on a little excursion with my
friends from [Lemon Code](https://lemoncode.net) to experience the most
authentic food on the islands, namely those provided by a
[_guachinche_](https://en.wikipedia.org/wiki/Guachinche). Five of us piled into
a small rental car, and we did a bit of tourism on our way to the _guachinche_,
including stopping at a town where I had been before when I traveled to the
island for the first time with my family two years earlier. We ended up at
Guachinche Los Gomez. There was no menu to order from. The sexagenarian waiter
came to our table and read out a list of things they had, including such Canary
staples as _ropa vieja_ and _queso asado_. We said, "Yeah, some of all that."
Then we began to order the main course, one person asking for the _solomillo_,
but the waiter stopped us, warning that it might be too much food and we should
wait to order additional dishes until we'd had our appetizers. We acquiesed.

<p>
<img
  src="/images/guachinche-ropa-vieja-queso-asado.jpg"
  alt="Ropa Vieja and Queso Asado"
  width={3024}
  height={4032}
/>

<caption>
  <em>Ropa Vieja</em> and <em>Queso Asado</em>
</caption>
</p>

Afterwards, we actually did want to try the meat, so we ordered one _solomillo_.
In Spanish, the word "_solomillo_" is used for both beef sirloin steak and pork
tenderloin, the beef usually being way more expensive. This meat was _so_ tasty
and juicy, we were genuinely unclear as to whether we were eating beef or pork.
We confirmed with the waiter that it was pork, and someone at the table
exclaimed, "_¡Menudo cerdo, tío!_" ("Man, what a pig!")

<p>
<img
  src="/images/guachinche-solomillo.jpg"
  alt="Pork Tenderloin"
  width={3024}
  height={4032}
/>

<caption>
  <em>Solomillo de Cerdo</em> (Pork Tenderloin)
</caption>
</p>

Rather than present us with a dessert menu, the waiter just brought us three of
their homemade desserts.

When we couldn't eat or drink any more (we'd had 6 liters of local red wine), we
went to pay. There had never been any mention of prices, of course (no menus
🙄). When the waiter told us 66€, our reaction was, "That's actually not a bad
price for what we ate!", assuming it was 66€ _each_. I mean, just the wine
should cost that much! But when he clarified that it was 66€ _in total_, we were
astonished!

I've placed a digital pin on the map, so I can find that place every time I go
back to Tenerife. Wow!


Model Based E2E Testing with State Machines


I'd never been to Florida. Not counting one time when I flew into Fort
Lauderdale to hop on a cruise ship. So when my friends at
[Infobip Shift](https://shift.infobip.com/), my Croatian peeps who have invited
me twice already to their lovely homeland, announced that they were introducing
a [conference in Miami](https://shift.infobip.com/us/), I jumped at their
generous offer.
[Everything I know about Miami, I learned from Burn Notice and Dexter](https://twitter.com/erikras/status/1635620326330576901),
so I assumed there would be plenty of bikinis, cocktails, explosions, and
pristine vigilante murder. TL;DR: let's just say they named their NBA team
correctly. 🔥

<p>
<img
  src="/images/infobip-shift-miami-stadium.jpg"
  alt="The Kaseya Center"
  width={4032}
  height={3024}
/>

<caption>
  The speakers' hotel was right across the street from where the Miami Heat
  play. On the second day of the conference, they hosted, and were beaten
  by, the Boston Celtics.
</caption>
</p>

The day before the conference, I spent the entire day with a soon-to-be good
friend, [Alexandra Spalato](https://alexandraspalato.com), a French woman who
lives on the Spanish island of Mallorca. Both being expats in Spain, we had a
ton to talk about. She had the brilliant idea of visiting Little Havana, a
gorgeous little _barrio_ of Miami full of Cuban culture. We then felt obligated
to check out the famed Miami Beach, but both living near good beaches, we were
very underwhelmed. The pelicans were cool, though.

<p>
<img
  src="/images/infobip-shift-miami-alexandra.jpg"
  alt="Me and Alexandra at lunch"
  width={4032}
  height={3024}
/>

<caption>
  Lunch with Alexandra.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-miami-cuban-fajitas.jpg"
  alt="Cuban Fajitas"
  width={3024}
  height={2859}
/>

<caption>
  Cuban fajitas for lunch. Just like Mexican fajitas, but instead of
  tortillas, it's crispy banana cakes.
</caption>
</p>

## Infobip Shift Miami – 2023

<p>
<img
  src="/images/infobip-shift-miami-venue.jpg"
  alt="The venue"
  width={8316}
  height={3870}
/>

<caption>
  Look at this disgusting venue! 🌴🌴🌴🌴🌴
</caption>
</p>

The conference itself was great! Much like how it's nice to transition back and
forth between sandals and sweaters as the seasons change, it's refreshing to
alternate between single-track and multi-track conferences. So it was nice to
know that there was only ever one talk going on at this one. I tried to attend
most of them, both for knowledge, but also for emotional support for my fellow
speakers. It's so nice to have someone in the front row nodding when you're
behind the podium. There were three talks that really stood out to me.

The first was from [John Romero](https://twitter.com/romero), the creator of
[DOOM](<https://en.wikipedia.org/wiki/Doom_(franchise)>), on the timeline of how
they created a genre-defining masterpiece in a fury of development effort that
can only be mustered in one's twenties. I especially appreciated how, despite
being in Texas at the time, they modeled all the weapons after toys they found
in Toys Я Us. My favorite part of seeing him was getting to talk to him
afterwards, and telling him how, as a school project in high school, a friend
and I modeled our school in a DOOM level editor, somehow got teachers into the
racquetball court (white background) to pose in all 32 (64?) poses to generate
sprites for them, and then we ended up with a DOOM level that allowed the player
to walk around the school shotgunning teachers in the face. This was before
Columbine. Everyone took it in good fun. Nowadays, you'd be #canceled for life
for such abhorrent ideas.

<p>
<img
  src="/images/infobip-shift-miami-john-romero.jpg"
  alt="Me and John Romero"
  width={4032}
  height={3024}
/>

<caption>
  The creator of DOOM with the harbinger of it.
</caption>
</p>

The second was from [Joyce Lin](https://twitter.com/PetuniaGray). I met her two
years earlier at my first conference in Croatia, and we clicked immediately. Our
senses of humor align disturbingly well.
[Her talk](https://www.youtube.com/watch?v=8aHzQEgM1gg) was about the history of
APIs, and, having been a web developer for 20+ years, I knew every single part
of it. She did a gimmick where she gave the audience quizzes and awarded Postman
swag as prizes. About halfway through, she had to tell me to STFU because I knew
all the answers.

<p>
<img
  src="/images/infobip-shift-miami-joyce-lin.jpg"
  alt="Me and Joyce Lin"
  width={4032}
  height={3024}
/>

<caption>
  Joyce Lin and I, just getting started with the tequila.
</caption>
</p>

The one that probably most blew me away was from a guy I've known on Twitter for
years, named [Jhey Tompkins](https://twitter.com/jh3yy). Turns out he really
does wear that hat all the time! Gotta respect his personal branding.
[His talk](https://www.youtube.com/watch?v=88D6jLHFw3Q) included some crazy
ambitious things, like interacting with his slides in realtime via voice and
hand gestures with his phone. He concluded by showing a QR code where we, the
audience, could all connect and pop up emojis and comments over his slides.
Credit to the audience for being completely tasteful when we had full control to
be jerks.

## My Talk

My talk was one I've been thinking about giving for 6 months, ever since seeing
a talk about Solid JS and meeting its creator, Ryan Carniato, at
[[a disaster of a conference](https://blog.tomayac.com/2022/11/23/modern-frontends-live/)]
in London last November. I find Solid extremly interesting. Hence my blog posts
about
[Solid Final Form – Proof of Concept](https://erikras.com/blog/solid-final-form-poc)
and [XState in Solid](https://erikras.com/blog/xstate-in-solid). As a React
developer by profession, I figured I had a unique perspective to explain Solid
to other React devs.

<video>vxTbDKaSnkk</video>

The day after the conference, as a result of a "what to do in Miami" search, I
took a boat tour of celebrity houses. I saw the mansions of Antonio Banderas,
Jackie Chan (which is available on Airbnb for $7k/night for 10 people), Floyd
Mayweather, Celia Cruz, Ricky Martin, DJ Kali, Puff Daddy, JLo, Will Smith,
Rihanna, David Beckham, Gloria and Emilio Estefan, and Fisher Island, with no
bridges, where property is owned by Tom Cruise, Julia Roberts, and Oprah.

<p>
<img
  src="/images/infobip-shift-miami-skyline.jpg"
  alt="Miami skyline selfie"
  width={3924}
  height={2943}
/>

<caption>
  Miami skyline selfie.
</caption>
</p>

<p>
<img
  src="/images/infobip-shift-miami-rainy-plane.jpg"
  alt="Rainy sunset plane"
  width={3336}
  height={3024}
/>

<caption>
  There was a fantastic Florida lightning storm in the distance as I waited
  to board my plane back to the Olde Worlde.
</caption>
</p>

Thank you so much to the Infobip Shift team for knocking another conference out
of the park. It was an amazing experience. 💙


Solid for React Developers


The chart above is from
[a famous tweet](https://twitter.com/dan_abramov/status/981712092611989509) by
Dan Abramov in 2018. Dan, as usual, does an amazing job of communicating his
deep technical knowledge in a way that is easy to comprehend.

Since the release of
[Stately's Visual Editor](https://stately.ai/registry/new?source=erikras), I've
been using it more and more at my dayjob at
[Centered](https://centered.app/erik) to construct new, and comprehend existing,
state machines in our codebase. The visual editor is just so _fun_ to use!

The other day, I thought to myself,

> "I wonder if I could test my knowledge of React and state charts, and model
> the React lifecycle methods in a state chart?" 🤔

So I gave it a try!

## React Lifecycle State Chart

<p>
<img
  src="/images/react-lifecycle-state-chart.png"
  alt="React Lifecycle State Chart"
  width={2590}
  height={2084}
/>

<caption>
  Elegant, ain't it?
</caption>
</p>

One thing that immediately jumped out at me was how all the lifecycle methods –
and `render()` itself! – ended up being side effects, or "actions" in XState
parlance. This makes total sense, as they really are _where you put side
effects_!

> Rendering is a side effect!

### The Code

This is the XState machine that the visual editor generated:

```js
import { createMachine } from "xstate";

export default /** @xstate-layout N4IgpgJg5mDOIC5QCUwEMDGAXABAYQHsBbABwIDsxysA6AWQIFdrIBiAVXKKesVDNgBLLIIp8QAD0QBaAIwAGAGw0ALAE4AHPICsigMxrFi+RqMAaEAE8ZAJhsaaAdm0qVsmyb12bamwF8-C1RMXEJSCipaBmYsNgA5MAB3HAAFACcCEngkEAFhUXJxKQRpNxsaeVk9FUc1Xz09DTttC2sS-WUG9wbtbUdXWUcAoPRsfGIySmp6HliIVgBlMFwFrDRY8TyRMRzi2SqaRTVHE3t+tS7HVplFDxofBUUVDQ1ZC5tZYZBgsbDJyJmMTYADECGkMGAcOwSBB1mBNgQhNtCrsZAp5DRZC4zvI9I4DPtriVtC8aGoVDZtLImoZHI4ngFAiByAQIHBxD9QhMItNoiwIDRUOQ2WlIAikQUijJapj8U19iSVLpZCoidI9L0KvJ5EqdQTNEovpzxuEplFZmKcltJaiSio9MpKtVavVGs01S8MV07I4fJoLiojaMuaaAZxuECIOL8jtQHs8WT5fI7KY3eYrLYsU4XColIZFNofP4mca-jysNHkVK7cYKlUanUbA0mpS1XUvXp3DZatVc7JFIy-EA */
createMachine({
  description: "made by @erikras",
  initial: "Mounted",
  states: {
    Mounted: {
      entry: [
        "constructor",
        "getDerivedStateFromProps",
        "render",
        "componentDidMount",
      ],
      initial: "Rendered",
      states: {
        Rendered: {},
      },
      on: {
        Unmount: {
          actions: "componentWillUnmount",
          target: "Unmounted",
        },
        "New Props": {
          actions: ["getDerivedStateFromProps", "render", "componentDidUpdate"],
          cond: "shouldComponentUpdate",
          target: ".Rendered",
        },
        "Set State": {
          actions: ["render", "componentDidUpdate"],
          cond: "shouldComponentUpdate",
          target: ".Rendered",
        },
        "Force Update": {
          actions: ["render", "componentDidUpdate"],
          target: ".Rendered",
        },
      },
    },
    Unmounted: {
      type: "final",
    },
  },
  id: "React Component",
});
```

The crazy comment at the top is how the visual editor encodes the location of
all the boxes and arrows and whatnot, so if you open this exact file in the
editor, the layout will be the same. Clever, huh?

Of course, because
[I tweeted it](https://twitter.com/erikras/status/1539984775523475457), I got
[a clever response/challenge](https://twitter.com/donavon/status/1540112177515970567),
from my friend, Donovan:

> Nice. Now do this one.

with a link to [this chart](https://github.com/donavon/hook-flow) he, his son,
and Dan put together three years ago:

<p>
<img
  src="/images/react-hooks-lifecycle.png"
  alt="React Hooks Lifecycle"
  width={761}
  height={969}
/>

<caption>
  React Hooks Lifecycle
</caption>
</p>

I couldn't turn down such a challenge, now could I?

## React Hooks State Chart

It actually didn't take me long at all to whip up this one. Although React
hooks, as an API, is full of footguns with which to shoot yourself, the actual
mental model of what is happening is simpler than the lifecycle methods.

<p>
<img
  src="/images/react-hooks-lifecycle-state-chart.png"
  alt="React Hooks State Chart"
  width={2226}
  height={1700}
/>

<caption>
  React Hooks State Chart
</caption>
</p>

With this one, I took the additional step of imagining we were actually
implementing it as an XState state machine, where we could have to save the
props, state, and context into the machine's context (that's the XState term for
the internal storage of the machine).

### The Code

```js
import { assign, createMachine } from "xstate";

export default /** @xstate-layout N4IgpgJg5mDOIC5QCUwEMDGAXABAYQHsBbABwIDsxzdBkAhwAkCCBrWHAMQBsCB3AOgCyBAK7VIfVOQhgATpADEABRkESbPAAs05GIlBlYASyyGKekAA9EAWgAsAdgAMfewGYAnK9e3XARgBs7v6OrgA0IACeNvYATPZ8tgAcMX7BjgH+9r4AvtnhqJi4hKQUVLQMTKwc3PxColjiktJyEPIAylhoDfhaOmDmBsam5OZWCHb+iXzuvgCsvr6J7rY+7u724VHj-r7u0zGJib5uwa7+B7n56Nj4xGSU1Dh0jCxsXLyCImIQElTNCoQxBYir1dEgQIMTGZwWM7PYpnEVolzjFbLNXEdNjZ5lMfPYso5-LZHGtZjFLiACjdivcyk8Kq9qh86t95ABVchEL5YAYEIxQkYwxD2WZ8SaxWKuRwxYJJXxY7Zk6azFU7HZJFX2XJ5EDkAjSeDgqlFO6lR7PSpvGqfeqNP6ySC8-nDUY2A6uaZHEW+Ry+1zo1wbSLRGIxBIHI7pUNrGUU423EoPcovKrvWrcx3gyEuoXjWbSviIpIotEY+XB8aJeYJZKpX0ZLJx64mxN0i2MtN8Dlc20QJ1DaGgMa2fx8ZFSvy+Ym+QOzWwK6yzI58RxkxyJJKuGJT3ZNwoJ2nmhmpmr9gWuvMywv2JEl9GYivWIK+GspUMi-xz-za7JAA */
createMachine(
  {
    description: "made by @erikras",
    initial: "Mounted",
    context: {
      props: {},
      state: {},
      context: {},
    },
    states: {
      Mounted: {
        entry: "Run Lazy Initializers",
        initial: "Rendered",
        states: {
          Rendered: {
            entry: [
              "Render",
              "Cleanup Layout Effects",
              "Run Layout Effects",
              "Browser Paints Screen",
              "Cleanup Effects",
              "Run Effects",
            ],
            on: {
              "Props Change": {
                actions: "setProps",
              },
              "State Change": {
                actions: "setState",
              },
              "Context Change": {
                actions: "setContext",
              },
            },
          },
        },
        on: {
          Unmount: {
            target: "Unmounted",
          },
        },
      },
      Unmounted: {
        type: "final",
      },
    },
    id: "React Component – Hooks Flow",
  },
  {
    actions: {
      setContext: assign({ props: (_context, event) => event.props }),
      setProps: assign({ props: (_context, event) => event.props }),
      setState: assign({ props: (_context, event) => event.props }),
    },
  }
);
```

## Conclusion

Am I trying to reimplement React using state machines? Hell no!

But this exercise _has_ served to benefit my understanding – and maybe yours
too? – of how React works, how to model flows in state charts using Stately's
visual editor, and how to read and understand state charts.


Modeling React in XState


Today is my final day working for [Distru](https://www.distru.com), helping to
build a SaaS product to manage inventory, traceability, and distribution for the
budding cannabis industry. Aside from being an
[ERP](https://en.wikipedia.org/wiki/Enterprise_resource_planning), the primary
pain point that Distru alleviates is keeping every transaction and transfer
synced up with the government database in this extremely regulated industry. As
you might imagine, the APIs for communicating with the government are...
...challenging.

The whole company is full of amazing people with expertise ranging from sales to
design to engineering to cannabis itself. The engineering team I have been a
part of is fantastic. Everyone is so generous and humble and hard working. I'm
going to miss them greatly.

At this turning point in my career, I thought I'd make a note of some of the
things I've learned, mostly for myself, but for you all, too.

## Standups

Before I worked at Distru, I was part of a 2-developer "team" for 15 years. I'd
heard words like Agile and Scrum, but I'd never really lived any of it. I know
this is common in my industry, but it was new to me. Normally, a
[standup](https://en.wikipedia.org/wiki/Stand-up_meeting) – like all compound
words, it will lose the hyphen eventually; embrace it – is a quick meeting,
typically every morning, where everyone at the meeting quickly says what they
did yesterday, and what they will be working, and, most importantly, if anything
is impeding their progress. "No blockers" is a common "over and out" way to
announce that you're done talking. Because many of the team is in California,
and I'm in Spain, my standup would be at the end of my workday, where I would
report what I had accomplished. I found knowing that I would have to report
progress every day very motivating.

### Standups at Distru

I assume that typically, a standup is run by the team leader, and it is they
that call on everyone in the meeting to speak. Distru doesn't do this. At the
end of every standup, we open up [Wheel of Names](https://wheelofnames.com), and
randomly select a team member to lead the following standup. If you're
smart/lazy, you learn to call on people in the order the Zoom has placed them on
your screen. Each time, the current leader's name is from the wheel, until
everyone has done it, and then they start over will all the names on the wheel.

When it's your turn to lead the standup, you are expected to entertain everyone
at the beginning of standup with an "interesting fact" that you learned
recently. This is no trouble for me, since I regularly listen to podcasts in the
"interesting facts" genre, such as
[No Such Thing as a Fish](https://www.nosuchthingasafish.com) and
[The Omnibus Project](https://www.omnibusproject.com). What's great about this
practice is that it lets you get to know your team mates...by the facts they
choose. One engineer, who literally hunts alligators in the Louisiana bayou, can
rival Bubba in enumerating all the ways to cook a shrimp. Another, from Brazil,
would regail us with the political shenanigans of his elected officials.
Another, based in Barcelona, taught us all about the importance of
[public human defecation](https://en.wikipedia.org/wiki/Caganer) in the Catalan
Christmas tradition. Another would get so into her facts, that she prepared
slides, and would sometimes have to be told that her fact was going on too long,
and we really should start standup. It was great fun! I highly recommend
adopting this quirk to your standups.

The fact I shared on my last day is that
[badminton shuttlecocks can only be made with feathers from the **_left_** wings of geese](https://www.inverse.com/article/19768-2016-rio-olympics-goose-geese-left-wing-badminton-shuttlecock).

## Retros

A
[Retrospective](https://en.wikipedia.org/wiki/Retrospective#Software_development)
is a meeting held at regular intervals – I think Distru does it on the last
Friday of the month – in which participants are encouraged to thoughtfully
reflect upon the previous month. I'd never done this before, so I can only speak
of how they do.

### Retros at Distru

Distru uses a SaaS product called [Retrium](https://www.retrium.com) to manage
the Retro meetings. All the team members log into Retrium, and then a Retro is
initiated. Everyone is encouraged to create little cards with thoughts organized
into three categories:

- What went well
- What went poorly
- Concerns about the future

The cards are clearly skeuomorphic representations of Post-It™ notes. Part of me
suspects that 3M, the manufacturer of Post-It™ notes, is behind the Agile
movement. You can just see them brainstorming: "How can we sell more of these
sticky pieces of colored paper?" I digress...

While people are adding cards, you can only see the contents of your own cards.
Everyone else's cards are blurred out, but you can see them typing. I once tried
to inspect the DOM to see if I could see what the others were typing, but
Retrium is just putting Lorem Ipsum nonsense to encourage you to contribute,
because your colleauges are. It works.

After a set amount of time, usually 5 minutes, everyone puts down their virtual
pencils, and the contents are revealed. Everyone can participate in the next
step, which is grouping cards about the same topic. For example, there might be
three different people complaining about how slow Continuous Integration has
been running lately, or happy about a new hire, or pleased that the value of
TypeScript finally clicked with them.

Then we read over all the "What went well" cards, and anyone can comment. No one
is ever afraid to step forward and say, "I wrote that one", and explain why.

Next is the anonymous voting phase. Retrium lets gives us all some number of
votes (depending on how many people are in the meeting). You can think of it
like placing poker chips next to the card that you most want to discuss, but you
can't see other people's chips. If something is really important, you can put
all your chips on that one card. This goes on until everyone has spent all their
votes.

Retrium then sorts the cards, and we discuss the ones with the most votes. This
is really great at capturing mutual sentiment. We then have a really
enlightening egoless discussion about how we can solve whatever problem or
concern has been voted on. Using this technique, we have implemented policies
such as having a special Slack channel where we can request PR reviews, or
discuss urgent production issues.

There is also some concept of writing down action items at the end, and
reviewing them at the beginning of every Retro, but we haven't followed that
policy very well, and I think that's fine.

## One-on-Ones (1:1)

Yet another practice that, from my internet reading, seems to be generally
understood as Good Management Practice™, but that was new to me. Every month (or
sometimes every week), there would be a meeting on my calendar to have a
30-minute call with my boss.

### One-on-Ones at Distru

My boss, Johnny, made it very clear from the very beginning that he expected us
to have extreme candor with each other. Distru offered to buy
[The 15 Commitments of Conscious Leadership: A New Paradigm for Sustainable Success](https://amzn.to/2W3yVmF)
for everyone, but I bought it on my own. It's a very interesting book.

Johnny would enter these meetings with a shared Google Doc with headers like
Touching Base, Talking Points, and Takeaways. He'd ask questions like, "What
could you do to be more productive?", or "What could _I_ do to help make you
more productive?", or "What are your goals six months from now; what do you hope
to have accomplished?" Very thought provoking questions that encourage
introspection. Never once was there any emotion or resistence when we told each
other how we could improve. It was just a good, healthy, egoless, selfless
discussion.

It made me feel listened to and respected, and it gave me the confidence to
suggest things at any time.

## #muchlove

Showing gratitude is a great way to feel good and make others feel good.
Sometimes, at work, a colleague will really help you out of a bind, or will
really stand up to a challenge. Distru has a Slack channel called **#muchlove**,
in which posts always start with the name of the channel and tags someone. e.g.

- \#muchlove to @susan for jumping in on an important sales call when I had
  another call scheduled and closing the deal!
- \#muchlove to @adam for helping me figure out a complex database query
  yesterday. Couldn't have done without you, mate!
- \#muchlove to @amy for these gorgeous designs for the new \_\_\_\_ interface.
  I can't wait to implement them!

You get the drift. It seems so silly, but when you get one about you, it feels
SO GOOD!! Every company should impement a system of public displays of
gratitude.

## Welcome Letters

Whenever Distru sends an official offer letter of employment to a candidate,
they post the candidate's email address in Slack and encourage employees to send
the candidate emails congratulating them on getting an offer. This is _so_
clever! It makes you feel so warmly welcomed even before you've joined. It's
such a great psychological hack to encourage the candidate to accept. Genius!

## Feature Channels

For every new feature added to Distru, a Slack channel is created called
something like #feature-label-printing. All discussion about how that project is
going is contained in that channel. People that care can follow, and people that
don't needn't be bothered by it. When the feature is released the channel is
renamed, e.g. to #feedback-label-printing. As an engineer building the feature,
I was encouraged to post daily updates about how I was progressing. I'm sure
lots of companies do this, but I found it very useful.

## Education Sessions

Every so often – it feels like it might've been fortnightly – there would be a
meeting for the whole company where someone would give a presentation about the
cannabis industry. Before joining Distru, I had no idea about
[terpenes](https://hightimes.com/guides/what-are-terpenes/),
[trichomes](https://wayofleaf.com/education/what-are-trichomes-cannabis-terminology-101),
[resin](https://wayofleaf.com/cannabis/101/cannabis-resin-uses),
[how to trim cannabis flower](https://www.greenbudguru.com/how-to-trim-weed),
and how cannabis plants have clear genders, and if you want to maximize your THC
production, you want only female plants, and keep them away from any male plant,
[so they get really horny and produce more THC](https://www.greenbudguru.com/how-to-spot-female-cannabis).
Who knew? I sure didn't! It was fascinating to learn. Did it help me draw
rounded rectangles in the application? Not really, but it gave a sense of
purpose and wider mission to what I was building.

## Knowledge Transfer

The brainspawn of one of our Retros, we began having Knowledge Transfer sessions
within the engineering department, where every other week one or two of us would
prepare a 30-60 minute presentation about one aspect of the product we were
working on. These were recorded Zoom calls that could later be watched if you
could not attend. I gave one on forms 🙄 and another on how I was using XState
to build several of my projects. Most of them were backend stuff that I didn't
really need knowledge of, but it was fun to hear my fellow engineers speak
passionately about what they had been working on.

## Engineering Demo Days

Whenever a new feature was released, we would have an hour-long meeting for the
engineer(s) that built the feature to demonstrate how it worked to the rest of
the company, specifically the sales and customer support departments. These were
also recorded Zoom calls for posterity.

## PR QA Videos

Another idea that came out of a Retro was to require all PRs to have an
accompanying [Loom](https://www.loom.com/) video where the engineer demonstrates
that the bug fix really fixes the bug, or that the feature really works. For
bugs, I would often switch back to the `main` branch, demonstrate the bug, pause
the recording, switch to my branch, and demonstrate the fix. This serves two
purposes:

1. It provides much needed context to the code reviewer to be able to visualize
   the user flow being altered.
2. It forces the engineer to actually test their code.

That last one sounds silly, right? I only ever record my Loom video when I'm
_certain_ my code works. Even so, about **70%** of the Loom videos I made for my
PRs found a problem, and I had to stop recording, fix it, and start again. These
little mind hacks can be so useful! You can think of it like a
[Rubber Duck](https://en.wikipedia.org/wiki/Rubber_duck_debugging) Demo. We all
know that, if you want to find a bug, give a demo.

Without this practice, I would've shipped _many_ more bugs into production.

## Clean Commit History

I honestly think I had never used `git rebase` before starting at Distru, where
they have a policy of having a "clean commit history". That refers to not having
commit messages like "Tweaks" and "Let's see if CI passes now". At Distru a PR's
commits should "tell a story", e.g. First I created this component, then I used
it over here, then I connected it to the backend. My boss at Distru, Johnny,
wrote
[a fantastic Medium post](https://johnnyisji.medium.com/engineering-culture-keeping-a-clean-commit-history-453f950c1f2d)
about how to achieve this with `git rebase -i`.

This can be a lot of work, and I wouldn't necessarily recommend it for startups
where you can still feed all the engineers with
[two pizzas](https://buffer.com/resources/small-teams-why-startups-often-win-against-google-and-facebook-the-science-behind-why-smaller-teams-get-more-done/),
but for larger organizations, being able to understand commits can become
invaluable.

## Gaming Sessions

The office manager would often organize 30 minute optional "games" meetings at
least once a month using online gaming platforms like
[Jackbox](https://www.jackboxgames.com/games/). Everyone that was participating
would hop on a Zoom call, and then we'd all go to some unique URL, often on our
phones, and it would be trivia or games where we had to ask questions about a
scenario and determine which of us was the spy. That sort of party game. The
most memorable one was an escape room. We are all remote on Zoom, how can we do
an escape room? Google "virtual escape rooms". There was some service that
provided a guy with a GoPro on his head that would do whatever we told him, e.g.
"Turn that vase so it's facing the other vase", and we would decipher clues to
help him escape. It was way more fun than it sounds!

Through these "team building" exercises, I really did feel close to my team, and
put personalities to the faces from other departments that I only saw during...

## All Hands Meetings

This is a term I've heard in the industry, but my first experience was with
Distru. These were monthly hour-long meetings where the heads of each department
would present how their department was progressing, if goals were being met,
etc. The most interesting part of these meetings for me was the total
transparency of the company's financials. Things like:

- We currently have $X in the bank.
- Last month we experienced $X in churn (lost customers), which is N% more than
  last month. This was due to factors A, B, and C.
- At our current rate of burn, we have X months of runway.

Those kinds of candid discussions made me feel like the captain of the ship knew
what he was doing, and I could feel safe toiling away below deck.

All Hands meetings were often ended with...

## Meditation Sessions

Mental health and productivity is so important at Distru that they hired a
professional meditation coach to guide the entire company in 15-30 minute
meditation sessions. We'd all hop on a Zoom call, turn off our cameras, and
she'd walk us through breathing and concentrating. Can you imagine your employer
telling the entire company to "Stop what you're doing!" and meditate for 20
minutes, 2-3 times a week?

I ended up not attending very many, because, while they were in the morning
between coffees for the Californians, it was 6pm for me, and more than once I
dozed off. But I've got to applaud the progressive thinking behind the practice.

## Two Sweet Anecdotes

The funniest thing that happened while I was at Distru was during an engineering
team meeting, where one person was discussing a problem they were having with
cookies. Half the team thought he was talking about HTTP browser cookies, and
the other half thought he was talking about an edibles product in the database.
🤣

I had been working at Distru for about six months when my birthday came around.
There's a birthday Slackbot that reminds everyone. Whatever, that's a low bar.
But on the afternoon of my birthday, my doorbell rings, and there's a delivery
for me. The head of HR at Distru is a lovely woman from Barcelona who lives in
the US. She had used my address to find a local bakery – in my little Spanish
fishing village, mind you, where I guarantee you the baker doesn't know the
English word for "cake" – and had them bake and deliver me a birthday cake!
That's how Distru cares for their own.

<img
  src="/images/distru-birthday-cake.jpg"
  alt="Distru Birthday Cake"
  width={4032}
  height={3024}
/>

## Conclusion

No one at Distru asked me to write this. In fact, I'm about to ask them for
permission to post it. If you're reading this, they approved. Distru is an
amazing place to work, and I wanted to write down all these brilliant ideas to
suggest them to every subsequent employer I ever have.

If Distru sounds like the kind of place you'd like to work, I happen to know
that they could really use a frontend engineer right now.
[Apply here](https://www.distru.com/careers).

<img
  src="/images/distru-team.jpg"
  alt="Distru Team"
  width={1493}
  height={854}
/>

<caption>I'm gonna miss these beautiful faces. 💚 #muchlove</caption>


What I learned at Distru


The [Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern) is very
powerful, and those familiar with my work on
[Final Form](https://final-form.org) will know that I'm a fan. The RxJs docs
[define Observables](https://rxjs.dev/guide/observable) as:

> Observables are lazy Push collections of multiple values. They fill the
> missing spot in the following table:
>
> |      |   Single   |   Multiple   |
> | ---- | :--------: | :----------: |
> | Pull | `Function` |  `Iterator`  |
> | Push | `Promise`  | `Observable` |

They can represent streams of data or a series of events over time. I like to
use them to notify interested parties to changes of values (a.k.a. "state") over
time. My favorite kind of observable is called a Subject. Back to the
[RxJs docs](https://rxjs.dev/guide/subject):

> A Subject is like an Observable, but can multicast to many Observers. Subjects
> are like EventEmitters: they maintain a registry of many listeners.

I like to think of a Subject sort of like a physical object on a table.
Vizualize a Rubik's Cube on the desk in front of you. You can look at it and see
its position. If I go and move it, as soon as I do, _if you're still looking at
it_, you will immediately know its new position. But if you look away, I can
change it a lot and you won't know until you look back at it.

## The Perfect Exercise

Creating a Subject is a nice exercise to try when learning a new programming
language, as it requires:

- Passing functions as arguments
- Adding to a data structure of items
- Iterating through a data structure of items
- Removing items from a data structure

So what a great task to tackle in my online learning of ReScript!

---

Due to [recent musings](/blog/follow-observables), I'm going to use the verb
`listen()` rather than `subscribe()`.

---

## Types

The most important contract with observables is that the `listen()` function
returns a function to "unlisten", to unregister the listener. We're going to
define our `unlisten` type, our `listener` type, and a record type that keeps a
unique `id` along with our `listener`. This is to tell them apart for
unlistening.

```reason
type unlisten = () => unit
type listener<'value> = (. 'value) => unit
type listenerId<'value> = {id: int, listener: listener<'value>}
```

<caption>Remember that `unit` is like `void` in TypeScript</caption>

Now let's define the shape of our Subject...

Sometimes you can have a Subject and you want to know what its value is without
subscribing to all future updates – a "glance" at the Rubik's Cube, if you will.
One way to do this, following the strict Observer pattern, is to quickly listen
and unlisten. In JavaScript, that would look like:

```js
let value;
subject.listen((v) => (value = v))();
//                                ^^-- immediately unlisten
```

But that's gross, and the internal implementation always has the value anyway,
so I like to provide a simple `get()` function on my Subjects.

```reason
type subject<'value> = {
  listen: listener<'value> => unlisten,
  get: unit => 'value,
  set: 'value => unit,
}
```

Notice our Subject is strongly typed with a
[Type Parameter](https://rescript-lang.org/docs/manual/latest/type#type-parameter-aka-generic),
also known as a "Generic" in other languages. All type parameters are prefixed
with a `'`, which I learned the hard way,
[_is not a backtick_](https://twitter.com/erikras/status/1372857612442726402)!
`unit` is like `void` in TypeScript.

Okay, I think we're ready to attempt the...

## Implementation

A few things to notice for non-ReScript folks:

- `let` bindings, by default, are immutable (like `const` in JS/TS), but you can
  [make them mutable](https://rescript-lang.org/docs/manual/latest/mutation#mutate-let-binding)
  by surrounding them with `ref()`, and then access the value with
  `myRef.contents`. Any React devs will find this nearly equivalent to the
  `useRef()` and `myRef.current` API that React provides. There is some syntax
  sugar that means that `myRef.contents = 7` can be written as `myRef := 7`.

- The `open Js.Array2` line "opens that module" into my current scope so that I
  can use `forEach` rather than `Js.Array2.forEach`. It's a bit like
  `import com.initech.frontend.js.array.*;` in Java.

  - Why are there
    [`Js.Array`](https://rescript-lang.org/docs/manual/latest/api/js/array)
    _and_
    [`Js.Array2`](https://rescript-lang.org/docs/manual/latest/api/js/array-2)
    modules, with identical docs? ReScript is still a growing language that
    hasn't quite figured out what their API dogma is yet. If that's a
    dealbreaker for you, then avoid it.
    [Quoth the docs](https://rescript-lang.org/docs/manual/latest/api/js#jsxxx2-modules):

  - > ### Js.Xxx2 Modules
    >
    > Prefer `Js.Array2` over `Js.Array`, `Js.String2` over `Js.String`, etc.
    > The latters are old modules.

- `->ignore` is required because ReScript doesn't like you calling functions
  that return a value and you not doing anything with it, so you have to
  explicitly ignore the value.

```reason
export createSubject = (initial: 'value) => {
  open Js.Array2
  let value = ref(initial)
  let nextId = ref(0)
  let listeners: array<listenerId<'value>> = []
  {
    get: () => value.contents,
    set: (v: 'value) => {
      value := v
      // notify all listeners
      listeners->forEach(({listener}) => listener(. v))
    },
    listen: (listener: listener<'value>) => {
      let id = nextId.contents
      nextId := id + 1
      listeners->push({id: id, listener: listener})->ignore
      // notify listener of value on listen
      listener(. value.contents)
      () => {
        let index =
          listeners->reducei(
            (foundIndex, listener, index) =>
              listener.id === id ? index : foundIndex,
            -1,
          )
        if index >= 0 {
          listeners->removeFromInPlace(~pos=index)->ignore
        }
      }
    },
  }
}
```

When I implement this in TypeScript or JavaScript, I will often store the
listeners in a `Record<number, Listener>` rather than an array, to allow for
easier removal, but it doesn't look like ReScript supports that syntax. And I
wasn't paying enough attention on
[Big O Day](https://en.wikipedia.org/wiki/Big_O_notation) in Data Structures 201
to know which is better. ReScript also supports linked lists, which pleases
someone who still remembers what
[CAR and CDR](https://en.wikipedia.org/wiki/CAR_and_CDR) are, but they aren't
useful for this random access deletion needed for my Subject.

I couldn't find a "remove the item for the first time this predicate is true and
stop iterating" function, so rather than `filter`ing through the array (and
making the reference mutable), I chose to search for the `index` (which still
goes through the entire array) and then delete (mutating) with that.

Thanks for reading! Comments and suggestions via Twitter are welcome!


Creating an Observable Subject in ReScript


It's hard to state just how difficult it is to talk about state management; it
all depends on the context of the conversation. The more I have been thinking
about state machines, and learning about XState, the more I like the way XState
talks about "application state".

In the context (🙄) of state machines:

**state**: which of a finite number of states the machine is currently in. e.g.
`fetching`, `loaded`, `error`.

**context**: the environment in which events are taking place. This includes
which user is logged in, any data that has been loaded, and errors that have
been returned.

Notice how these are the same words that React uses for different things. The
state machine "context" is what you would put into a `useState()` hook. In
Redux, the state machine "context" would be in your store.

Let's build the simplest possible state machine, in my new favorite language,
[ReScript](https://rescript-lang.org):

## The Ubiquitous Counterexample

In ReScript, our states, represented by
[variants](https://rescript-lang.org/docs/manual/latest/variant), can have a
[payload](https://rescript-lang.org/docs/manual/latest/variant#constructor-arguments),
which is where we will place our context. In this case, our context is a simple
integer.

```reason
type state = Idle(int)
type event = Increment | Decrement | Reset

export let initial = Idle(0)

export let transition = (state:state, event:event) =>
  switch (state, event) {
    | (Idle(value), Increment) => Idle(value + 1)
    | (Idle(value), Decrement) => Idle(value - 1)
    | (Idle(_), Reset) => initial
  }
```

Notice that we are always returning to our only state, `Idle`, and our events
are only modifying our context.

<img
  src="/images/single-state-machine.png"
  width={888}
  height={730}
  alt="A single-state state machine"
/>
<caption>American Idle</caption>

What have we created here? A simple **_reducer_**. This is the equivalent, in
TypeScript, of:

```ts
export const initial = 0;
export function transition(
  state: number,
  event: "Increment" | "Decrement" | "Reset"
) {
  switch (event) {
    case "Increment":
      return state + 1;
    case "Decrement":
      return state - 1;
    case "Reset":
      return initial;
  }
}
```

It's the kind of thing that powers Redux or what you might give to a
`useReducer()` hook in React.

I can hear you rolling your eyes already.

### Yeah, so what?

Well, what if we wanted to temporarily disable our counter, so that the value
couldn't be changed? You could add another `disabled: boolean` to your reducer's
`state` value... But if you were implementing it as a state machine, you could
have your `Pause` event shift the machine into the `Paused` state, where it
would ignore the `Increment` and `Decrement` events.

```reason
type state = Idle(int) | Paused(int)
type event = Increment | Decrement | Reset | Pause | Unpause

export let initial = Idle(0)

export let transition = (. state:state, event:event) =>
  switch (state, event) {
    | (Idle(value), Increment) => Idle(value + 1)
    | (Idle(value), Decrement) => Idle(value - 1)
    | (Idle(_), Reset) => initial
    | (Idle(value), Pause) => Paused(value)
    | (Paused(value), Unpause) => Idle(value)
    | (Idle(_), Unpause)
    | (Paused(_), _) => state
  }
```

These are very, very trivially simple examples, but I think there may be a
significant difference "at scale" with a real application.


A reducer is a single-state state machine


After hearing my friend, [David 🎹](https://twitter.com/davidkpiano), go on and
on about [finite] state machines and the value they can provide to us as
frontend programmers, a few months ago, I was able to actually use his library,
[XState](https://xstate.js.org), in anger at work, and the result was nothing
short of glorious!

> It eliminates a whole class of bugs!

👆 This is a phrase that has come out of my mouth very often in the last couple
of years since being baptized into the Holy Church of TypeScript. I have spread
the Good Word far and wide, and even created a meme which I have used multiple
times on PRs with my team.

<s>1308736441753767937</s>

## ReScript

[ReScript](https://rescript-lang.org), the artist formerly known as BuckleScript
and Reason, takes "It eliminates a whole class of bugs" to the next level. Quoth
the docs:

> ReScript has **no** pitfalls, aka the type system is "sound" (the types will
> always be correct). e.g. If a type isn't marked as nullable, its value will
> never lie and let through some undefined value silently. **ReScript code has
> no null/undefined errors.**

Okay, you have my attention! I read through the docs
[one day](https://twitter.com/erikras/status/1370007991202758657) like it was a
_Jack Reacher_ novel, very excited to see the sort of tradeoffs ReScript was
making.

In my n00b experience so far, the interop edges where ReScript must consume –
moreso than provide – third party JavaScript libraries feels a bit awkward...at
least more awkward than modern 2021 TypeScript which has huge community support
(so the comparison is not really fair).

Since acquiring this itch, I've been looking for a simple example project to try
out my ReScript skills.

## Twitter's "Follow" Button

Last week, I noticed an interesting thing about the "Follow" button on Twitter's
webapp. Rather than having four states, `not-following`, `following`,
`not-following-hover`, and `following-hover`, it actually has _five_! There's a
special state when you've just clicked "Follow", but are still hovering over the
button.

<s>1372838015656136708</s>

**Perfect!** This is a job perfect for a state machine, and also tiny enough
that maybe I could implement it in ReScript!

At the time of this writing, there are virtually zero search results that come
back for "XState ReScript". There is one article about ReScript and state
machines called
[Modelling domain with state machines in ReasonML](https://dev.to/margaretkrutikova/modelling-domain-with-state-machines-in-reasonml-n29),
from almost a year ago by
[Margarita Krutikova](https://twitter.com/rita_krutikova), in which she mentions
XState, but codes in ~~ReasonML~~ ReScript. That is what I shall attempt to do,
as well. One could imagine a ReScript interop layer for XState existing
(ReXState? 🦖), but it doesn't seem to at the moment.

## "Follow" Button State Machine

I admit to usually rolling my eyes at the point of David 🎹's talks where he
recommends:

> Start with a sheet of paper or a whiteboard, and draw out the states you need.

"I can see the Matrix and visualize all the states just looking at the code", I
think smugly to myself. However, this time, darned if he wasn't right! I
struggled with considering all the interactions writing just code (plus, this
coding language is foreign to me), so I found great benefit in drawing up my
state machine by hand first. Of course I used
[Excalidraw](https://excalidraw.com/), not paper – I'm not a caveman!

<img
  src="/images/follow-button-state-chart.png"
  width={1480}
  height={801}
  alt="Follow Button Finite State Machine"
/>
<caption>
  The clicks without hovering are there for completeness (and maybe
  accessibility?).
</caption>

Notice that from `not-following-hover`, it's pretty hard to get to
`following-hover` (with red background and "Unfollow" text), when you would
think would be the next state; you have to:

1. Click
2. Mouse out
3. Mouse over again

## ReScript Implementation

### Types

Let's start with our types:

```reason
type state =
  | Following
  | FollowingHover
  | FollowingNeverMouseOut
  | NotFollowing
  | NotFollowingHover
type event = Click | MouseOver | MouseOut
type style = Highlight | Danger | Hover | None
```

The actual Twitter "Follow" button doesn't have a style for `NotFollowingHover`,
but I decided to improve on that and make a `Hover` style.

### `getText()`

What should the text of the button be in each state? Notice that you can "fall
through" just like you can with a `switch-case` statement in JavaScript if you
leave out the `break`.

```reason
@genType
let getText = (state: state) => {
  switch state {
  | NotFollowing
  | NotFollowingHover => "Follow"
  | FollowingHover => "Unfollow"
  | Following
  | FollowingNeverMouseOut => "Following"
  }
}
```

Notice the `@genType`. One fun fact that made me want to attempt adopting
ReScript is that: **_IT GENERATES TYPESCRIPT TYPES FOR YOU_!!!** 🤯

It's not the most beautiful TS ever, but it gives you the typings and then
defers the calls to the generated JavaScript. For example, here's an excerpt of
the TypeScript the code above generated:

```ts
// tslint:disable-next-line:no-var-requires
const followButtonBS = require("./followButton.bs");

// tslint:disable-next-line:interface-over-type-literal
export type state =
  | "Following"
  | "FollowingHover"
  | "NotFollowing"
  | "NotFollowingHover"
  | "FollowingNeverMouseOut";

// tslint:disable-next-line:interface-over-type-literal
export type event = "Click" | "MouseOver" | "MouseOut";

// tslint:disable-next-line:interface-over-type-literal
export type style = "Highlight" | "Danger" | "Hover" | "None";

export const getText: (state: state) => string = function (Arg1: any) {
  const result = followButtonBS.getText($$toRE161065015[Arg1]);
  return result;
};
```

However, more interesting, is the JavaScript that it generates. Check this out:

```js
function getText(state) {
  switch (state) {
    case /* FollowingHover */ 1:
      return "Unfollow";
    case /* NotFollowing */ 2:
    case /* NotFollowingHover */ 3:
      return "Follow";
    case /* Following */ 0:
    case /* FollowingNeverMouseOut */ 4:
      return "Following";
  }
}
```

All nicely documented so you can follow along.

### `getStyle()`

Now we declaratively define how the state relates to the style (think, "CSS
class") of the button.

```reason
@genType
let getStyle = (state: state) => {
  switch state {
  | FollowingHover => Danger
  | Following => Highlight
  | NotFollowing => None
  | NotFollowingHover
  | FollowingNeverMouseOut => Hover
  }
}
```

Pretty similar to `getText()`. Notice that the "fifth state", `FollowingHover`,
is special in both functions.

### The Machine

Here's where it gets fun! The machine is a simple mapping from state to state
via events. This is just the code that represents the arrows in the
drawing...nothing more.

```reason
@genType
let machine = (. state:state, event: event) =>
  switch state {
    | NotFollowing => switch (event) {
      | Click => Following
      | MouseOver => NotFollowingHover
      | MouseOut => state
    }
    | NotFollowingHover => switch event {
      | Click => FollowingNeverMouseOut
      | MouseOut => NotFollowing
      | MouseOver => state
    }
    | FollowingNeverMouseOut => switch event {
      | Click => NotFollowingHover
      | MouseOut => Following
      | MouseOver => state
    }
    | Following => switch event {
      | MouseOver => FollowingHover
      | Click => NotFollowing
      | MouseOut => state
    }
    | FollowingHover => switch event {
      | MouseOut => Following
      | Click => NotFollowingHover
      | MouseOver => state
    }
  }
```

...which compiles nicely – in milliseconds! – to this efficient JS code:

```js
function machine(state, $$event) {
  switch (state) {
    case /* Following */ 0:
      switch ($$event) {
        case /* Click */ 0:
          return /* NotFollowing */ 2;
        case /* MouseOver */ 1:
          return /* FollowingHover */ 1;
        case /* MouseOut */ 2:
          return state;
      }
    case /* FollowingHover */ 1:
      switch ($$event) {
        case /* Click */ 0:
          return /* NotFollowingHover */ 3;
        case /* MouseOver */ 1:
          return state;
        case /* MouseOut */ 2:
          return /* Following */ 0;
      }
    case /* NotFollowing */ 2:
      switch ($$event) {
        case /* Click */ 0:
          return /* Following */ 0;
        case /* MouseOver */ 1:
          return /* NotFollowingHover */ 3;
        case /* MouseOut */ 2:
          return state;
      }
    case /* NotFollowingHover */ 3:
      switch ($$event) {
        case /* Click */ 0:
          return /* FollowingNeverMouseOut */ 4;
        case /* MouseOver */ 1:
          return state;
        case /* MouseOut */ 2:
          return /* NotFollowing */ 2;
      }
    case /* FollowingNeverMouseOut */ 4:
      switch ($$event) {
        case /* Click */ 0:
          return /* NotFollowingHover */ 3;
        case /* MouseOver */ 1:
          return state;
        case /* MouseOut */ 2:
          return /* Following */ 0;
      }
  }
}
```

## Demo Time

The following button (pun intended) is written using the logic described above,
with the actual JavaScript compiled from ReScript.

<div style={{ textAlign: "center", marginTop: "1em" }}>
  <FsmFollowButton />
</div>

Notice how there are two states where it reads "Following", the one right after
you've clicked it, and the button is still gray, and the one after you've moused
away and the button is purple.

So concludes my first of what will hopefully be
[many posts about ReScript](/blog/categories/rescript). Feel free to follow me
on Twitter as I ask questions from people smarter than myself and get help
learning this promising language.


Finite State Machines in ReScript

With every new technology, we inevitably attempt to describe it with our
existing vocabulary that applies to the older technology. A viral video shot on
a mobile phone might be headlined with "[Phenomenon] caught on tape!",
podcasters talk about being "on the air", etc. etc. So it only made sense that
when the Blog (_née_ "Web Log") was introduced, if you wanted to get new
"articles" from it, you would "subscribe" to it, just like you would to a
newspaper or magazine. But when you "subscribe" to a newspaper or magazine, you
are paying money!

As of iOS 14.5, if you would like to subscribe to a podcast on Apple's Podcasts
app,
[you must tap "Follow"](https://9to5mac.com/2021/03/09/apple-adopting-the-word-follow-for-podcasts-as-users-associate-subscribe-with-paid-content/).
This seems reasonable. Over the course of the last decade, the social media
giants have more or less agreed that the verb for "I want to hear more from this
entity whenever it produces content" is "follow". While Facebook still
differentiates the mutually bidirectional relationship of "friend", for
unidirectional bondings, it agrees with Instagram, Twitter, TikTok, and now
Clubhouse, that the word is "follow". From what I can tell, YouTube is the only
remaining holdout on the Island of Subscribe.

The really interesting tidbit to come out of this news is that back in 2018,
[Tom Webster discovered](https://www.niemanlab.org/2018/08/podcastings-next-frontier-a-manifesto-for-growth-beyond-the-already-converted/)
that most people that don't listen to podcasts don't because they think they
aren't free!


> Now we are getting to one of the more dangerous perceptions — that podcasts
> cost money. This is a flat out misconception, but it’s one that _we_ created
> with our continual insistence that people “subscribe” to our show. With the
> exception of a YouTube channel, you pay for things you subscribe to —
> magazines, satellite radio, HBO, the fruit-of-the-month club. The listeners we
> have may understand that podcasts are largely free. But many of The [millions
> of Americans who do not listen to podcasts] do not.


How interesting!

This immediately resonated with me because a year or two ago, I wrote a talk to
discuss my JavaScript library [🏁 Final Form](https://final-form.org) at a
conference. I mentioned how what really set 🏁 Final Form apart from the
competition was the use of the
[Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern), which allows
the library consumer fine grained control over rerenders via _subscriptions_.
You can _subscribe_ to exactly which parts of form state you'd like to be
notified about when they change.

I sent my talk proposal off to be reviewed by a non-technical person who was
offering to broker a deal with the conference organizers to get my talk
accepted. She wrote me back and said, "I don't think they will accept your talk
if you're going to be hocking a paid subscription service." 🤯 The twGo meanings
of the word had never once occurred to me! In the same way that we took the old
magazine/newspaper "tell me when something is new" nomenclature for blogs and
podcasts, we had done the same thing with `Observable`s. I used the word
"subscribe" because
[RxJS did](https://rxjs.dev/api/index/class/Observable#subscribe-), and the
["pub-sub" pattern](https://en.wikipedia.org/wiki/Publish–subscribe_pattern)
long predates Rx.

This got me thinking... perhaps it's time to deprecate the word "subscribe" in
our code as well as in our social networks? I don't really love `follow()`, but
perhaps that's so ubiquitous in other realms that it's the way to go. The other
obvious words that occur to me are `listen()` and `observe()`, evoking our
senses of hearing and vision.

What do you think? Hit me up on Twitter to discuss... I'll be
\_\_\_\_\_\_\_\_ing [to] your tweets.

Should we follow Observables?


As we round the bend into the second half of this most exceptional year, 2020,
two things happened that affected me and my open source work:
[CodeFund](https://codefund.io) announced they were shutting down, and social
pressure forced [Tanner Linsley](https://github.com/tannerlinsley) and myself to
remove the [Scarf](https://scarf.sh) analytics service from our open source
libraries.

## Advertising

CodeFund has meant a lot to me over the years. I was an early adopter, and the
monthly revenue it generated – which has never been more than roughly equivalent
to what my dayjob pays me for a single day of work – was really motivating. When
I was 85% done with the MVP of [Final Form](https://final-form.org), I was
stalled for motivation, and seeing that I could potentially get some income from
having another popular library gave me the stamina to make it to the finish
line.

(That metaphor was not intentionally related to Final Form's logo, I swear.)

I still think that radio, television, the internet, social media, YouTube, and
podcasts have shown us that making something that people want, giving it to them
for free, but with ads, _is_ a viable strategy for a producer-consumer
relationship that works with how our brains make decisions. The eyes that peruse
the documentation pages for open source libraries are very valuable to
advertisers. Developers not only can influence decisions about which SaaS
solutions their employers adopt, but are also, generally, pretty well paid and
have disposable income to spend on gadgets and things.

In the future, I hope more companies like CodeFund spring up to offer themselves
as middlemen between OSS devs and advertisers; I think there's still money to be
conjured from this space. I think Microsoft, as the owner of both GitHub and
NPM, is uniquely positioned to make a difference in open source sustainability
via advertising.

## Analytics

Installing an analytics tracker in my open source library had never occurred to
me before Avi, from Scarf, approached me to talk about it. The way it works is
simple. Much like how this very webpage, totally unbeknownst to you and without
your consent, probably caused your computer to download half a dozen (or more)
little 1x1px gifs, allowing some unknown-to-you corporations to triangulate,
using only the HTTP headers of those requests, where you are, what device you're
on, and sometimes all the way down to your actually identity, including Scarf as
a dependency in my library caused a single HTTP request to fire off whenever
anyone ran `npm install` on a project that included my library as a dependency.
Scarf would then determine the location of the request, only to the resolution
of the country, and attempt to deduce if the IP address belonged to a
corporation, and then record the name of the corporation and the country,
_discarding the IP address itself_.

My initial reaction to this idea was similar to that of most developers I have
spoken to about it. Eww! Gross! That's creepy to have a library reporting to
some third party every time I run `npm install`. The implicit contract when I
run `npm install` is that I expect my computer to go fetch some metadata and
possibly published library code from NPM, and NPM only. But then Avi explained
that the long term goal of Scarf was to then approach these corporations to
request financial support, and it was a novel idea to the seemingly intractable
problem that this post is about, so I consented to give it a try.

The results that rolled in over the next few weeks were stunning. Microsoft,
Google, Amazon, and Apple were
[all using my library](https://final-form.org/users)! It was hugely validating
and motivating. ...but it also made more salient the fact that, between
[Github Sponsors](https://github.com/sponsors/erikras) and
[Open Collective](https://opencollective.com/final-form), the library was
receiving a grand total of just under $30/month in sponsorship.

In the end, I'm glad that briefly had Scarf enabled as a test of open source
analytics and get a feel for that avenue of attack on this problem, but, unlike
all the Silicon Valley behemouths that are gaining value from my library, I
cannot, in good faith, continue to force my consumers to give up any information
about themselves in exchange for using my library.

NPM _has_ all of these analytics, but does not share them. I think Microsoft, as
the owner of NPM, is uniquely positioned to make a difference in open source
sustainability via analytics.

## What is the value of Open Source?

For the purposes of this discussion, I'm going to ignore that, on most
platforms, most of the code all the way down to the kernel is open source. Let's
start at the web app level. You want to build a web application that can receive
Hypertext Transfer Protocol requests and return Hypertext Markup Language.
Personally, I'm old enough to remember when web applications were actual
compiled executables (or scripts) in the `/cgi-bin` directory that did exactly
that: listened to a port for HTTP requests and squirted out HTML. If you had to
start at that level every single time, double-checking the
[HTTP specs](https://www.w3.org/Protocols/), to design your web application,
you'd never get anywhere. The reason the web even exists is that it has been
collaborative from the beginning, with people sharing their code and having
others improve upon it, like Science in Academia.

If I want to build a single page app to track COVID-19 data, and building that
included designing a charting library from scratch, it'd never get done. But
there are a plethora of charting libraries out there that people have spent
many, many hours building and perfecting, just given to me...no strings
attached. And so, I can whip up my COVID-19 tracking app in a day or two! Am I
_stealing_ from the chart devs? No, of course not. They posted their code to the
public square and let anyone have it. Were I a thoughtful individual, I might be
so grateful for their effort that I toss them a $20 bill in thanks for saving me
200 hours of work.

Where it gets a bit more morally murky is if my virus tracking app starts making
$1M in monthly recurring revenue, and if the chart devs stopped maintaining
their library, I could lose $100K in revenue, and then another $50K in
development time to migrate to another library or try to build one in-house. The
incentives are out of whack. It should be in ViralCorp's best interest to make
sure that the chart devs are well compensated and not going to burn out or lose
interest.

In no other industry would such large corporations depend so heavily on single
individuals for no pay. Can you imagine a car manufacturer that gets an
important cog in the engine from a guy down the street who just really likes
making these cogs and leaving them out on this front porch in a "FREE, take as
many as you want!" box, and has no backup plan if the guy keels over or decides
to start making another thing? The accountants and shareholders would be
shouting "_OMFG RISK!!_" from the rooftops. And yet that is how the software
industry operates.

To me, the value of open source is in the time that it saves all of us to get an
app off the ground and working. That profitable corporations should give back is
a bit like corporations paying taxes because they built their business on the
roads the taxes pay for... oops, bad analogy...they don't pay taxes either!

## Donations are NOT the answer

This is the current model, and I don't even think this obvious fact warrants an
argument.

## The Spotify Model is NOT the answer

Some people suggest some system where you can pay $X every month to "some
arbitrator?", and then every library in your `package.json` with 75 dependencies
recieves $X/75 every month. This "by usage" model is how Spotify pays artists,
and
[how Egghead pays its content producers](https://howtoegghead.com/instructor/royalties/).
The problem is that this model incentivizes the tiny small utility, like the
infamous `leftpad`, and disincentives complex logic that actually saves devs
time.

Don't get me wrong; I _love_ that I will never have to think about how to parse
or format a query string ever again. I _could_ write that function in a few
minutes, but to write it properly with tests would be closer to an hour, and
even then I'm certain I'd miss some edge case that I know for sure that
`query-string` or `qs` has faced and addressed.

That said, a function that takes a string and converts it into an object does
not deserve the same compensation as a complex calendar widget. I challenge you
to find a website that doesn't contain some code from Sindre Sorhus. He deserves
$1M in annual recurring royalties, but not $1B.

So if we can't divvy it up evenly, how?

There's the rub. I guess it would have to be by which libraries the devs that
use them appreciate most. What I'm suggesting is that companies should provide
their devs with "gift vouchers" or some sort of credits for them to distribute
to open source libraries. Open Collective already supports vouchers, but I don't
see why the Github Sponsors program couldn't create "GitBucks" or something. I
think Microsoft, as the owner of NPM and GitHub, is uniquely positioned to make
a difference in open source sustainability via gift vouchers.

## Licensing is NOT the answer

A startup approached me recentlly, offering to handle all the recurring billing
and access restriction for me to have two versions of my library, one free and
open source, and a second one with more features that required a license to use.
I listened to their spiel intently and then pointed directly to the Emperor's
exposed genitals: "Who enforces this?" Their answer was, "Yeeeahhh, well....
it's up to the library consumer's internal legal team to remember that they have
to pay you, which is why we only expect about 2% of your so-called 'paying'
customers to _actually_ pay." Wow! Roll. On. The. Floor. Laughing!

If I switched from MIT to GPL tomorrow, 80% of people wouldn't notice, 19%
wouldn't care, and the remaining 1% would dump my library and migrate to another
free one with a slightly worse API and larger bundle size, and yet, _100% would
hate me_. Open Source Licensing is a joke, at least as it currently stands. I
_wonder_ if Microsoft, as the owner of NPM and GitHub, is not uniquely
positioned to make a difference in open source sustainability via licensing?

## Conclusion

It doesn't take
[a report from the Ford Foundation](https://www.fordfoundation.org/work/learning/research-reports/roads-and-bridges-the-unseen-labor-behind-our-digital-infrastructure/)
to see that the status quo is broken; it sucks for the little guy, and it sucks
for the corporate capitalist that's taking advantage of him even if they don't
know it yet. I don't really have a solid course of action to suggest. I guess
it's about awareness raising and asking your boss for some funding to go to
libraries you use; you can frame it like insurance: you hope there's never a
disaster, but you pay a little every month so that, if/when the disaster
happens, it's not so bad. If anyone can think of a corporation uniquely
positioned to help fix this problem, let me know.


Open Source Sustainability


I recently launched two podcasts, neither of which are technical. The first is
[Seek Justice](https://seekjustice.fm/), in which I engage my friend who is an
expert in the criminal justice system — a thing I know almost nothing about — in
thoughtful discussion about justice reform. The second is
[Happy Hour with Dennis and Erik](https://happyhour.fm/), in which my same
friend and I have an evening beverage, tell stories, and make each other laugh.

I’ve learned a lot about podcasting so far. One thing I already knew was that
both podcasts needed to have decent websites that could quickly get someone
listening, and make it as frictionless as possible to subscribe. I really liked
the design of [The Undefined Podcast](https://undefined.fm/), by fellow React
nerds Jared Palmer and Ken Wheeler, so I more or less plagiarized their design
layout entirely.

I knew I wanted the website to be static html with React rehydration, which
currently very fashionable in 2019, and I went back and forth looking at
blogging boilerplates from [Gatsby](https://www.gatsbyjs.org/) and
[React Static](https://react-static.js.org/), but what really sealed the deal
was learning of Shawn Wang’s very recent work on a
[React Static Podcast hosting framework](https://github.com/sw-yx/react-static-podcast-hosting),
which does things like generating an RSS feed with show notes directly from the
same markdown files that make up your episode post, using his hilariously named
[Podcats](https://github.com/sw-yx/podcats) library. Awesome!

> But there was one final piece of the puzzle that I needed: an in-page audio
> player.

Surveying the React audio player landscape, I found that the two leading
contenders are [Cassette](https://benwiley4000.github.io/cassette/styleguide)
and [React Audio Player](https://github.com/justinmc/react-audio-player).
Cassette is quite sophisticated, and does video as well, but it was playing my
MP3 files using the `<video>` tag, and required a stylesheet import. And React
Audio Player is just a simple wrapper around the HTML5 `<audio>` tag. I wanted
to replicate the embeddable players of some of the nice podcast hosting
services, like Simplecast or Anchor, with “album” art.

And for bonus points, I’d love it if I could use the `twitter:player` meta tag
to get my podcast episodes to play
[_directly in Twitter_](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/player-card.html).
My favorite podcast consumption app, [Overcast](https://overcast.fm/), has this
functionality on its website.

I also knew, since it’s 2019, I wanted to use Typescript and React Hooks. I
wasn’t really sure how to create a library with Typescript, but I do know of a
well maintained React Typescript library! So I more or less cloned the repo for
[Formik](https://github.com/jaredpalmer/formik) and removed all the code, but
kept the scaffolding. One side-effect of this was that I ended up learning
[Storybook](https://storybook.js.org/) for testing my component.

> Without further ado… Introducing…

## ⏯️ AudioCard

AudioCard is a responsive audio player for React designed to be compatible with
[Twitter Player Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/player-card.html).

```jsx
<AudioCard
  title="Ep 1. – What is Criminal Justice?"
  art="https://seekjustice.fm/art300.jpg"
  source="https://seekjustice.fm/media/001.mp3"
  skipBackSeconds={10}
  skipForwardSeconds={30}
/>
```

<caption>Example usage</caption>

This renders something that looks like:

<div style={{ textAlign: "center" }}>
  <img
    src="/images/audio-card-screenshot.jpg"
    alt="AudioCard screenshot"
    width={1000}
    height={313}
  />
</div>
<caption>It’s just a screenshot. Don’t click it! 😄</caption>

If you have a podcasting website that you build with React, and you either don’t
have an in-page player, or are dissatisfied with the one your podcast host has
given you to embed, or would like to add Twitter player card functionality, then
check it out.

### [Github Repo](https://github.com/erikras/audiocard)

### [Storybook Playground](https://erikras.github.io/audiocard/)

---

Here you can see it working with embedded tweets:

<s>1116441320636260352</s>

<s>1112983811401318401</s>

Thanks for reading. I hope this project can be of use to some people. ❤️

---

...and if you find either of my podcasts interesting, susbcribing, sharing and
⭐⭐⭐⭐⭐ iTunes ratings are the nicest gifts you can give a podcaster.


⏯️ AudioCard — The React audio player designed for podcasts and Twitter cards


I think we can all agree, the problem with all the current UI form libraries is
that the form state is controlled by a single entity, usually a corporation or
government, and there is very little accountability, and even less cryptographic
hashing. Wouldn’t it be better if the entire history of a user’s interaction
with a form were stored in a secure _decentralized_ place where both parties,
the user and the website, could trust was accurate and secured by strong one-way
cryptography?

> Now you can!

From [the guy](https://twitter.com/intent/follow?screen_name=erikras) that
thought putting form state in Redux was a good idea...

## 🔒 Blockchain Form

Now every single keypress, change of focus, and validation error of your form
fields can be stored on the Ethereum blockchain, which has an average
transaction speed of only 6 minutes per transaction. It’s the securest way ever
invented to store your form data. _**It’s 🔥 BLAZING 🔥 secure!**_

<div style={{ textAlign: "center" }}>
  <img
    src="/images/blockchain-animation.gif"
    alt="How Blockchain Form Works"
    width={629}
    height={329}
  />
</div>

<caption>Simple animation showing how 🔒 Blockchain Form works.</caption>

Want to modify field B when field A changes? No problem! Just write a quick and
easy [smart contract](https://en.wikipedia.org/wiki/Smart_contract) to modify
the other value! Just make sure you don’t make any mistakes in coding your smart
contract — and that your requirements will never change — because those
motherfuckers are **permanent**.

> But wait! There’s more!

<div style={{ textAlign: "center" }}>
  <img src="/images/but-wait.gif" alt="But wait!" width={391} height={295} />
</div>

Every time someone submits a form with 🔒 Blockchain Form, both the website and
the user will receive one free FormCoin™. _**OMGamification!!!**_ FormCoin™s are
a secure cryptocurrency that can be exchanged for goods and services if you can
convince someone that they’d rather have a virtual currency than whatever it is
they have that you want.

```bash
npm install blockchain-form
```

> [👉 Read the easy-to-follow, thorough documentation 👈](https://www.npmjs.com/package/blockchain-form)

Get started today! Because remember, kids: 🤔

> When your form data is distributed, no one is in control! ✊

<div style={{ textAlign: "center" }}>
  <img
    src="/images/spinning-coin.gif"
    alt="Spinning coin"
    width={240}
    height={240}
  />
</div>


Introducing… 🔒 Blockchain Form


---

Sometimes I wonder how many hours of frustration and billions of dollars has
been spent over the history of web development on making code that works in one
browser support another browser. With tools like Babel to transpile modern
language features down to an older language that works on ancient browsers,
young devs these days have no idea how good they have it.

It occurred to me that it kind of sucks that even the newer browsers have to
download the larger, older javascript versions of the bundles, laden with
polyfills. What if they didn't? What if you could build bundles for many
different browsers, and then had some Express middleware or Nginx rule that
would serve the right bundle depending on the client's User-Agent header? That
would be awesome!

I am a happily paying customer of [CloudFlare](https://www.cloudflare.com). I
love that all my javascript bundles are automatically cached on servers around
the world to make them load faster for my users.

## What if? 🤔

What if there was a service that would allow me to put a bundle of the most
bleeding edge, unminified, [Prettier](https://prettier.io)-ified, modern
JavaScript on my server, and have my brower's request be rerouted to a service
that would read my `User-Agent` header, and serve a minified, uglified,
transpiled bundle specifically tailored to my browser version, cached at my
local CDN node?

---

<div fontSize="7em" textAlign="center">
  🔥🔥🤯🔥🔥
</div>

---

## Introducing...

Nah, I'm just kidding. I haven't built this. I have too many other startup irons
already in the fire. I'm just throwing it out there as a "Wouldn't it be cool?"
product idea, but I promise I'll be a customer if _you_ build it.

It seems like it would be easiest for someone with the infrastructure in place
already, like _CloudFlare_ or _DigitalOcean_, to implement, but I bet a leaner
company could handle it with a moderate cloud storage plan.

## A few things to consider

- You'd need to have to be _very_ confident in your
  User-Agent-to-browser-feature mapping. You can't make many mistakes there.
- Ideally you would automatically detect what esoteric features, e.g. `Symbol`
  or `for...of`, are being used in the code to know if you need a polyfill or
  not, but you could also do feature checkboxes on a settings screen.
- You might also consider pulling the code from a Github branch. 🤷‍♀️
- Doing all bundle versions lazily (on first request) might not be the optimal
  solution; it would require some thinking and testing.
- You could maybe provide source maps to people that had an auth cookie for your
  website.
- Might be a good idea to have a "dev mode" that puts in some error tracking
  code, like _Rollbar_ or _New Relic_ do, to detect edge cases when your
  `User-Agent`-to-browser-feature mapping wasn't up to snuff.

## Conclusion

The minimum step in this direction would be an open source library for the
Express middleware with a detailed description of how to tailor existing build
tools to output browser-specific bundles - like
[this](https://gist.github.com/newyankeecodeshop/79f3e1348a09583faf62ed55b58d09d9),
but as a published lib. I'd also be grateful to learn of something like that. If
you know of one, or have just finished building it after being inspired by this
article,
[@ me on Twitter](https://twitter.com/intent/follow?screen_name=erikras).

And if you don't want to build this and get filthy rich, but think it might make
everyone's experience better on the web, maybe share this until it finds someone
who _does_ want to build it.

### Updates

- [@Raathigesh](https://twitter.com/Raathigesh) on Twitter
  [pointed me](https://twitter.com/Raathigesh/status/985827397030129664) towards
  [Polyfill.io](https://polyfill.io), a service from _The Financial Times_, that
  "reads the User-Agent header of each request and returns polyfills that are
  suitable for the requesting browser." And it's
  [open source](https://github.com/Financial-Times/polyfill-service), too! 👍


💡 IDEA: JavaScript Compatibility as a Service


Let’s start off with the problem. I manage a few popular form libraries, and I
often get the question:

> How can I use `redux-saga` or `redux-observable` to submit my form via a
> side-effect?

I have to answer, “Well… the form library is expecting the `onSubmit` function
to return a `Promise` to know when it is submitting, so...” At least with
[Redux Form](https://redux-form.com/), because all of its state was managed in
Redux, including whether or not the form was currently being submitted, it was
possible to let users _dispatch_ the `START_SUBMIT` and `STOP_SUBMIT` actions
themselves, rather than allowing Redux Form to manage that for them via the
`Promise`. But, if you
[take your form state out of Redux](/blog/final-form-announcement), you’re just
sort of screwed…

<div style={{ textAlign: "center" }}>
  <img
    src="/images/cry-emoji.png"
    alt="Crying emoji"
    width={120}
    height={120}
  />
</div>

### Until now.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/sweat-smile-emoji.png"
    alt="Sweat-Smile emoji"
    width={120}
    height={120}
  />
</div>

---

What if you had a way to create an asynchronous function that dispatched a START
action when it was called, and resolved or rejected the returned `Promise` when
either a `RESOLVE` or `REJECT` action was dispatched? That would totally solve
this problem. Right?

## 💥 React Redux Promise Listener 💥

The name is not the catchiest on NPM, but... I’ve just released
[React Redux Promise Listener](https://github.com/erikras/react-redux-promise-listener#react-redux-promise-listener),
a library that solves just this problem. The API looks something like this:

```jsx
<MakeAsyncFunction
  listener={promiseListener}
  start="START_ACTION_TYPE" // the type of action to dispatch when this function is called
  resolve="RESOLVE_ACTION_TYPE" // the type of action that will resolve the promise
  reject="REJECT_ACTION_TYPE" // the type of action that will reject the promise
>
  {(asyncFunc) => (
    <SomeFormLibrary onSubmit={asyncFunc}>
      ...
      <button type="submit">Submit</button>
    </SomeFormLibrary>
  )}
</MakeAsyncFunction>
```

The `promiseListener` comes from a piece of Redux middleware that must be
installed. By default, the values passed around are kept in `action.payload`,
but there are config options that let you read and write those from anywhere in
the actions.

## Conclusion

It should be a lot easier now to use async side-effect Redux libraries with
other async components, like routers, that were built on the assumption of
Promises being “how async is done” in Javascript.

❤️ Enjoy! ❤️


Getting a Promise from Redux Actions


Validation is probably the most complicated part of maintaining form state:
deciding _when_ to validate values, and _when_ and _where_ to display error
messages are important design decisions for making your forms as useable as
possible by the widest range of users.

Over a decade ago, the W3C set out some guidelines for what they thought the
next version of HTML should look like, and they called it HTML5. Part of that
standard included a system for validating form fields, both with native browser
rules, and also the ability to set a custom validation error on a field. These
days, the HTML5 validation standard is
[more-or-less supported by all web browsers](https://caniuse.com/#search=setCustomValidity).

## Why use HTML5 Validation?

I see three primary reasons why HTML5 form validation is a good thing to
incorporate into your application:

### Consistency of Design

By using the browser’s built-in mechanism for displaying form errors, your users
will be given a consistent UI for form errors across the entire internet (or at
least those very few sites that are advanced as yours will be when you start
using HTML5 form validation).

### Accessibility

This is the big one. Screen readers and other accessibility tools need a lot of
help understanding what exactly went wrong when a form submission fails. Some
screen readers will also let the user know a field is required when they enter
the field for the first time.

### Built-In Focus On Errors

As of last week, 🏁 Final Form supports [a plugin](/blog/focus-on-errors) to
focus on the first form field with an error. But with HTML5 Form Validation, it
comes for free from the browser! The browser stops the form submission and
focuses on the first error even before React is given the `onSubmit` event.

---

Introducing...

## [🏁 React Final Form HTML5 Validation](https://github.com/final-form/react-final-form-html5-validation)

I’ve written a drop-in replacement for the `Field` component in 🏁 React Final
Form that wraps the official `Field` component and adds the additional HTML5
validation onto it by doing three things:

- Deducing which DOM input corresponds to the field
- Injecting a special field-level validation function that reads from the
  `input.validity` DOM structure.
- Setting the HTML5 validation error with `input.setCustomValidity()` if there
  is an error from a specified field-level validation function.

The result is a two-way binding between the browser native HTML5 Validation, and
any field-level validation function specified to the component. The bindings are
two-way because any
[HTML5 contraint validation errors](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api)
will be added to the 🏁 Final Form state, and any _field-level_ validation
errors from 🏁 Final Form will be set into the HTML5 `validity.customError`
state. Unfortunately, this functionality is not compatible with 🏁 React Final
Form _record-level_ validation, so the two should not be mixed.

> “Why not add this functionality directly into the officially bundled `Field`
> component?”

Good question. The reason is that not everyone needs this functionality, and not
everyone is using 🏁 React Final Form with the DOM (e.g. some people use it with
React Native). Therefore it makes sense to make this a separate package. This
version of `Field` is a thin wrapper over the official `Field` component, and
the only `Field` API that this library uses/overrides is the field-level
validate prop, so even if you are using this library’s `Field` component, you
will still get improvements as features are added to the 🏁 React Final Form
library in the future.

> "How to use it?"

Well, first you change this:

```js
import { Field } from "react-final-form";
```

to this:

```js
import { Field } from "react-final-form-html5-validation";
```

All the regular API of `Field` stays the same, except that now you can pass in
props like `maxLength={25}` or `required` and, optionally, messages to display
when those rules are broken, e.g. `tooLong="Be more concise!"` or
`valueMissing="You need to answer this"` respectively. All of these prop names
are taken from the
[HTML5 Specification](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#the-constraint-validation-api),
so if you have staff already trained to the standards, they should pick it up
right away.

## What does it look like?

Well, the error UI look slightly different in every browser. No doubt the users
of each of these browsers will recognize this format of displaying error
messages.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-safari.gif"
    alt="HTML5 Validation in Safari"
    width={500}
    height={368}
  />
</div>

<caption>Safari</caption>

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-chrome.gif"
    alt="HTML5 Validation in Chrome"
    width={500}
    height={355}
  />
</div>

<caption>Chrome</caption>

<div style={{ textAlign: "center" }}>
  <img
    src="/images/html5-validation-firefox.gif"
    alt="HTML5 Validation in Firefox"
    width={500}
    height={357}
  />
</div>

<caption>Firefox</caption>

And here’s the obligatory sandbox embed for you to play with…

<iframe
  src="https://codesandbox.io/embed/14r018yjp4?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - HTML5 Validation Example"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

<caption>Go ahead! Play around with it!</caption>

## Conclusion

HTML5 Form Validation is yet another step towards making 🏁 Final Form the most
versatile, extensible form state management framework for React and beyond. Just
think how pleased your boss will be when you inform her that you’ve made all
your forms much more accessible! 😜

❤️ Thanks for reading. ❤️


🏁 React Final Form HTML5 Validation


The users of [🏁 React Final Form](https://react-final-form.org) continue to
suggest interesting use cases that challenge just what is possible from a form
library, and stimulate my imagination about possible solutions.

Today’s problem was:

> How can I update field B when field A changes from X to Y?

As the API stands currently, this could not be accomplished with
[🏁 Final Form Calculate](/blog/final-form-decorators), as it matters what the
_previous value_ was. We need a way to run some code to update another field
when one field changes, _without calling the update in `render()`_.

This requires a _**stateful**_ component to subscribe to changes to a field and
keep track of what the previous value was. It was pretty trivial to code up an
`OnChange` component that doesn’t render anything, but calls a callback when the
field value changes. This seemed so potentially useful that I went ahead and,
for completeness, created `OnBlur` and `OnFocus`, resulting in the library
[🏁 React Final Form Listeners](https://github.com/final-form/react-final-form-listeners#-react-final-form-listeners).

Having just discovered this idea, I have not yet decided how useful it is, or
whether or not it’s a good idea, but I’m sharing it to get feedback from others.
These components allow us to write “form rules” as non-rendering components,
like this:

```jsx
<WhenFieldChanges
  field="pickup"
  becomes={true}
  set="delivery.street"
  to={undefined}
/>
```

How do we write `WhenFieldChanges`? Well, we need a `Field` to get the
`onChange` function for the field we want to change, and then the OnChange
component to notify us when the field we want to listen to has changed value.

```jsx
const WhenFieldChanges = ({ field, becomes, set, to }) => (
  <Field name={set} subscription={{}}>
    {(
      // No subscription. We only use Field to get to the change function
      { input: { onChange } }
    ) => (
      <OnChange name={field}>
        {(value) => {
          if (value === becomes) {
            onChange(to);
          }
        }}
      </OnChange>
    )}
  </Field>
);
```

It’s important to notice that the function given to `OnChange` will _only_ be
called when the value changes, not on every render. Let’s see how it looks in
practice.

<iframe
  src="https://codesandbox.io/embed/52q597j2p?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Declarative Form Rules"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Conclusion

I’m still not convinced how useful this concept is, but it’s kind of fun to
explore the boundaries of what React allows us to do. Component composition, and
letting them keep state as the data cascades through them, is extremely
powerful.

As always, feedback welcome and encouraged! 🤔


Declarative Form Rules


Without a doubt, one of the most common questions I hear from people using my
forms libraries is:

> “How can I focus on the first field that has an error?”

Merely asking this question demonstrates a perceptive level of UX intelligence.
Clearly it’s an order of magnitude better to actually take a user to the problem
spot rather than just tell them “There’s an error up there somewhere. Scroll up
and try to find it!”

Here’s the answer I usually give:

> Well, that’s a tough problem, because calling focus() on an input requires
> having direct access to the DOM instance, and [form library] does not have
> that; all [form library] does is provide a `value` and `onChange` (and other
> listeners) to you, the developer that actually renders the `<input>`, and
> there is no good way for you, who may have a DOM reference to the input, to
> give that back to [form library] to allow [form library] to call focus() on
> the DOM element.

🙄 Just typing that practically put me to sleep. Yawn! 😴

<div style={{ textAlign: "center" }}>
  <img
    src="/images/sleepy-girl.gif"
    alt="Sleepy...zzzz"
    width={400}
    height={282}
  />
</div>

## 🤔 Can we do better?

It ocurred to me that, at least in DOM-land (sorry React Native folks!), we have
this ancient structure which, like Seinfeld — _“What’s the deal with render
props?!”_ — dates back to the early 1990’s, that modern web developers might not
know about. Did you know that _document.forms[0][0]_ will give you a reference
to the first input on the first form on your page? Or, that if you give your
form a name, e.g. `<form name="foo">`, that you can iterate through an
`HTMLCollection` of its inputs at `document.forms.foo`? 🤯

So, maybe a higher level form library can gain access to the input DOM elements,
as long as they are given the name value that matches the field name the form
library knows about?

---

🥁 🥁 🥁 Introducing, the alliterative…

## 🏁 Final Form Focus 🧐

[🏁 Final Form Focus 🧐](https://github.com/final-form/final-form-focus) is a
decorator for 🏁 Final Form. That means that you just import it and plug it in,
and it does all the rest. There is only one possible change in configuration: in
the interest of future proofing it and maybe allowing non-DOM platforms, like
React Native, to take advantage of it, you may provide a `getInputs()` function
that will give a list of “focusable inputs” (i.e. objects with a `name` property
and a `focus()` method) that correspond to the fields in your form. For those of
us in DOM land, you can omit that parameter and it will default to searching
through your `document.forms` structure and will "just work".

Whenever your form is submitted and the submission fails due to synchronous,
asynchronous, or submission validation errors, the first input on the page that
has a `name` prop that matches the path to an error will have `focus()` called
on it.

What does it look like? Well, if you’re using 🏁 React Final Form, you just add
the decorator like this:

```jsx

import React from 'react'
import { Form, Field } from 'react-final-form
import createDecorator from 'final-form-focus'

const focusOnErrors = createDecorator()
...
<Form
  onSubmit={submit}
  decorators={[ focusOnErrors ]} // <--------- 😎
  validate={validate}
  render={({ handleSubmit }) =>
    <form onSubmit={handleSubmit}>

      ... inputs here ...

    </form>
  }
/>
```

<caption>
  Step 1: Add the decorator to your form. Step 2: There is no Step 2!
</caption>

Let’s see it in action:

<iframe
  src="https://codesandbox.io/embed/6174kqr403?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Focus On First Error"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Vanilla JS Code

For those of you that have arrived to this post by googling “how to focus on the
input with the first validation error” (_Look, ma! I’m SEOing!!_), or looking to
add this functionality to your own form solution, this is all it takes:

```js
function focusOnFirstError(formName, hasError) {
  const form = document.forms[formName];
  for (let i = 0; i < form.length; i++) {
    if (hasError(form[i].name)) {
      form[i].focus();
      break;
    }
  }
}
```

<caption>
  `hasError()` is a predicate that returns truthy if a field has an error
</caption>

## Conclusion

Almost none of the web forms — or native forms, for that matter — I use on a
daily basis are sophisticated enough to bring focus to the first field with an
error, and thus introduce friction and frustration into the user experience.
Implementing “focus on first error” manually on every form is quite difficult,
e.g. keeping track of all the DOM refs, sorting them by which is first on the
page, and examining the error structure at submission to determine which one to
focus on.

But now, with 🏁 Final Form, there is a pluggable way to get that functionality
_**on every form you write**_.

❤️ Thanks for reading, and I look forward to your feedback! ❤️


Focus On Errors 🧐


Last week, I introduced
[the concept of mutators and array fields](/blog/final-form-arrays-mutators) to
🏁 Final Form. This week, I’d like to introduce the concept of decorators, and
show two examples of how powerful decorators and mutators can be, when combined
with the subscription-based paradigm of 🏁 Final Form.

## Decorators

The term comes from
[ye olde ancient forgotten land of OOP](https://en.wikipedia.org/wiki/Decorator_pattern).

> In object-oriented programming, the **decorator pattern** is a design pattern
> that allows behavior to be added to an individual object, either statically or
> dynamically, without affecting the behavior of other objects from the same
> class.

In terms of 🏁 Final Form, a decorator is just a function that takes the form
object, subscribes to it somehow, and returns a function that can be called to
“undecorate” (undo all of its subscriptions). This allows a decorator to listen
for changes and enact side-effects.

This simple pattern allowed me to write a
[45 line](https://github.com/final-form/final-form-calculate/blob/master/src/decorator.js)
— and those are post-[Prettier](https://prettier.io/) lines! — library to
perform realtime calculations between fields, not unlike a spreadsheet.

## [🏁 Final Form Calculate](https://github.com/final-form/final-form-calculate)

This library creates a 🏁 Final Form decorator based on a set of calculation
rules you provide. Here’s what it looks like:

```js
import { createForm } from "final-form";
import createDecorator from "final-form-calculate";

// Create Form
const form = createForm({ onSubmit });

// Create Decorator
const decorator = createDecorator(
  // Calculations:
  {
    field: "foo", // when the value of foo changes...
    updates: [
      {
        // ...set field "doubleFoo" to twice the value of foo
        doubleFoo: (fooValue, allValues) => fooValue * 2,
      },
    ],
  },
  {
    field: /items\[\d+\]/, // when a field matching this pattern changes...
    updates: {
      // ...sets field "total" to the sum of all items
      total: (itemValue, allValues) =>
        (allValues.items || []).reduce((sum, value) => sum + value, 0),
    },
  }
);

// Decorate form
const undecorate = decorator(form);

// Use form as normal
```

Here is a live demo showing what this looks like.

<iframe
  src="https://codesandbox.io/embed/oq52p6v96y?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁  React Final Form - Calculated Fields"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

Kind of a silly example, but there are valid use cases for this feature.

## [🏁 Final Form Set Field Data](https://github.com/final-form/final-form-set-field-data)

This library is a trivial little thing that provides a mutator that set any
arbitrary metadata for a field. You use it like this:

```js
import { createForm } from "final-form";
import setFieldData from "final-form-set-field-data";

// Create Form
const form = createForm({
  mutators: { setFieldData },
  onSubmit,
});

form.mutators.setFieldData("firstName", { awesome: true });

form.registerField(
  "firstName",
  (fieldState) => {
    const { awesome } = fieldState.data; // true
  },
  {
    // ...other subscription items
    data: true,
  }
);
```

Why would you want this? Well, for one, it allows you to create…..

## ⚠️ Field Warnings ⚠️

Way back in September of 2016 — in the horrible Dark Times before Prettier–a
user and prolific contributor to Redux-Form submitted
[a pull request](https://github.com/erikras/redux-form/pull/1780) for a feature
that never would have occurred to me. He needed fields to have what he called
“warnings”, which are just like synchronous validation errors, but they don’t
prevent submission. The way it was implemented was the way new features are
often added to software: by taking the existing validation pipeline and
duplicating all the methods and data structures to create a warning pipeline. It
worked perfectly, of course, but as is often the case with code duplication, it
created problems in the future, where someone fixed a bug in the error-handling
code, but not in the mirror image _warning_-handling code. And, of course, it
wasn’t long before someone came along and said, “You know, it’d be cool if we
could set, just, like, any arbitrary metadata on a field that we want, maaaan.”

With the ability to set arbitrary metadata into fields provided by
`final-form-set-field-data`, coupled with the subscription-based form state
paradigm of 🏁 Final Form, it becomes trivial to implement your own warning
system. Behold:

```jsx
const WarningEngine = ({ mutators: { setFieldData } }) => (
  // FormSpy lets you listen to any part of the form state you want.
  // If you provide an onChange prop, FormSpy will not render to the DOM.
  <FormSpy
    subscription={{ values: true }}
    onChange={({ values }) => {
      setFieldData("firstName", {
        warning: values.firstName ? undefined : "Recommended",
      });
      setFieldData("lastName", {
        warning: values.lastName ? undefined : "Recommended",
      });
    }}
  />
);
```

This component subscribes to the form values, so its onChange function gets
called every time they change, and it sets or removes a warning value in the
fields. All you have to do is include this somewhere inside your form — after
all the fields, so that they are registered when onChange is called the first
time.

Here it is in action: (tab through the fields to see the warnings appear)

<iframe
  src="https://codesandbox.io/embed/react-final-form-warnings-m5qwxpr6o8?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁  React Final Form - Warnings"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Conclusion

My goals with 🏁 Final Form is to be as lean and flexible as possible. Rather
than implementing a feature like field arrays or field warnings or calculated
fields directly in the core library, the core library allows ways for them to be
implemented outside, so that each application can only use the tools and pieces
it needs, and unforeseen use cases can be implemented for their specific project
and not for all. What interesting form features can you imagine building?

Happy coding, y’all. ❤️👩‍💻👨‍💻


🏁 Final Form — Decorators, Calculated Fields, and Warnings


After the release of [🏁 Final Form](https://final-form.org) and
[🏁 React Final Form](https://react-final-form.org)
[seven days ago](/blog/final-form-announcement), the very first feature that
[people asked for](https://github.com/erikras/react-final-form/issues/2) was
array fields / arrays of fields. I could have pretty easily implemented the
ability to push, pop, insert, etc. into array values as part of 🏁 Final Form,
but the reason that Redux Form got so gargantuan was from exactly this sort of
feature bloat, where many individuals added on their own pet feature, and
everyone that uses the library has to download _all of these features_ whether
they use them or not. How could I avoid this with 🏁 Final Form?

🏁 Final Form is already more or less feature complete (famous last words) as
far as editing flat or arbitrarily deep form values. But how could it be made
more _extensible_? Well, here’s what I came up with:

## Mutators

Mutators are functions that can be provided to 🏁 Final Form that are allowed to
mutate any part of the form state. You provide an object of mutators when you
call `createForm()`, and then they are exposed (bound to the form state) on the
form instance you get back, under `form.mutators.whatever()`. A mutator function
is given: the arguments it was called with, the form state, and a collection of
utility functions, like `getIn` and `setIn` to read and mutate arbitrarily deep
values, as well as `changeValue`, which updates a field value in the form state.
They can mutate the state however they wish, and then the form and field
subscribers that need to be notified will be notified.

What does this look like? Well, here’s a somewhat simplistic example that I
created when writing the unit tests:

```js
/** Clears a form value */
const clear = ([name], state, { changeValue }) => {
  changeValue(state, name, () => undefined)
}

/** Converts a form value to uppercase **/
const upper = ([name], state, { changeValue }) => {
  changeValue(state, name, value => value && value.toUpperCase())
}

const form = createForm({
  onSubmit,
  mutators: { clear, upper }
})

...

form.mutators.upper('foo')

...

form.mutators.clear('foo')
```

These are dumb examples, but what else does this allow? Well, for one, it
allows…..

## Field Arrays

Everyone doesn’t need to include the code for field arrays in their bundle, but
for those that do…..

Introducing:

## [🏁 Final Form Arrays](https://final-form.org/arrays)

This library
([687 bytes gzipped](https://bundlephobia.com/result?p=final-form-arrays@1.0.0))
contains mutators for performing array operations on form values in 🏁 Final
Form.

```js
import { createForm } from "final-form";
import arrayMutators from "final-form-arrays";

// Create Form
const form = createForm({
  mutators: {
    // potentially other mutators here
    ...arrayMutators,
  },
  onSubmit,
});

// push
form.mutators.push("customers", { firstName: "", lastName: "" });

// pop
const customer = form.mutators.pop("customers");
```

And of course it needs a companion:

## [🏁 React Final Form Arrays](https://github.com/final-form/react-final-form-arrays)

This library
([1.7 kB gzipped](https://bundlephobia.com/result?p=react-final-form-arrays@1.0.0))
consists of a `<FieldArray/>` component that very closely mimics the
functionality of
[Redux Form's `<FieldArray/>` component](https://redux-form.com/7.2.0/examples/fieldarrays/),
providing a fields object that is very array-like, with methods like `forEach`,
`map`, `push`, `pop`, `shift`, `splice`, etc. When you iterate through it, it
gives you the array-syntax strings (e.g. `foo[0]`) for the array value in your
form, ready to be used with the `<Field/>` component.

An example is worth 1,024 words…

<iframe
  src="https://codesandbox.io/embed/distracted-bhaskara-kx8qv67nk5?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: 500,
    border: 0,
    borderRadius: 4,
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Field Arrays"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

## Going Forward

I have some other ideas of functionality that can be provided by mutators, and
I’m sure you do, too. They could provide some very powerful features to your
forms in the future, without imposing feature bloat on applications that just
need a simple login and account form.

As always, feedback welcome! Thanks for reading. ❤️


🏁 Final Form – Field Arrays and Mutators


Two and a half years ago, about a month after
[Dan Abramov](https://overreacted.io)’s
[unforgettable launch](https://www.youtube.com/watch?v=xsSnOQynTHs) of Redux at
React Europe 2015, I released a humble little library that managed form state in
Redux, called [Redux-Form](https://redux-form.com), which, over the intervening
period, has grown quite substantially in popularity.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/redux-form-logo.png"
    width={300}
    height={181}
    alt="Redux Form Logo"
  />
</div>

As I write this in late 2017, Redux-Form has well over 8k stars on Github and
800k monthly downloads on NPM. By my recent calculations, based entirely on NPM
download figures, about half of React projects use Redux, and about a quarter of
those use Redux-Form, so about 11% of the _7 million_ projects that download
React, also download Redux-Form.

With this popularity and usage has come a deluge of feedback. Everyone has had a
slightly different use case and requested a slightly different behavior out of
Redux-Form. I have done my best to accommodate these, and merge in pull requests
for features that never would have occurred to me. I’ve done a lot of thinking
about forms and form state management.

## Problems with Redux-Form

Over these years, I have heard four primary complaints about Redux-Form. For
some reason, unlike with most complaints, I have most heard these in person at
conferences than on Twitter or Github or Stackoverflow. They are as follows, in
no particular order, but with growing emoji angst:

1. **🙁 It’s only for React?**

“Redux works with Angular, _et. al._, it’s too bad that Redux-Form doesn’t.”

2. **😢 I have to use Redux?**

“I really need a form solution, but my project isn’t using Redux.” Also,
everyone high up in the React community,
[_including both inventors of Redux_](https://github.com/reactjs/redux/issues/1287#issuecomment-175351978),
say that Redux is **_not_** the best place to keep form data. Oops.

3. **😖 I can’t use inline render functions?**

“Why does my input lose focus on first keypress?” Well, it’s because Redux has
asynchronously updated both your input and the surrounding form component
(because now `dirty === true`), and because your inline render function is !==
the previous one, blah blah blah 😢

4. **😭 It’s [over 26k gzipped?](https://bundlephobia.com/result?p=redux-form)
   No way!**

“Bundle size, bro. I’m watching my weight.”

## Premature Optimization

As `v5` of Redux-Form became very popular, the biggest complaint I had was that
it was slow. The theory behind why was that it was rerendering the _entire_ form
on every single keypress, since the `values` were provided to the form
component.

In early 2016, I solved this, by completely rewriting it from scratch, in what
became `v6`, creating a `<Field/>` component, which only updated when _its_
state changed, but did not update when another field’s state changed. This
complicated matters greatly, because now the whole `<Form/>` only received a few
select form-wide props, so the people that needed more information had to
`connect()` with a
[suite of selectors](https://redux-form.com/8.3.0/docs/api/selectors.md/) to get
other form state that was no longer provided by default.

It is entirely possible that the fear of rerendering the entire form drummed
into me by the complaints that lead to Redux-Form `v6` is unfounded, but,
whether or not the user notices it, it must be true that rerendering parts of
your tree needlessly _is_ going to be slower than avoiding it. I decided that my
next form solution should have built-in “only rerender if you need to” logic,
which most people will never need, but that will allow fine tuning of complex
forms.

## Solution

Some time in early 2017, I had the idea to create a “form state management
engine” that was totally independent of React or Redux, just pure javascript. My
first attempt was using Immutable.js, leveraging its power for fast “has this
whole tree changed?” checks. I was about halfway done with it in May, when I
mentioned it to fellow form library author,
[David Khourshid 🎹](https://twitter.com/davidkpiano). His reaction to involving
Immutable.js (15.3k gzipped) was negative, and it made me rethink my approach;
could I do it without the help of _any_ third party libraries? In August, during
an offline vacation, I began coding a dependency-free form management library.

## Going with the Flow

Normally I would build a library from the inside out, from the core to the
public API, but this time, I defined the API first, even writing some tests,
before implementing the core functionality. By strongly typing my API with
[Flow](https://flow.org/), I was able to catch bugs and ensure that the
internals were satisfying the contracts of the API. It felt a little like pair
programming with an annoying partner that was constantly saying, “Well actually,
that’s supposed to return a string!”, _but in a good way!_ Flow is awesome. 😍

## Clogged Namespace

Before I get to the _finish line_ of this post, I’d like to talk about the
process of choosing library names. I probably tried a hundred different names
involving the word “form” before finding one that was not taken already on NPM.
So many of them are rotten unused/unfinished/undocumented libraries that have
not been updated in a long time, and others are just empty namespace squatters —
a tactic I was forced to resort to in reserving the name of my library until
launch. I guess it was inevitable that a good NPM library name would become as
hard to acquire as a good .com domain, but it’s still frustrating.

Speaking of namespace..._Emojispace!_ After seeing the emoji branding succcesses
of popular 2017 libraries
[Styled Components 💅](https://www.styled-components.com/),
[Glamorous 💄](https://github.com/paypal/glamorous), and
[Downshift 🏎️](https://github.com/paypal/downshift), I decided that my library
needed an emoji to go with it. I have been very nervous that someone might steal
the one I chose (months ago) before launch, which has been very motivating!

Okay, now on to the announcement…..

<div style={{ textAlign: "center" }}>
  <img
    src="/images/final-form-banner.png"
    width={700}
    height={178}
    alt="Final Form Banner"
  />
</div>

## 🏁 Final Form

Today I am launching a new form library, called
[🏁 Final Form](https://final-form.org/). It’s based on the
[Observer pattern](https://en.wikipedia.org/wiki/Observer_pattern), so observers
can subscribe to receive updates for either form or field state changes. Each
observer must explicitly define _which_ parts of the state they want to be
notified about, and they will _only_ be called when the parts they have
subscribed to have been changed.

It has **zero** dependencies, is framework agnostic, and weighs in at 💥
**3.5k** gzipped 💥.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/react-final-form-banner.png"
    width={700}
    height={178}
    alt="React Final Form Banner"
  />
</div>

## 🏁 React Final Form

Of course it had to come with a companion library,
[🏁 React Final Form](https://final-form.org/react), which is a thin wrapper
around 🏁 Final Form that allows it to be used in React. And when I say thin… it
weighs in at 💥 **2.2k** gzipped 💥, for a combined weight of **5.7k** gzipped.
It has no dependencies, and only two peer dependencies: 🏁 Final Form and
React…..as the name would suggest 🙄.

## Problems with Redux-Form: ✅ Solved!

1. **🙂 Is it only for React?**

Nope! There’s nothing stopping anyone from implementing a 🏁 Final Form wrapper
in Angular, Ember, Vue, Preact, Elm, ReasonML, TheNextHotness™, etc.

2. **😊 Do I have to use Redux?**

Nope! State is canonically kept inside the 🏁 Final Form instance, and the React
components know when to rerender by calling `setState()` when they are notified
of a state change.

3. **😀 Can I use inline render functions?**

Of course you can! It’s almost 2018, for Pete Hunt’s sake! And to paraphrase a
prominant thoughtleader of the React community:

> “OMG!! Render functions! RENDER FUNCTION ALL THE THINGS!!!11one11"
>
> –– Michael Jackson

Both the `<Form/>` and `<Field/>` components use the three ways of rendering
that I have humbly stolen from the awesome rival library,
[Formik](https://github.com/jaredpalmer/formik#formik-render-methods), by
[Jared Palmer](https://twitter.com/jaredpalmer). Brilliant idea. You can either
pass a component, a render prop, or a render function to the children prop
([see docs](https://final-form.org/docs/react-final-form/types/FormProps#render)).

4. **😍 It’s only 5.7k gzipped? 21% the size of Redux-Form? AWESOME!**

Lean and mean. 😎

## What does it look like?

People familiar with the Redux-Form syntax should feel right at home, in fact
many custom component libraries that have been adapted for Redux-Form should
Just Work™ in 🏁 React Final Form. I will eventually write a Migration Guide,
but I haven’t gotten around to that yet.

August 2019 Update:
[Migration Guide!](https://final-form.org/docs/react-final-form/migration/redux-form)

<iframe
  src="https://codesandbox.io/embed/ww40y2m595?fontsize=14&hidenavigation=1&theme=dark"
  style={{
    width: "100%",
    height: "500px",
    border: 0,
    borderRadius: "4px",
    overflow: "hidden",
  }}
  title="🏁 React Final Form - Simple Example"
  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
  sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
></iframe>

<caption>Simple Example — No custom inputs</caption>

## Roadmap

🏁 Final Form is not yet up to feature parity with Redux-Form. For example, at
launch, it’s missing the concept of `<FieldArray/>` to edit an array of values
(**EDIT:** `<FieldArray/>` functionality
[released 7 days after this post](https://erikras.com/blog/final-form-arrays-and-mutators)
and `<Fields/>` to edit several fields in a single component. Nor does it have
some of the more esoteric features such as `autofill`. I plan on being a little
more willing to say, “No, I will not implement your specific feature,” with this
library, to minimize its complexity and surface area. I suspect that most edge
cases that previously required a new Redux action could be managed within React
state.

I very much look forward to working with others who want to wrap 🏁 Final Form
into another view framework, or even other implementations of 🏁React Final
Form. One suggestion: get in early if you want to be the dominant library (see
first paragraph).

## Conclusion

I cannot wait to get feedback from the community; I have learned so much from
you all in my years with Redux Form. ❤️

I do plan on continuing to maintain Redux Form. If you’ve built a huge
enterprise application on top of Redux Form, don’t worry; I’m not going
anywhere. But maybe you could try out 🏁 Final Form on the next form page you
build?

🙏 Thanks for reading. Go install it, star it, and give it a try! 🎉


🏁 Final Form – Announcement


There are times, when writing a large scale React application in which one
component needs to send a message to another component that it is not a direct
descendent or ancestor of, a cousin component, if you will. Two examples that
spring to mind are:

1. Needing to apply focus to a particular DOM node, which requires a ref to the
   actual DOM node.
2. Needing to make some AJAX call, e.g. submitting a form, using information the
   receiving component has in its props.

Luckily, if you are writing a large enough React application, you are probably
already using some sort of global state management, such as Redux. That’s great,
so you have a common state that both components can read from and write to, but
how does that help you pass a message? That’s where the world of international
espionage comes in…

Draw the curtain and take a seat, Mr. Bond.

To quote Wikipedia:

> A **dead drop** or **dead letter** box is a method of espionage tradecraft
> used to pass items or information between two individuals (e.g., a case
> officer and agent, or two agents) using a secret location, thus not requiring
> them to meet directly and thereby maintaining operational security. The method
> stands in contrast to the live drop, so-called because two persons meet to
> exchange items or information.

<div style={{ textAlign: "center" }}>
  <img src="/images/booksafe.jpg" width={590} height={443} alt="Book Safe" />
</div>

<caption>
  Image from{" "}
  <a href="http://chadchandler.com/diy-book-safe/" target="_blank">
    Chad Chandler
  </a>
</caption>

You already see where this is going, don’t you? The sending component needs to
dispatch an action that will set some slice of the state that the receiving
component is listening to. The flow goes like this:

1. User interacts with **Sender**
2. **Sender** dispatches an action to modifiy `state.deaddrop` to `true` or to
   any value that it wants to pass with the message.
3. **Receiver** has `mapStateToProps` with a selector for `state.deaddrop`, and
   thus gets rerendered with a new prop.
4. **Receiver** initiates whatever action is required.

It is important to note here that the flow does not _need_ to begin with a user
interaction. With the rise of asynchronous middleware like `redux-saga` and
`redux-observable`, the ability to trigger any code on a component anywhere is
very useful.

<div style={{ textAlign: "center" }}>
  <img
    src="/images/redux-dead-drop-logo.jpg"
    width={308}
    height={311}
    alt="Redux Dead Drop Logo"
  />
</div>

<caption>redux-dead-drop logo</caption>

## Implementation

I briefly considered writing a `redux-dead-drop` library, even going so far as
“designing” a logo, with its own higher order reducer to enable this
functionality on any reducer and a HOC to connect any component the dead drop
location on the reducer, and even have it call an instance method on its wrapped
component. I'm still reasonably certain that it would be possible to write, but
the design pattern is so simple that it takes hardly any effort to implement it
on any existing reducer, so I rejected abstraction for abstraction's sake.

If you would like to try and implement such a library, help yourself to the name
and logo.

As in the world of covert government agents, is important that the Receiver
component clear out the dead drop once the message has been received.

I have used this pattern in my [`redux-form`](https://redux-form.com) library to
enable the triggering of a form submission via the dispatch of an action. This
allows the form component to know about how it needs to be submitted and
validated, but also allows any actor in the entire application to trigger the
submission.

This post will self destruct in 5…. 4…. 3….


Redux Dead Drop


With the rise of Higher Order Component composition in the React community,
there are a plethora of libraries, such as my own
[`redux-form`](https://redux-form.com), that will add functionality to your
application by decorating your component and wrapping it in a HOC.

What you end up with is a component structure like this, where you control the
yellow components, `MyContainer` and `MyWrappedComponent`, but you have no
control over the red code, LibraryHOC.

<img
  src="/images/wrapped-hoc.png"
  alt="Wrapped Components Diagram"
  width={1000}
  height={496}
/>

Most such libraries are polite enough to pass through any props that they do not
use as parameters down to your wrapped component, but sometimes they will not
provide a way, e.g. getWrappedInstance, to access instance methods on your
wrapped component.

What can you do? How can you get through this barrier?

## Concrete Example

Let’s lay out a concrete example. Your MyWrappedComponent has instance methods
of load(), save(), and clear(), and you need buttons in your MyContainer to be
able to call these.

```jsx
// MyContainer.js
import React, { Component } from "react";
import MyWrappedComponent from "./MyWrappedComponent";

export default class MyContainer extends Component {
  constructor() {
    // bind handlers
    this.handleLoad = this.handleLoad.bind(this);
    this.handleSave = this.handleSave.bind(this);
    this.handleClear = this.handleClear.bind(this);
  }

  handleLoad() {
    // somehow call load() on MyWrappedComponent
  }

  handleSave() {
    // somehow call save() on MyWrappedComponent
  }

  handleClear() {
    // somehow call clear() on MyWrappedComponent
  }

  render() {
    return (
      <div>
        <button onClick={this.handleLoad}>Load</button>
        <button onClick={this.handleSave}>Save</button>
        <button onClick={this.handleClear}>Clear</button>
        <MyWrappedComponent />
      </div>
    );
  }
}
```

```jsx
// MyWrappedComponent.js
import React, { Component } from "react";
import { hocLibrary } from "some-hoc-library";

@hocLibrary({ config: "parameters" })
export default class MyWrappedComponent extends Component {
  load() {
    // load something
  }

  save() {
    // save something
  }

  clear() {
    // clear something
  }

  render() {
    return <div>Gorgeous UI</div>;
  }
}
```

How can MyContainer drill through the HOC to call methods on
`MyWrappedComponent`?

<div style={{ textAlign: "center" }}>
  <img
    src="/images/drill.gif"
    alt="Wrapped Components Diagram"
    width={362}
    height={360}
  />
</div>

<caption>This HOC is tough!</caption>

## Callback Drill

Because our HOC allows us to pass props down through it, we can pass a callback
that will give our container component references to the wrapped component’s
instance methods.

Let’s see that in action. When the inner `MyWrappedComponent` is going to be
mounted, it sends up the API that it wants to expose to `MyContainer`.

```jsx
// MyContainer.js
import React, { Component } from "react";
import MyWrappedComponent from "./MyWrappedComponent";

export default class MyContainer extends Component {
  constructor() {
    // bind handlers
    this.handleCallback = this.handleCallback.bind(this);
  }

  handleCallback(load, save, clear) {
    // save instance methods from MyWrappedComponent to this
    this.handleLoad = load;
    this.handleSave = save;
    this.handleClear = clear;
  }

  render() {
    return (
      <div>
        <button onClick={this.handleLoad}>Load</button>
        <button onClick={this.handleSave}>Save</button>
        <button onClick={this.handleClear}>Clear</button>
        <MyWrappedComponent methodCallback={this.handleCallback} />
      </div>
    );
  }
}
```

```jsx
// MyWrappedComponent.js
import React, { Component } from "react";
import { hocLibrary } from "some-hoc-library";

@hocLibrary({ config: "parameters" })
export default class MyWrappedComponent extends Component {
  componentWillMount() {
    this.props.methodCallback(
      this.load.bind(this),
      this.save.bind(this),
      this.clear.bind(this)
    );
  }

  load() {
    // load something
  }

  save() {
    // save something
  }

  clear() {
    // clear something
  }

  render() {
    return <div>Gorgeous UI</div>;
  }
}
```

## Conclusion

It is a little messy, but breaking through barriers often is. I have used this
pattern on several occasions, and it works well. One important side note: If
your wrapped component might be unmounted while your container remains, to
prevent a memory leak, you should “unregister” the instance methods via another
callback in `componentWillUnmount()`.

Happy coding!


Coding

Posted in Coding