I didn't like the OnUnhandled action because that means either you have to call out to a dependency or mutate the state. Yuck. Changed to returning a command.

Author: leeoades

FunctionalStateMachine.Core.Tests/StateMachineUnhandledTests.cs

@@ -21,9 +21,12 @@ public void TryFire_ReturnsFalseWhenUnhandled()
     [Fact]
     public void OnUnhandled_InvokesHandler()
     {
-        var log = new List<string>();
         var machine = StateMachine<State, Trigger, Data, CommandBase>.Create()
-            .OnUnhandled((trigger, state, data) => log.Add($"{state}:{trigger}"))
+            .OnUnhandled()
+                .Execute((trigger, state) =>
+                [
+                    new LogCommand($"{state}:{trigger}")
+                ])
             .For(State.Ready)
             .Build();
 
@@ -32,8 +35,7 @@ public void OnUnhandled_InvokesHandler()
         var handled = machine.TryFire(Trigger.Start, currentState, currentData, out _, out _, out var commands);
 
         Assert.True(handled);
-        Assert.Empty(commands);
-        Assert.Single(log);
+        Assert.Single(commands);
     }
 
     [Fact]
@@ -84,4 +86,6 @@ private sealed record Data(string Id)
     }
 
     private abstract record CommandBase;
+
+    private sealed record LogCommand(string Message) : CommandBase;
 }

FunctionalStateMachine.Core/StateMachine.cs

@@ -12,7 +12,7 @@ public static StateMachineBuilder<TState, TTrigger, TData, TCommand> Create()
     }
 
     private readonly Dictionary<TState, StateDefinition> _states = new();
-    private Action<TTrigger, TState, TData>? _onUnhandled;
+    private Func<TTrigger, TState, IEnumerable<TCommand>>? _onUnhandled;
     private bool _hasInitialState;
     private TState? _initialState;
 
