State machine config structure question/proposal

[alxdnlnko]

@muxa Hi! First of all thanks for the great component! 👍 I love state machines, I use them in my everyday work, and i'm very excited about the opportunity of applying them in my home automations 😃

There is only one confusing thing for me in your implementation. I hope my thoughts would be useful for you.

The "problem" is that the "inputs" list is global. Input becomes the main entity, it has information about states in which that input could be triggered, so you can't think in states because of that. (e.g. to know what could happen in some state, you have to look through all inputs and check if that state is included there).

A more standard way of describing state machines is to have possible "events" within every state. This way you can think in states, state is the main thing in state machines. Knowing the current state, you can easily see, what events could happen in it, what transitions could be done from it and so on.

Pseudo-code example:

- states:
  - name: OFF
    on_enter: ...
    events:
      - name: BUTTON_CLICKED
        target: ON
      - name: MOTION_DETECTED
        target: ALARM
  - name: ON
    on_enter: ...
    events:
      - name: BUTTON_CLICKED
        target: OFF
        actions:
          - logger.log "Switching off"
  - name: ALARM
    on_enter: ...
    events:
      - name: RESET
        target: OFF

This way you would have a full information about every state in one place. You can clearly see what could happen in current state and what would be done in that case.

Please take a look at the config structure used in this library to understand better what I try to explain:
https://xstate.js.org/
https://xstate.js.org/docs/guides/start.html

Sorry if my explanation is confusing, please ask questions if you didn't get my thoughts, I would be happy to discuss 😃

[muxa]

@alxdnlnko thanks for the suggestion. This does make sense. I'll respond in more details when I have more time.

[muxa]

@alxdnlnko When I'm been thinking about the configuration schema to the state machine I went though different approaches, and settled on the one currently implemented. For me it felt more natural at the time to define transitions from inputs perspective, i.e. "what happens on this input", as opposed to "from state has transitions to these states on these inputs".
The input-centric config allows defining actions for certain inputs, without duplication that the event-centric config would require, e.g. here a snippet from one of my configs:

    inputs:
      ...
      - name: CLOSE
        transitions:
          - OPEN -> CLOSING
          - OPENING -> CLOSING
          - OPEN_HOLD -> CLOSING
          - WAITING_CLOSE -> CLOSING
        action:
          - switch.turn_on: gate_relay

Another benefit that I saw in the input-centric config is that it has tighter validation - the transitions states are validated against the list of defined states. And with a state-centric config that you've suggested, there is no validation of event names (e.g. if made a typo). That can be solved by defining all allowed event names in a single list separately, but that would make the config more verbose than it needs to be.

It's possible to implement support for both state-centric and input centric config to have the both of both worlds. But having too much flexibility will increase complexity of the code and config overall and is likely to become confusing.