/xstate-examples

A series of examples showing how to model application state with statechart using xstate

Primary LanguageJavaScript

Here are four examples showing different usages of xstate.

Each one was built upon the previous one, hence it's recommended to start with crud-v1-services and move forward from there. All examples also available on codesandbox, feel free to play and fork those examples, and report any issues you found here, PRs welcome too.

All these examples are built with StatesKit - a visual statechart editor where you can drag and drop to creat states, events and stuff, no need to code at all, the goal is to help dumping the ideas from your brain to states real quick, don't forget to give it shot! 😎

Also here's a detailed write up on statecharts introducing it's core benefits.

Core features of each example

crud-v1-services

  • A typical CRUD app showing how to model application states with statechart and implement the basic functionalities in xstate, pay attention to how invoked Services are used to serve different API calls.

  • There are four kind of services in xstate, which are Promise, Callback, Observable and Machine, for this example we are focused on Callback because it's the most commonly used services in a real world application.

  • Read about different kind of Services here

  • Play on [codesandbox]

crud-v2-optimistic-update

  • v2 is built upon v1, but with more delicate handling of optimistic update processing and used different child state to model the app, observe how parallel states were used to handle different steps of each operation also pay attention to both happy and sorrow paths.

  • Play on [codesandbox]

crud-v3-promises

  • v3 is a slightly differnt version based on v2 using a different invoked Service called Promise, pay attention to services.js and see how loadItems and deleteItem worked.

  • Key different between Callback and Promise service is you get to dispatch events back to the parent just once with Promise, whereas in Callback you could use cb and onReceive functions to dispatch events multiple times, both has it's own place in an application, hence this example.

  • Play on [codesandbox]

crud-v4-actors

  • v4 is based on David'sTodoMVC example but with a couple of improvements.

  • This is by far the most complicated example, it showcased how to use the latest Actor model for communication between child components and their parent.

  • Pay attention to how TodosMachine spawned child TodoMachines and pass it's ref to each child component as a local single truth that handles the component state., more details in the folder's Readme.md

  • See detailed docs on actor here, this is something you don't want to miss 😎

  • In short, Service and Actor are basically the same thing but used differently, rule of thumb:

    • Statically invoke services (you have to write all services in machine statemenet in advance)
    • Dynamically spawn actors (you can spawn new actors from any events whenever needed)

  • Play on [codesandbox]

Notes

  • Generic naming convention for states and events are:

    • camelCaseForState

    • UPPER.CASE.FOR.EVENT

      • By using dots for event it is possible in the future to implement wildcase event matching, for example UPPER.* to match all events starting with UPPER

  • Basic guiding rule for all these example are hoping to make ui a dumb layer

    • meaning ui only does two things
      • draw the user interface
      • accept user inputs (keyboard/mouse events)
    • then delegate those events to xstate to handle, where all business logics are encapsulated

Todo

  • Rewrite tests

  • Enable whyDidYouRender to eliminate unnecessary renders.