JSX Pragma for xstate

[bobcat-pixel]

Hello,

I am a big fan of your library and really appreciate the amount of work you've put into it. I feel lucky to be introduced to statecharts and SCXML through it. I read the SCXML docs while trying to learn the spec and how it diverges from XState's useful additions like actors, etc. During the course of that I started making a JSX pragma that mirrored the SCXML language to learn more about it.

JSX/Xstate is to SCXML, what JSX/React is to HTML. You can nest together states like React components. It's not any different than plain xstate in terms of functionality, I just find it really easier to read for some reason.

Here is one of the examples from your documentation:

/** @jsx statechart */
import statechart from "./index";

// hierarchical parallel state nodes, traffic light
const WalkSignNode = () => (
  <state id="walkSign">
    <state initial="solid">
      <state id="solid">
        <transition event="COUNTDOWN" target="flashing" />
      </state>
      <state id="flashing">
        <transition event="STOP_COUNTDOWN" target="solid" />
      </state>
    </state>
  </state>
);

const PedestrianNode = () => (
  <state id="pedestrian" initial="walk" compound>
    <state id="walk">
      <transition event="COUNTDOWN" target="wait" />
    </state>
    <state id="wait">
      <transition event="STOP_COUNTDOWN" target="stop" />
    </state>
    <state id="stop" final />
  </state>
);

const Light = () => (
  <machine initial="green">
    <state id="green">
      <transition event="TIMER" target="yellow" />
    </state>
    <state id="yellow">
      <transition event="TIMER" target="red" />
    </state>
    <state id="red" type="parallel">
        <WalkSignNode />
        <PedestrianNode />
    </state>
  </machine>
);

// 5
// non-parallel hierchical state nodes
const Crosswalk = () => (
  <state initial="walk">
    <state id="walk">
      <transition event="PED_COUNTDOWN" target="wait" />
    </state>
    <state id="wait">
      <transition event="PED_COUNTDOWN" target="walk" />
    </state>
    <state id="stop" />
    <state id="blinking" />
  </state>
);

const TrafficLight = () => (
  <machine initial="green">
    <state id="green">
      <transition event="TIMER" target="yellow" />
    </state>
    <state id="yellow">
      <transition event="TIMER" target="red" />
    </state>
    <state id="red">
      <transition event="TIMER" target="green" />
      <Crosswalk />
    </state>
    <transition event="POWER_OUTAGE" target=".red" />
    <transition event="POWER_RESTORED" target=".red.blinking" />
  </machine>
);

The machine configs can be given in two ways:

const TrafficLight = () => (
  <machine initial="green">
    {{
        context: {},
        mutations: {},
        actions: {},
        guards: {}
    }}
    <state id="green">
      <transition event="TIMER" target="yellow" />
    </state>
  </machine>
);

or simply saying <machine initial="green" config={configObj}>

My only real change besides syntax is having a separate "mutations" and "actions." This helps me mentally separate fire and forget actions and mutations easily just by looking at the code. It's not a deal breaker by any means, but a suggestion.

I have 4 main questions/areas of exploration at this point:

(1) Is this something you'd be interested in in a blessed xstate package, or should I continue on my own path?

(2) I hoped that using this syntax would unlock some interesting declarative patterns for composition. Like pre-hook React. I know pubsub and message passing is the preferred way of doing things here, but I thought it might help those in situations that call for a more tightly coupled implementation

(3) Is there any move to support async iterators in xstate? Or would such a PR be accepted? I think that would help

(4) I am a TS n00b. Would appreciate any advice on this aspect.

Thanks again for xstate :)

[Andarist]

During the course of that I started making a JSX pragma that mirrored the SCXML language to learn more about it.

Just remember that there are some subtle differences between both formats - I see you have already handled some of them though, especially the fact that we need <state type={type}/> whereas SCXML has separate children elements for each type (or rather - most types).

My only real change besides syntax is having a separate "mutations" and "actions." This helps me mentally separate fire and forget actions and mutations easily just by looking at the code. It's not a deal breaker by any means, but a suggestion.

It would be great if you could give a more concrete example of both types.

(1) Is this something you'd be interested in in a blessed xstate package, or should I continue on my own path?

This is a really cool experiment! I believe though that this is somewhat out of the scope of the XState's core packages - but when this matures a little bit it could be linked to from the "Community" page (or similar). It's generally IMHO better to provide a single blessed way of doing something, otherwise, the community starts to diverge, people unnecessarily discuss which way is better, you start getting inconsistent articles on the internet etc.

