canDo() - Testing in advance when emitting and event would result in a transition or not.

[szabeszg]

Hello,

Thanks for sharing your state machine project, I like it a lot, however, I'm missing at least one feature: in (for example) Dave Stewart's "proof of concept" FSM it is possible to query the transition chart to see if an action is available from the current state, meaning if emitting a particular event would result in a transition or not.

see: https://github.com/davestewart/javascript-state-machine/blob/master/docs/api/statemachine.md#canDo

This would be particularly useful to update GUI elements based on the result of such a function call. When emitting an event would result in no state change then I need to disbale buttons in advance, for example.

[shuckster]

Thank you for your feedback and observation.

Statebot has two methods that deal with upcoming states:

• #canTransitionTo
• #stateAvailableFromHere

Unfortunately I don't think they quite line-up with the specification you linked-to because canDo takes the current action/event. But Statebot charts specify only state-transitions, and this is its only internal mapping.

Events can be specified in #performTransitions for example, but these are applied more like addEventHandler, so there is no corresponding dictionary against the states they might cause a transition to.

However, I wouldn't say that the scenario you outline is impossible to implement with Statebot, but perhaps it may be tricky to make it elegant within a single machine.

Take this contrived example:

[entering-email] -> email-valid | email-invalid
  email-invalid -> entering-email
  email-valid -> [entering-password]

[entering-password] -> password-valid | password-invalid
  password-invalid -> entering-password
  password-valid -> [form-completed]

[form-completed]

Using the above chart, perhaps an email-form might look something like:

const emailHasValidFormat = machine.inState('email-valid')
const submittedInvalidEmail = machine.history().includes('email-invalid')

return (
  <form>
    <input type="text" name="email" />

    {submittedInvalidEmail && (
      <p>Your email is invalid. Please try again.</p>
    )}

    <submit disabled={!emailHasValidFormat}>Submit</submit>
  </form>
)

As you can see, only #inState was required in this case.

I can imagine such examples could be solved with more than one Statebot, which might keep each one simple rather than try to have an exhaustive chart as I've tried to attempt in the above thrown-together example.

Happy to hear more on it though. Do you have a more complete example?

[shuckster]

I'll try and summarise what you've said to see if I've got the picture straight:

stateAfterEmitting should:

1. ... have the possibility to return multiple states, either as a special value or as an array of values.

2. ... indicate if a state-transition will not happen.

3. ... indicate if an event is not registered.

As for the name of inStateAfterEmitting, I agree that canTransitionToByEmitting sounds more consistent, so thank you for that suggestion.

To address points 1-3:

1. Does #statesAvailableFromHere not already cover this? If you wish to know all potential states from the current state, you don't need to involve an event.

   However, it does not make sense to me to return more than one state if you are asking what will happen if you emit an event. For me, emitting an event should always result in either:

   • a single transition to the next state
   • nothing

   If multiple states are possible from a single event, then this would indicate that the machine has not been well configured. I mean, it's true that an event emitted many times can cause a machine to visit many states over time. But a single event should result in a single transition, which I believe is what canDo/stateAfterEmitting should indicate.

