Practical State Machinery

Examples

Wizards

Multipage forms, sometimes called “wizards”, are a common design pattern. They can also create headaches for web developers, as they require custom forms and logic based on the state of the user’s interaction. Here’s a typical and relatively simple checkout wizard you might use in an online store:

{
  "initial": "cart",
  "transitions": {
    "checkout": { "cart": "shipping" }
    "advance": {
      "shipping": "billing",
      "billing": "payment",
      "payment": "confirmation"
    },
    "confirm": { "confirmation": "accepted" },
    "cancel": {
      "shipping": "cart",
      "billing": "cart",
      "payment": "cart",
      "confirmation": "cart"
    }
}

That is: 

• The initial state will be cart and will remain so while the user shops.
• The checkout event can only occur while in state cart, and when that event happens, we move to shipping.
• The user may advance through the form when it’s in state shipping, billing, or confirmation.
• From state confirmation alone, the user can confirm the order, at which point the payment will be run and the form will enter accepted, a terminal state (because there’s no event that leads out of it to another state).

If the user has started the checkout process but hasn’t finished it—i.e., if we’re in any state other than cart or accepted—we can cancel the checkout and continue shopping.

Imagine, in your language of choice, implementing the above with conditional logic. The user form itself must be rendered based on the state of the order, as will client- and server-side validations and side effects of successful operations, like sending confirmation emails or reindexing customer data. That’s four sites—rendering the form, running client-side validations, running server-side validations, dispatching backend side effects—where you’d potentially have if or case or switch statements to maintain. Imagine also that the business team will inevitably come asking for a new screen in the middle of the wizard, with its own form, validation, side effects and so on, so all of this logic should be easier to refactor, for your own health if nothing else.

Conditional logic to select a form component using JavaScript might look like this:

switch (currentPage) {
  case "billing":
    return 
  case "shipping":
    return 
   ...
}

This code breaks encapsulation by making two things its own responsibility: the iteration logic (the list of case statements) and the dispatch logic (the connection between, e.g., ”billing” and BillingForm). Suppose again we have four places where this or something like it happens in the application. Because the iteration logic is foisted on the caller, that’s four different lists of possible states. While one is updated, others might not be. From a design perspective it’s simply not the caller’s job to specify what the possible values are for the form, or what the connection is between those values and actual form components.

It would be great if we could abstract/centralize both of those things, maybe by writing a little function like this:

// like this:
getStateByName(currentPage).component
// or this:
getStateByName(currentPage).validators

This hypothetical function would take the name of the current page and return an object that provides what the caller really wants as simple keys. We’ll call these “state objects.” Callers don’t have to iterate over the possible states of the form, and state-specific information, like what form component to use, can stay encapsulated:

/* states/billingStage.js */

import { BillingForm } from FormComponents

export default const billingState = {
  pageName: "billing",
  component: BillingForm,
  validations: {
    field1: (value) => { ... }
    ...
  }
}

Now all you need to implement getStateByName is a registry of state objects, keyed by pageName.

The next page in the form is also dependent on the current state; when you leave shipping you go to billing, whereas when you leave billing you go to payment. Once you’ve started the checkout process you can cancel it, but not after you’ve paid for it, i.e., if the state is accepted. This logic will be used by the server to update the state, and by validators to tell the user if what they’re trying to do is permitted. Let’s add a transitions key to our state object above to say what actions are possible, and what next state they will result in:

/* states/billingState.js */

export default const billingState = {
  ...
  transitions: {
    advance: "payment",
    cancel: "cart"
  }
  ...
}

Congratulations, in the process of cleaning up conditional logic you have essentially implemented a state machine. With the addition of an initial state, (which you have already implemented elsewhere in your application, if the feature works at all) the transitions objects of each state can easily be combined and transformed into the format above.

The advantage of the format above, and of thinking in terms of state machines from the jump, is that it gives you an efficient, high-level representation of things you were probably going to do anyway, one way or another.