Add Start() so that the initial state can emit commands and immediately transition. Renamed InitialStateOrDefault to InitialState since it isn't optional.

Author: leeoades

FunctionalStateMachine.Core.Tests/StateMachineImmediateTransitionTests.cs

@@ -61,6 +61,7 @@ public void ImmediateTransitionGuard_CanBlockTransition()
                     .TransitionTo(State.Waiting)
                     .Done()
             .For(State.Waiting)
+            .For(State.Ready)
             .Build();
 
         var (state, _, commands) = machine.Start(new Data("stop"));

FunctionalStateMachine.Core/StateMachine.cs

@@ -77,29 +77,22 @@ public bool TryFire(
             throwOnUnhandled: false);
     }
 
-    public TState? InitialStateOrDefault()
+    public TState InitialState
     {
-        return _hasInitialState ? ResolveInitialLeaf(_initialState!) : default;
-    }
-
-    public (TState State, TData Data, IReadOnlyList<TCommand> Commands) Start(TData data)
-    {
-        if (!_hasInitialState)
+        get
         {
-            throw new InvalidOperationException("No initial state has been configured.");
-        }
+            if (!_hasInitialState)
+            {
+                throw new InvalidOperationException("No initial state has been configured.");
+            }
 
-        return Enter(_initialState!, data);
+            return ResolveInitialLeaf(_initialState!);
+        }
     }
 
-    public (TState State, TData Data, IReadOnlyList<TCommand> Commands) Enter(TState state, TData data)
+    public (TState State, TData Data, IReadOnlyList<TCommand> Commands) Start(TData data)
     {
-        if (!_states.ContainsKey(state))
-        {
-            throw new InvalidOperationException($"State '{state}' is not configured.");
-        }
-
-        var targetState = ResolveInitialLeaf(state);
+        var targetState = InitialState;
         var commandList = new List<TCommand>();
         AppendInitialEntryCommands(commandList, targetState, data);
         var (finalState, finalData) = ApplyImmediateTransitions(commandList, targetState, data);
@@ -111,6 +104,7 @@ public bool TryFire(
         return (finalState, finalData, commands);
     }
 
+
     private bool TryFireInternal(
         TTrigger trigger,
         TState currentState,
@@ -453,6 +447,7 @@ private void AppendInitialEntryCommands(
         }
     }
 
+
     private List<TState> GetHierarchyChain(TState state)
     {
         var chain = new List<TState>();
@@ -1743,19 +1738,14 @@ public bool TryFire(
         return _inner.TryFire(trigger, currentState, new NoData(), out newState, out _, out commands);
     }
 
-    public TState? InitialStateOrDefault() => _inner.InitialStateOrDefault();
+    public TState InitialState => _inner.InitialState;
 
     public (TState State, IReadOnlyList<TCommand> Commands) Start()
     {
         var (state, _, commands) = _inner.Start(new NoData());
         return (state, commands);
     }
 
-    public (TState State, IReadOnlyList<TCommand> Commands) Enter(TState state)
-    {
-        var (newState, _, commands) = _inner.Enter(state, new NoData());
-        return (newState, commands);
-    }
 
     internal sealed class StateConfiguration
     {

FunctionalStateMachine.Samples/LightSwitchSample.cs

@@ -46,12 +46,12 @@ public class LightSwitchDemo(ITestOutputHelper output)
     public void Demo()
     {
         var machine = LightSwitchSample.Build();
-        var state = machine.InitialStateOrDefault();
+        var state = machine.InitialState;
 
         for (int i = 0; i < 5; i++)
         {
-            (state, var commands) = machine.Fire(LightTrigger.Toggle, state);
-            Run(commands);
+            (state, var toggleCommands) = machine.Fire(LightTrigger.Toggle, state);
+            Run(toggleCommands);
         }
 
     }

FunctionalStateMachine.Samples/ShoppingTrolleySample.cs

@@ -168,7 +168,7 @@ public class ShoppingTrolleyDemo(ITestOutputHelper output)
     public void Demo_Card_Payment()
     {
         var machine = ShoppingTrolleySample.Build();
-        var currentState = machine.InitialStateOrDefault();
+        var currentState = machine.InitialState;
         var currentData = new CartSession(new ShopData([], 0));
 
         (currentState, currentData) = Fire(CartTrigger.StartShopping(), currentState, currentData, machine);
@@ -183,7 +183,7 @@ public void Demo_Card_Payment()
     public void Demo_Cash_Payment()
     {
         var machine = ShoppingTrolleySample.Build();
-        var currentState = machine.InitialStateOrDefault();
+        var currentState = machine.InitialState;
         var currentData = new CartSession(new ShopData([], 0));
 
         (currentState, currentData) = Fire(CartTrigger.StartShopping(), currentState, currentData, machine);

FunctionalStateMachine.Samples/ShoppingTrolleySampleTests.cs

@@ -88,7 +88,7 @@ public void PayByCash_OverpaymentIssuesRefund()
     private static (ShopState State, CartSession Data) StartState(
         StateMachine<ShopState, CartTrigger, CartSession, ShopCommand> machine)
     {
-        return (machine.InitialStateOrDefault(), new CartSession(new ShopData([], 0)));
+        return (machine.InitialState, new CartSession(new ShopData([], 0)));
     }
 
     private static (ShopState State, CartSession Data) Fire(

docs/entry-exit.md

@@ -30,4 +30,4 @@ var machine = StateMachine<State, Trigger, Data, Command>.Create()
 
 ## Notes
 
-- Entry actions run when a state is entered. For the initial state, call `Start(...)` or `Start()` to emit entry commands.
+- Entry actions run when a state is entered. The initial state does not trigger `OnEntry` until the machine transitions into it, unless you call `Start(...)`.

docs/immediate-transitions.md

@@ -38,5 +38,5 @@ var (state, data, commands) = machine.Start(Data.Initial);
 ## Notes
 
 - Immediate transitions run only when a state is entered.
-- Use `Start(...)` (or `Start()` for no-data machines) to run entry actions and immediate transitions from the initial state.
+- Use `Start(data)` to run `OnEntry` and immediate transitions from the initial state.
 - If no immediate transition guard matches, the machine stays in the current state.