Coding For Complexity

## Writing Good Code

While the details of writing good code are highly subjective, a good basic rule is to try and optimize your
implementations for *correctness* and *clarity*.

The code needs to accomplish the task for which it was written, and it needs to be done in a way that is
straightforward, so that it can be effectively refactored, shared and extended.

---

### It has been said in the programming community that:

> Shared mutable state is the root of all evil.

If that's the case, then the application state we write, refactor, and share with other programmers every day makes
myself and most other developers very evil people.

---

### How many states does this code have?

```javascript
if (enabled) {

} else {

}
```

---

### How about this code?

``` javascript
if (enabled && !eligible) {

} else if (eligible) {

}
```

---

## Transitioning to state machines

Without a structured approach to iterating the states our code can be in it can be very difficult to make sure that you
have all of your bases covered.

![state-machine](/images/tech/state-machine.png)

While combinations of conditionals create inexhaustive, implicit applications states, state machines require explicit and comprehensive
definitions of all the application states and valid transitions between them in a system.

---

## Our use case

Our team's first state machine used the [javascript state
machine](https://github.com/jakesgordon/javascript-state-machine) (JSM) library to define our application's
authentication process.

## Advantages

1. The diagrams of our authentication state machine generated by the library helped us better document and reason about
our implementation.
2. Dividing the process into a series of states and transitions led to clearer, more organized code.
3. State machines have their own data store, allowing us to encapsulate authentication details within our state machine
instead of our global Redux store.

---

## Initial implementation

Our state machine configurations looked something like this:

```javascript
const auth = new StateMachine({
  init: 'UNAUTHENTICATED',
  data: {},
  states: {
    AUTHENTICATED: { name: 'AUTHENTICATED' },
    UNAUTHENTICATED: { name: 'UNAUTHENTICATED' },
    SIGN_IN: { name: 'SIGN_IN' },
    REGISTER: { name: 'REGISTER' },
    ...
  },
  transitions: [
    { name: 'signout' from: 'AUTHENTICATED', to: 'UNAUTHENTICATED' },
    { name: 'signin' from: 'SIGN_IN', to: 'AUTHENTICATED' },
    ...
  ],
  methods: {
    onEnterAuthenticated: () => doX(),
    onEnterSignIn: () => showSignInScreen(),
    ...
  }
});
auth.transition('signin');
```

---

### Issues

* **State explosion**: Whenever we add a new dimension to the system, we get exponentially more states.
Managing the state of a user being authenticated vs unauthenticated becomes four potential states when we add the
notions of backgrounded vs foregrounded:

1. Authenticated/Foregrounded
2. Unauthenticated/Backgrounded
3. Authenticated/Backgrounded
4. Unauthenticated/Backgrounded

* **Poor separation of concerns**: All of the authentication logic is in a single big state machine. The biometrics
logic is co-located with the logic for the sign-in and deep-linking states and overall the authentication state machine
had too many responsibilities.

* **Big graphs and lines everywhere**: Our purpose for using state machines was to make it easier to reason about and
organize complex systems. Looking at a diagram with 10 states and a spider web of transitions doesn't help much to lower
that cognitive burden.

---

### Enter statecharts

statecharts are a layer on top of state machines that enhance the core concept of a graph-based definition of system
states with additional features and patterns for managing complexity.

---

### A Trusted Model

> When NASA used the Statechart Autocoder to build the software for the Mars Science Laboratory (the Curiosity Rover),
one of the reported benefits of using Statecharts was that “it forced developers to consider off nominal scenarios”.

Whether you call them bugs, features, or off nominal scenarios, statecharts can help developers identify edge cases and
write clearer state machine implementations.

Read about the original formalization here: [public
paper](http://www.inf.ed.ac.uk/teaching/courses/seoc/2005_2006/resources/statecharts.pdf)

---

### Core terminology

* **states**: Either atomic nodes corresponding to a single state or compound nodes consisting of substates.
* **events**: The triggers for transitions from one state to another.
* **actions**: Synchronous side-effects performed on transitioning, entering or exiting a state.
* **activities**: Asynchronous side-effects similar to actions, but which take a period of time to complete.

---

### Hierarchical states

statecharts address the problem of poor-encapsulation by supporting hierarchies of states.

---

### Parallel states

To address the state explosion issue, statecharts support parallel states. A parallel state node is in all of its child
states at the same time.

A system of boolean conditions like *authenticated/unauthenticated* and *foregrounded/backgrounded* will now grow
linearly as opposed to exponentially and can better represent the state of the system, since a user can be both
authenticated and backgrounded simultaneously.

---

### Chart visualizations

One of the biggest advantages of the statechart model is its translation into a clear and formalized visual statechart
diagram:

![state-machine-example](/images/tech/xstate-example.png)

The diagrams follows the W3C statechart XML (SCXML) implementation and can clearly illustrate every part of a state
machine configuration including parallel and hierarchical states.

---

### statecharts in action: xstate

xstate is a JavaScript implementation of the statechart model. It describes itself as:

> A library for creating, interpreting, and executing finite state machines and statecharts, as well as managing
invocations of those machines as **actors**.

xstate implements the statechart model with all of its core feature specifications:

* Guarded transitions
* Actions (entry, exit, transition)
* Activities
* Extended state (context)
* Orthogonal (parallel) states
* Hierarchical (nested) states
* State history

---

### Actor model

> The actor model is a model of concurrent computation that treats "actors" as the universal primitives of a system, with each actor to perform three core functions:

* Receive messages from other actors
* Send messages to other actors
* Do something with the messages it received (its behavior), such as:
* change its local state
* send messages to other actors
* spawn new actors

---

### Modeling a Button

```javascript
const Button = ({
  onPress,
  enabled,
  isLoading,
}) => (
  <div
    className={css(getContainerStyle(enabled).container)}
    onPress={() => onPress()}
    disabled={!enabled || !onPress || isLoading}
  >
    { isLoading ? 'Loading...' : 'Submit' }
  </div>
);
```

The button component has 3 inputs:

1. **onPress**: Controls what happens when it's clicked.
2. **enabled**: Manually override the enabled/disabled state of the button.
3. **isLoading**: Choose whether the button should display a loading state.

It consumes these inputs to determine which one of the three mutually exclusive UI states to display: **loading**,
**enabled** or **disabled**.

---

### Edge cases

1. The button can become loading at the same time it is disabled.
2. The button can become disabled at the same time it is loading.
3. The style of the button can be changed at any time, even if loading or unhandled.

---

Now let's compare this to an explicit state machine model using xstate. We'll start with the state machine definition:

```javascript
const transitions = [
  {
    target: "#button.enabled",
    cond: (context, event) => !event.isLoading && event.onPress && event.enabled
  },
  {
    target: "#button.disabled.loading",
    cond: (context, event) => event.isLoading
  },
  {
    target: "#button.disabled.manual",
    cond: (context, event) => !event.enabled
  },
  {
    target: "#button.disabled.unhandled",
    cond: (context, event) => !event.onPress
  }
];
```

---

```javascript
const ButtonMachine = Machine({
  id: "button",
  initial: "enabled",
  states: {
    enabled: {
      on: { UPDATE: transitions }
    },
    disabled: {
      id: "disabled",
      initial: "init",
      states: {
        init: {},
        loading: {},
        manual: {},
        unhandled: {}
      },
      on: { UPDATE: transitions }
    }
  }
});

const { initialState } = ButtonMachine;

console.log(initialState.value); // => 'enabled'

const nextState = ButtonMachine.transition(
  initialState, 'UPDATE', { isLoading: true }
);
console.log(nextState.value); // => disabled.loading
```

---

## Transition API

The transition API is a pure function which takes an initial state and an event and returns the new state of the system.
While a state machine with a pure `.transition()` function is useful for flexibility, purity, and testability, in order
for it to have any use in a real-life application, something needs to:

* Keep track of the current state, and persist it
* Execute side-effects
* Handle delayed transitions and events
* Communicate with external services

---

## Interpreter

An **interpreter** is responsible for interpreting the state machine/statechart and doing all of the above - that is,
parsing and executing it in a runtime environment. An interpreted, running instance of a statechart is called a
**service**.

---

### useMachine API

The `useMachine` API from `@xstate/react` interprets the given state machine and starts it as a service:

```javascript
import { interpret } from 'xstate'
import { useRef, useState } from 'react';

export const useMachine = stateMachine => {
  const [state, setState] = useState(stateMachine.initialState);
  const ref = useRef(null);

if (ref.current === null) {
    ref.current = interpret(stateMachine);
  }
  useEffect(() => {
    if (!ref.current) {
      return;
    }

ref.current.subscribe(setState);
    ref.current.start();

return () => {
      ref.current!.stop();
      ref.current = null;
    };
  }, [stateMachine]);
}
```
---

## xstate Button

```javascript
const Button = ({
  onPress,
  enabled,
  isLoading,
}) => {
  const [current, send] = useMachine(ButtonMachine);
  const disabledState = _.get(current, 'value.disabled');
  const isEnabled = _.get(current, 'value') === enabled;

useEffect(() => {
    send("UPDATE", { onPress, enabled, isLoading });
  }, [enabled, isLoading, send, onPress])

return (
    <div
      className={css(getContainerStyle(isEnabled).container)}
      onClick={() => onPress()}
      disabled={!!disabledState}
    >
      {disabledState === "loading" ? "Loading..." : "Submit"}
    </div>
  );
}
```

---

### Implementation advantages

This explicit state machine has three main benefits over our first implementation:

1. The button can now only be in one state at a time (`enabled`, `disabled.loading`, `disabled.manual` or
`disabled.unhandled`)
2. There is a priority to its states: If it is in the loading state and it receives a new manual `enabled=false` prop
change,
it will not transition from the loading state.
3. The state machine can be visualized according to the statechart specification.

---

### Xstate button

Here is a diagram of our button state machine:

![xstate button](/images/tech/xstate-button.png)

---

## Visualization advantages

The ability to visualize the states of a UI component or experience can benefit the entire team.

* Engineers can refer to self-documented implementations while working with each other's code.
* Design and QA can look at the diagrams to assert their expectations of the system and uncover any unexpected
scenarios.
* Product managers can even use them to follow user journeys and ensure that product requirements have been met.

---

## Modeling Flows

statecharts are also useful tools for managing complex flows. For our development focusing on financial products, an
example of such a flow could be an application for a new bank account.

This financial product will consist of a number of screens the user goes through to enter their personal information
required for the application:

* name
* date of birth
* SSN
* address

---

```javascript
import { Machine, assign } from 'xstate';

const BankApplicationMachine = Machine(
  {
    initial: 'NAME',
    context: {
      name: null,
      dateOfBirth: null,
      SSN: null,
      address: null,
    },
    states: {
      NAME: {
        entry: 'showNameScreen',
        on: {
          SUBMIT: {
            target: 'DATE_OF_BIRTH',
            actions: assign((context, { name }) => ({
              ...context,
              name,
            }))
          }
        }
      },
      ...
    },
  },
  {
    actions: {
      showNameScreen: (context, event) => Navigation.push('NameScreen'),
    }
  }
);
```

---

![xstate application machine](/images/tech/application-machine.png)

There a couple of new features to unpack here:

1. **Context API**: The statechart maintains its own data store called its *context* which can be assigned to using the
*assign* action from the library.
2. **Action handlers**: Actions, as mentioned earlier, are synchronous side-effects that can be performed on
transitioning, entering or exiting a state. Each time one of our UI states is entered, we perform a submit action to
store the user's information and push on a new screen.

---

## Nested Flows

What if we wanted to allow a user to stop and resume applications for multiple financial products at a time?

As actors, each statechart service can spawn and manage its own child services. We can create a
`BankApplicationManagerMachine` to handle multiple applications.

---

```javascript
import { Machine, spawn } from 'xstate';

return {
          applications: {
            ...context.applications,
            [event.name]: application
          },
          activeApplication: application,
        };
      })
    }
  }
});
```

---

```javascript
import { useMachine, useService } from '@xstate/react'
import { useMemo, useCallback } from 'react';

const products = [
  { name: 'Chase Bank', id: 'chase' }, 
  { name: 'Bank of America', id: 'bank-of-america' }
];

const Application = ({ service }) => {
  const [current, send] = useService(service);

if (current.matches('NAME')) {
    return (
      <NameForm
        initialData={current.context.name}
        onSubmit={(data) => send('SUBMIT', data)} 
      />
    );
  } else if (current.matches('DATE_OF_BIRTH')) {
    return (
      <DateOfBirthForm
        initialData={current.context.dateOfBirth}
        onSubmit={(data) => send('SUBMIT', data)}
      />
    );
  }
  ...
}
```

---

```javascript
const ApplicationManager = () => {
  const [current, send] = useMachine(BankApplicationManagerMachine);
  const { activeApplication } = current.context;

const handleOpenApplication = useCallback(
    product => send('OPEN_APPLICATION', { product }),
    [send]
  );

const renderApplicationPicker = useMemo(() => products.map(product => (
    <a onClick={() => handleOpenApplication(product.name)}>{product}<a/>
  ), [handleOpenApplication]);

return (
    <div>
      {renderApplicationPicker()}
      {activeApplication && <Application service={activeApplication} />}
    </div>
  );
};
```

---

Storing spawned applications and their data in a state machine separately from the UI has a number of advantages
over a traditional data-in-components implementation:

1. Applications can process data in the background even when their components are unmounted
2. Application services and their data is stored by the application manager and can be persisted and restored
without any external data mechanism.
3. The UI framework layer (e.g., React) becomes a plain view layer; logic and side-effects are not tied directly
to the UI, except where it is appropriate.
4. Business logic is testable independent of UI

---

### A New State of Mind

Whether you have written state machines before, there are always state machines in our code, either implicit or
explicit.

Implicit ones are generally harder to maintain, visualize and get right. In theory, an explicit state machine can
help developers optimize for correctness and clarity in their code.

---

### Considerations

* It's a new set of tools and terminology: When to use a parallel state? What is an interpreter and a service?
* It increases the lines of code for smaller implementations especially
* It's a different programming model, everyone is used to standard if/else conditional statements and there can be
a lot of *a boolean is much simpler!* arguments between developers.

---

### Investigating Further

There are excellent resources on both statecharts and xstate that I would recommend exploring if you're interested
in the topic:

* [xstate docs](https://xstate.js.org/docs/)
* [statechart model docs](https://statecharts.github.io/)