2. Yes, it might indeed by useful to know if a state-transition will not happen, but I think this could be satisfactorily achieved like this:

   const stuck = fsm.stateAfterEmitting('go-north') === fsm.currentState()

   Alternatively, undefined could be returned therefore allowing the user to identify the next-state like this:

   const nextState = fsm.stateAfterEmitting('go-north') ?? fsm.currentState()
   const stuck = fsm.stateAfterEmitting('go-north') === undefined

   For me, I think I prefer the first option just because "next-state equals current-state" makes semantic sense if you're trying to figure out if the machine is "stuck". Comparing to undefined is more ambiguous.

   But perhaps there's room for a more extended syntax like inState has?

   Something like this:

   const upNext = fsm.peek('go-north', {
     'entrance': () => 'Ahead is a place to hang your coat',
     'courtyard': () => 'Through the windows you see overgrown monuments',
     'paddock': () => 'A stream of water burbles ahead',
     'woods': () => 'The trees are tall and thin and many',
     undefined: () => 'You cannot go north',
   })

   Hopefully this makes sense? (By the way, peek is an alternative name for stateAfterEmitting. I think I prefer it, especially as it doesn't seem to clash so badly with the extended syntax above.)

   Actually, this syntax could allow undefined to be returned like this:

   const nextState = fsm.peek('go-north', {
     undefined: undefined
   })
   // Force peek() to return `undefined` instead of the current-state
   // if no transition is possible. (States with no key in the object
   // will be just be returned as-is.)

   I don't like it, but it would be possible. :)

3. For the case where an event is not registered, I'm not sure if this one should be behaviourally any different from the previous case.

   I'm just trying to think about what's important to know if a transition isn't going to happen...

   If being stuck can already be determined by:

   const stuck = fsm.peek('go-north') === fsm.currentState()

   Then I wonder about the value of being more granular than this.

   I think logging would still be useful. It's good to know if a transition didn't happen because an event isn't registered. But as for what to return, I am thinking that for the general case (ie; not just games) it may be better to always return a state.

That's my thinking so far. Let me know if I understood correctly.

[szabeszg]

Hi, regarding points 1-3

1. I was thinking along the line of "conditional transitions" so I misinterpreted why you proposed the "error" message, and now I get what you meant by "likely config issue". So yes, there is no need to implement "runtime error checking" like that, I guess.

2. I like the "peek" version, it is a lot shorter and an even more descriptive than stateAfterEmitting, as "state after emitting" could also be interpreted by the coder as the state after an event has actually been emitted, but peek sounds more like testing beforehand.

I also like your upNext example, looks simple but powerful.

3. When I know what event I tested for emitting and I also know that emitting that event would not result in a state change, then I can of course rely on that info to output something I described in my previous post. I was just thinking that if the method already detects such a scenario for outputting a warning message, then it might be also useful to use it in the program itself as a "shorthand technique". Also, such an application state might not mean it is an issue with the code when it is handled gracefully. Well, eat least if I understand correctly what you propose.

[shuckster]

Thank you for the further feedback.

I believe the combination of peek and canTransitionToAfterEmitting should be able to cover the use-cases you bring up.

So with the following config:

const machine = Statebot('peek-a-boo', {
  chart: `
    idle -> running
  `
})

machine.performTransitions({
  'idle -> running': {
    on: 'start'
  }
})

We could do this:

1: machine.peek('start')
// "running"

2: machine.peek('non-existent-event')
// "idle"
// -> ie; the current-state

3: machine.canTransitionToAfterEmitting('non-existent-event', 'running')
// false
// -> no transition will happen

So with 2:, no transition will happen and we have to detect it in another step (ie; by comparing the result to currentState().) But with 3: we don't need to take that step.

You make a good case for returning a different result depending on whether or not a warning is emitted, but I'm not sure it convinces me. I think I'd prefer a dedicated method for that, perhaps called isEventRegistered? But since FSM config is specified up-front I wonder about the utility.

Finally, after looking at canTransitionToAfterEmitting I find it a bit long, so have come up with these alternatives:

1: machine.canTransitionTo('running', { afterEmitting: 'start' })

2: machine.afterEmitting('start', { willTransitionTo: 'running' })

I kind of prefer the first one. It's a bit annoying to overload an existing method, but maybe it's worth it?

[szabeszg]

Hello, I do like your proposal of peek and canTransitionTo or afterEmitting, thanks.

Regarding canTransitionTo vs afterEmitting, I would vote for canTransitionTo even if it involves overloading, which is not a big deal when overloading is not overused (so to speak) like in this case, I think. I myself first looked at what canTransitionTo does when looking for a "canDo" method before starting this discussion.

BTW, are you still thinking of including this extended syntax as well, perhaps?

const upNext = fsm.peek('go-north', {
  'entrance': () => 'Ahead is a place to hang your coat',
  'courtyard': () => 'Through the windows you see overgrown monuments',
  'paddock': () => 'A stream of water burbles ahead',
  'woods': () => 'The trees are tall and thin and many',
  undefined: () => 'You cannot go north',
})

In my point of view it would "just" be a "shortcut" but a useful one. However, such an option might rule out the possibility of sensible overloading?

[shuckster]

Good to hear you like the approach.

I'll get to work on both new methods and see if the overloading isn't too much of a pain for canTransitionTo.

I'll also try and get the peek "shorthand" working too.

[szabeszg]

Thank you so much! In the meantime, I refactored my current Construct project to make use of Statebot instead of a bunch of global variables and things are so much cleaner and shorter this way. When using the new methods, the inner workings of the interface state management will be even more streamlined.

I especially enjoy the verbose log messages as they point me to the right direction when things are just not yet working quite right.

In a day or two, I will also find the time to buy you some coffee, btw :)

[szabeszg]

Hi, Thanks for your work and kind words. I'm about to update my current Construct project to use peak() and I will report back.

Just one more observation: as I do not use nmp, first I simply downloaded the zip from https://github.com/shuckster/statebot/releases/tag/v2.9.1
which results in 2.9.0 being downloaded instead of 2.9.1. Downloading the master brach leads to 2.9.1, but for some reason the tagged version does not.

[szabeszg]

As the state machine in my current project is tiny, all I had implemented in addition was only this:

function can(eventToEmit) {
  return fsm.peek(eventToEmit) === fsm.currentState() ? 'disabled' : 'enabled';
}

and I also updated some method calls by using can('restart') and can('accept')

Works fine :) I will need to expand the state machine later on when I add some ajax email sending features, and I also have two, even more complex projects to produce after finishing the current one, so I will definitely do more than this, based on Statebot 2.9+.

[shuckster]

which results in 2.9.0 being downloaded instead of 2.9.1

Oh, that's weird. I wonder if it has always happened like this? I use an automated deploy script, so I'll look into that thank you.

Glad to see you've made use of the new methods already! I look forward to hearing any further feedback or progress you'd like to share.

[shuckster]

The version mismatch might just have been a propagation issue. Saw the same thing today in a different repo.

Hopefully 2.9.2 (same as 2.9.1 but with updated package.json) is downloadable from Git now.

[szabeszg]

I see. Thanks for notifying me.