A library for finite state machine realization

I'm having trouble compiling the test methods as the file 'fsm_test.g.dart' doesn't exists.

I'm assuming this is generated by build_running but running a build does nothing:

pub run build_runner build 
[INFO] Generating build script completed, took 211ms
[SEVERE] Nothing can be built, yet a build was requested.
[INFO] Reading cached asset graph completed, took 35ms
[INFO] Checking for updates since last build completed, took 304ms
[INFO] Running build completed, took 2ms
[INFO] Caching finalized dependency graph completed, took 25ms
[INFO] Succeeded after 36ms with 0 outputs (0 actions)

The current on clause takes two arguments. This tends to make the FSM definitions fairly dense.

I'm proposing a breaking change to the api so that the on clause on takes a single argument.

This changes has two advantages:

1. the code will be easier to read
2. we reduce the risk of further breaking changs as the single argument will be a class which can contain additional arguments if required at a later date.

Whilst this change will break existing code the updates to the code will be straight forward and mechanical in nature.

Here is an example of what the existing code looks like:

As such I'm proposing the following alteration to the '.on' method.

..s_stateMachine = StateMachine<State, Event, SideEffect>.create(
      (g) => g
        ..initialState(AppLaunched())

        /// AppLaunched
        ..state<AppLaunched>((builder) => builder
          ..onEnter((s) => s.onEnter())
          ..on<ForceRegistration>((initialState, forceRegistration) =>   ForcedRegistrationRequired())
          ..on<HasApiKey>((initialState, hasApiKey) => RegistrationRequired())
          ..on<MissingApiKey>((initialState, missingApiKey) => Registered()))

Here is an example of what the new code would look like:

_stateMachine = StateMachine<State, Event, SideEffect>.create(
      (g) => g
        ..initialState(AppLaunched())

        /// AppLaunched
              ..state<AppLaunched>((builder) => builder
          ..onEnter((s) => s.onEnter())
          ..on<ForceRegistration>((details) =>   ForcedRegistrationRequired())
          ..on<HasApiKey>((details) => RegistrationRequired())
          ..on<MissingApiKey>((details) => Registered()))

The details argument would be:

class TransitionDetails<STATE, EVENT>
{
      STATE state;
      EVENT event;
}

typedef TranstionFunction<STATE, EVENT> = TransitionTo<STATE, SIDE_EFFET> Function(TransitionDetails details);

Thoughts?

I'm looking to encapsulate some of the transition logic in the state. I think this is essentially a guard condition.

An event comes into a state and depending on data in the event the states transition needs to be selected dynamically.

So the question is, what is the appropriate why to dynamically select the next state when an event arrives.

   /// HasMobileNo
        ..state<MobileNoAcquired>((builder) => builder
        ..on<ApplyUserDetails>((mobileNoAcquired, applyUserDetails) => mobileNoAcquired.applyUserDetails(applyUserDetails))
        ..on<NoUserForMobile>((mobileNoAcquired, noUserForMobile) => EmailRequired().transitionTo(builder, noUserForMobile))
        ..on<UserDisabled>((mobileNoAcquired, userDisabled) => AccountDisabled().transitionTo(builder, userDisabled))


class MobileNoAcquired extends State {
  TransitionTo<State, SideEffect> applyUserDetails(ApplyUserDetails details) {
    switch (details.details.userStatus) {
      case UserStatus.NOT_FOUND:
        return super.transitionTo(NoUserForMobile()));
        break;
      case UserStatus.DISABLED:
        return FSM().transition(UserDisabled());
        break;
    }
  }
}

You can see from the above code I've considered a couple of alternatives but neither seems corret.

The first version where I call super.transitionTo returns the wrong type. The second where I call FSM().transition just seems wrong as I'm calling back into the fsm at the very top level (FSM is a StateMachine) whilst already in a state transition.

So what is the correct way of doing this?

To help with debugging I'm currently adding an onEnter and onExit method to each state.

It would be much nice if this could be done globally.

The GraphBuilder.onTransition listener seems an natural place to hook all transitions and log these events.

The problem is that the Transition object that the listener passes has little information that is of use.

Ideally the Transition object should contain:

Prior state New state Event SideEffect.

This would then allow it to be used for debug logging and reduce clutter in the state machine declaration.