(2) I hoped that using this syntax would unlock some interesting declarative patterns for composition. Like pre-hook React. I know pubsub and message passing is the preferred way of doing things here, but I thought it might help those in situations that call for a more tightly coupled implementation

Any more concrete example of this?

(3) Is there any move to support async iterators in xstate? Or would such a PR be accepted? I think that would help

You can already use them - just using a callback actor. It might become a little bit easier in the v5 to create your own "to-actor" converters. There are already some changes regarding that on the next branch.

(4) I am a TS n00b. Would appreciate any advice on this aspect.

I'm afraid that parent-child relationships in JSX cannot be validated by TS.

[bobcat-pixel]

Just remember that there are some subtle differences between both formats - I see you have already handled some of them though, especially the fact that we need whereas SCXML has separate children elements for each type (or rather - most types).

Yes, I like the xstate way of just saying type="parallel" for example instead of the SCXML parallel tag. In most cases I've tried to copy SCXML as much as possible, but there are a couple arbitrary deferences to the xstate way. Now it shouldn't be too hard to really get a perfect 1-1 correspondence with SCXML syntax-wise if that were ever a priority, but my focus was just on making xstate easier and more ergonomic to use for me.

It would be great if you could give a more concrete example of both types.

Sure, action is just an xstate action without any extra baggage. "Mutations" on the other hand wraps the actions in an xstate-immer assign operation if it's a function or object.

      mutations: {
        createClient: (context) => {
          context.client = sdk.createClient(url);
        },
        setToken2: {
          token: (context, { data }) => data,
        },
        setToken: (context, { data }) => {
          context.token = data;
        },
      }

So in this case setToken2 would provide the best dev tools experience, but in my experience I'm content with seeing "setToken" in the tools, even if it just shows the function name and lacks the name of the actual field being updated.

This is a really cool experiment! I believe though that this is somewhat out of the scope of the XState's core packages - but when this matures a little bit it could be linked to from the "Community" page (or similar). It's generally IMHO better to provide a single blessed way of doing something, otherwise, the community starts to diverge, people unnecessarily discuss which way is better, you start getting inconsistent articles on the internet etc.

That makes sense, and I understand, that would be very confusing, just figured it wouldn't hurt to ask check :). I'm glad you found it interesting. I became jealous of languages with syntax amenable to state machines like Clojure and really want to try to replicate that with JSX. I hope to post it soon and hopefully get some advice on the project esp re: TS.

Any more concrete example of this?

Unfortunately no, my use case is too simple to require it and pubsub is working just fine for what I'm doing. But I could imagine something like the React "render props" pattern being used for a base machine/singleton that needs to be used in different places in the app. Or probably more commonly, lock step synchronicity with state machines by nesting them together.

You can already use them - just using a callback actor. It might become a little bit easier in the v5 to create your own "to-actor" converters. There are already some changes regarding that on the next branch.

Will take a look at this, thanks

Re: TSX, that's a big bummer. I'll still keep hacking on it though. Thank you for the feedback!

[Andarist]

I became jealous of languages with syntax amenable to state machines like Clojure

Do you happen to have an example of that? Would be interested in seeing how this could look like in Closure.

[bobcat-pixel]

(Just head up I'm not a Clojure aficionado, just something I tinkered with a bit). They have a notion of "keywords" which can be simultaneously thought of as strings, keys in a map, or functions. So state machines are just these huge maps, where a transition to a new state can succinctly describe what action is to be performed when that transition occurs. There are some examples here at the reframe docs:[here]((https://day8.github.io/re-frame/EPs/005-StateMachines/#how). (Reframe was like the granddad of Elm and Redux0

There is also Idris which is able to embed state machines into the type system, but I haven't even learned how that works yet. Just that it involves depenedent types, somehow. I don't know Idris either, just throwing it out there because you seemed interested. The book "Type Driven Development with Idris" goes into it eventually but I haven't gotten that far in the book yet.

[Andarist]

Thanks for the book recommendation - sounds very interesting on its own, so gonna probably order it eventually :)

[johnyanarella]

Neat experiment! I wonder... could the JSX parent/child tag relationships be validated via custom ESLint rules?

[Andarist]

Definitely - if you would only keep them in a single tree.

[bobcat-pixel]

Thanks for for the suggestion! I'm new to writing eslint rules but if there is any specific idea you had in mind I'd love to hear about it. Thank you.

[Andarist]

No particular ideas - you would have to learn how to write those rules, the rest should be somewhat easy. ESLint is based on AST representation of the code and the visitor pattern - you would have to match the JSXELement type (or similar), check if its openingElement's name is "machine" and if yes then traverse its children nodes with your validation rules.