@@ -33,7 +33,7 @@ internal StateConfiguration For(TState state)
     }
 
     internal StateMachine<TState, TTrigger, TData, TCommand> OnUnhandled(
-        Action<TTrigger, TState, TData> handler)
+        Func<TTrigger, TState, IEnumerable<TCommand>> handler)
     {
         _onUnhandled = handler;
         return this;
@@ -191,10 +191,10 @@ private bool HandleUnhandled(
     {
         if (_onUnhandled != null)
         {
-            _onUnhandled(trigger, currentState, currentData);
+            var commandList = _onUnhandled(trigger, currentState)?.ToList() ?? new List<TCommand>();
             newState = currentState;
             newData = currentData;
-            commands = [];
+            commands = commandList.Count == 0 ? Array.Empty<TCommand>() : new ReadOnlyCollection<TCommand>(commandList);
             return true;
         }
 
@@ -1914,9 +1914,10 @@ internal void Validate()
 
     public TState CreateState(TState state) => _inner.CreateState(state, new NoData()).State;
 
-    internal StateMachine<TState, TTrigger, TCommand> OnUnhandled(Action<TTrigger, TState> handler)
+    internal StateMachine<TState, TTrigger, TCommand> OnUnhandled(
+        Func<TTrigger, TState, IEnumerable<TCommand>> handler)
     {
-        _inner.OnUnhandled((trigger, state, data) => handler(trigger, state));
+        _inner.OnUnhandled((trigger, state) => handler(trigger, state));
         return this;
     }
 

FunctionalStateMachine.Core/StateMachineBuilder.cs

@@ -13,11 +13,32 @@ public StateMachineBuilder<TState, TTrigger, TData, TCommand> StartWith(TState s
         return this;
     }
 
-    public StateMachineBuilder<TState, TTrigger, TData, TCommand> OnUnhandled(
-        Action<TTrigger, TState, TData> handler)
+    public UnhandledConfiguration OnUnhandled()
     {
-        _machine.OnUnhandled(handler);
-        return this;
+        return new UnhandledConfiguration(this);
+    }
+
+    public sealed class UnhandledConfiguration
+    {
+        private readonly StateMachineBuilder<TState, TTrigger, TData, TCommand> _builder;
+
+        internal UnhandledConfiguration(StateMachineBuilder<TState, TTrigger, TData, TCommand> builder)
+        {
+            _builder = builder;
+        }
+
+        public StateMachineBuilder<TState, TTrigger, TData, TCommand> Ignore()
+        {
+            _builder._machine.OnUnhandled((_, _) => Array.Empty<TCommand>());
+            return _builder;
+        }
+
+        public StateMachineBuilder<TState, TTrigger, TData, TCommand> Execute(
+            Func<TTrigger, TState, IEnumerable<TCommand>> handler)
+        {
+            _builder._machine.OnUnhandled(handler);
+            return _builder;
+        }
     }
 
     public StateConfiguration For(TState state)
@@ -1062,11 +1083,39 @@ public StateMachineBuilder<TState, TTrigger, TCommand> StartWith(TState state)
         return this;
     }
 
-    public StateMachineBuilder<TState, TTrigger, TCommand> OnUnhandled(
-        Action<TTrigger, TState> handler)
+    public UnhandledConfiguration OnUnhandled()
     {
-        _machine.OnUnhandled(handler);
-        return this;
+        return new UnhandledConfiguration(this);
+    }
+
+    public sealed class UnhandledConfiguration
+    {
+        private readonly StateMachineBuilder<TState, TTrigger, TCommand> _builder;
+
+        internal UnhandledConfiguration(StateMachineBuilder<TState, TTrigger, TCommand> builder)
+        {
+            _builder = builder;
+        }
+
+        public StateMachineBuilder<TState, TTrigger, TCommand> Ignore()
+        {
+            _builder._machine.OnUnhandled((_, _) => Array.Empty<TCommand>());
+            return _builder;
+        }
+
+        public StateMachineBuilder<TState, TTrigger, TCommand> Execute(
+            Func<TTrigger, TState, IEnumerable<TCommand>> handler)
+        {
+            _builder._machine.OnUnhandled(handler);
+            return _builder;
+        }
+
+        public StateMachineBuilder<TState, TTrigger, TCommand> Execute(
+            Func<TTrigger, TState, TCommand> handler)
+        {
+            _builder._machine.OnUnhandled((trigger, state) => new[] { handler(trigger, state) });
+            return _builder;
+        }
     }
 
     public StateConfiguration For(TState state)

FunctionalStateMachine.Samples/LightSwitchSample.cs

@@ -9,6 +9,8 @@ public static class LightSwitchSample
 [StateMachineDiagram("diagrams/LightSwitch.md")]
     public static StateMachine<LightState, LightTrigger, LightCommand> Build() =>
         StateMachine<LightState, LightTrigger, LightCommand>.Create()
+            .OnUnhandled()
+                .Ignore()
             .StartWith(LightState.Off)
             .For(LightState.Off)
                 .On<LightTrigger.ToggleTrigger>()

docs/ignore-unhandled.md

@@ -12,6 +12,8 @@ You can explicitly ignore triggers or handle them with a global callback.
 
 ```csharp
 var machine = StateMachine<State, Trigger, Data, Command>.Create()
+    .OnUnhandled()
+        .Ignore()
     .For(State.Ready)
         .On(Trigger.Ping)
             .Ignore()
@@ -22,8 +24,9 @@ var machine = StateMachine<State, Trigger, Data, Command>.Create()
 
 ```csharp
 var machine = StateMachine<State, Trigger, Data, Command>.Create()
-    .OnUnhandled((trigger, state, data) =>
-        data.Log.Add($"Unhandled {trigger} in {state}"))
+    .OnUnhandled()
+        .Execute((trigger, state) =>
+            new Command.LogUnhandled(trigger, state))
     .For(State.Active)
         .On(Trigger.Stop)
             .TransitionTo(State.Stopped)