
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.


ReScript

Posted in ReScript