Basic States to Exit With Different Results (Success, Error, Failure)

Directory.Build.props

@@ -4,7 +4,7 @@
     <LangVersion>latest</LangVersion>
     <EnforceCodeStyleInBuild>True</EnforceCodeStyleInBuild>
 
-    <AssemblyVersion>2.4.0</AssemblyVersion>
+    <AssemblyVersion>2.4.1</AssemblyVersion>
 
     <BaseOutputPath>../../output/$(MSBuildProjectName)</BaseOutputPath>
     <Deterministic>true</Deterministic>

samples/Sample04.ResultTransitions/Program.cs

@@ -1,12 +1,95 @@
 // Copyright Xeno Innovations, Inc. 2026
 // See the LICENSE file in the project root for more information.
 
+using Lite.StateMachine;
+
 namespace Sample04.ResultTransitions;
 
-internal class Program
+/// <summary>State definitions.</summary>
+public enum StateId
+{
+  State1,
+  State2,
+  State3,
+}
+
+public class Program
 {
-  private static void Main(string[] args)
+  private static async Task Main(string[] args)
+  {
+    await ResultsStateMachine.RunAsync();
+  }
+}
+
+[System.Diagnostics.CodeAnalysis.SuppressMessage("StyleCop.CSharp.MaintainabilityRules", "SA1402:File may only contain a single type", Justification = "Ignore")]
+public class ResultsStateMachine
+{
+  /// <summary>Example asynchronous run method.</summary>
+  /// <returns>Task.</returns>
+  public static async Task RunAsync()
+  {
+    var machine = new StateMachine<StateId>();
+    machine.RegisterState<State1>(StateId.State1, onSuccess: StateId.State1, onError: StateId.State2, onFailure: null, subscriptionTypes: null);
+    machine.RegisterState<State2>(StateId.State2, onSuccess: StateId.State1, onError: null, onFailure: StateId.State3, subscriptionTypes: null);
+    machine.RegisterState<State3>(StateId.State3, subscriptionTypes: null);
+
+    // Async Example!
+    await machine.RunAsync(StateId.State1);
+  }
+
+  public class State1 : IState<StateId>
+  {
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Simulate an Error state transition so we can continue.
+      context.NextState(Result.Error);
+
+      Console.WriteLine($"[State1][OnEnter].OnSuccess goto: '{context.NextStates.OnSuccess}'");
+      Console.WriteLine($"[State1][OnEnter].OnError goto:   '{context.NextStates.OnError}'");
+      Console.WriteLine($"[State1][OnEnter].OnFailure goto: '{context.NextStates.OnFailure}'");
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
+  }
+
+  public class State2 : IState<StateId>
   {
-    Console.WriteLine("Coming Soon!");
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Simulate a Failure state transition so we can continue.
+      context.NextState(Result.Failure);
+
+      Console.WriteLine($"[State2][OnEnter].OnSuccess goto: '{context.NextStates.OnSuccess}'");
+      Console.WriteLine($"[State2][OnEnter].OnError goto:   '{context.NextStates.OnError}'");
+      Console.WriteLine($"[State2][OnEnter].OnFailure goto: '{context.NextStates.OnFailure}'");
+
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
+  }
+
+  public class State3 : IState<StateId>
+  {
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Set Failure so we can continue.
+      context.NextState(Result.Success);
+
+      Console.WriteLine($"[State3][OnEnter].OnSuccess goto: '{context.NextStates.OnSuccess}'");
+      Console.WriteLine($"[State3][OnEnter].OnError goto:   '{context.NextStates.OnError}'");
+      Console.WriteLine($"[State3][OnEnter].OnFailure goto: '{context.NextStates.OnFailure}'");
+
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
   }
 }

samples/Sample04.ResultTransitions/Sample04.ResultTransitions.csproj

@@ -7,4 +7,8 @@
     <Nullable>enable</Nullable>
   </PropertyGroup>
 
+  <ItemGroup>
+    <ProjectReference Include="..\..\source\Lite.StateMachine\Lite.StateMachine.csproj" />
+  </ItemGroup>
+
 </Project>

source/Lite.StateMachine.Tests/StateTests/NextStateResultTests.cs

@@ -0,0 +1,87 @@
+// Copyright Xeno Innovations, Inc. 2026
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Linq;
+using System.Threading.Tasks;
+
+namespace Lite.StateMachine.Tests.StateTests;
+
+[TestClass]
+public class NextStateResultTests : TestBase
+{
+  /// <summary>State definitions.</summary>
+  public enum StateId
+  {
+    State1,
+    State2,
+    State3,
+  }
+
+  [TestMethod]
+  public async Task NextState_Error_Failure__SuccessTestAsync()
+  {
+    var machine = new StateMachine<StateId>();
+    machine.RegisterState<State1>(StateId.State1, onSuccess: StateId.State1, onError: StateId.State2, onFailure: null, subscriptionTypes: null);
+    machine.RegisterState<State2>(StateId.State2, onSuccess: StateId.State1, onError: null, onFailure: StateId.State3, subscriptionTypes: null);
+    machine.RegisterState<State3>(StateId.State3, subscriptionTypes: null);
+
+    // Async Example!
+    await machine.RunAsync(StateId.State1);
+
+    // Assert Results
+    AssertMachineNotNull(machine);
+
+    // Ensure all states are registered
+    var enums = Enum.GetValues<StateId>().Cast<StateId>();
+    Assert.IsNotNull(enums);
+    Assert.HasCount(enums.Count(), machine.States);
+    Assert.IsTrue(enums.All(k => machine.States.Contains(k)));
+  }
+
+  private class State1 : IState<StateId>
+  {
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Simulate an Error state transition so we can continue.
+      context.NextState(Result.Error);
+
+      Console.WriteLine($"[State1][OnEnter].OnSuccess goto: '{context.NextStates.OnSuccess}'");
+      Console.WriteLine($"[State1][OnEnter].OnError goto:   '{context.NextStates.OnError}'");
+      Console.WriteLine($"[State1][OnEnter].OnFailure goto: '{context.NextStates.OnFailure}'");
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
+  }
+
+  private class State2 : IState<StateId>
+  {
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Simulate a Failure state transition so we can continue.
+      context.NextState(Result.Failure);
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
+  }
+
+  private class State3 : IState<StateId>
+  {
+    public Task OnEnter(Context<StateId> context)
+    {
+      // Set Failure so we can continue.
+      context.NextState(Result.Success);
+      return Task.CompletedTask;
+    }
+
+    public Task OnEntering(Context<StateId> context) => Task.CompletedTask;
+
+    public Task OnExit(Context<StateId> context) => Task.CompletedTask;
+  }
+}

source/Lite.StateMachine/Lite.StateMachine.csproj

@@ -21,6 +21,9 @@
     <PackageTags>statemachine;lite;fsm;suesslabs;xeno-innovations</PackageTags>
     <PackageLicenseFile>LICENSE.md</PackageLicenseFile>
     <PackageReleaseNotes>
+      New Features in v2.4:
+      * Added custom State Results (Success, Error, Failure, etc.) and ability to override the default Result.Success/.Error./Failure.
+
       New Features in v2.2:
 
       * New: Renamed, Result.Ok -&gt; Result.Success (Breaking Change).

source/Lite.StateMachine/StateMachine.cs

@@ -133,7 +133,7 @@ public StateMachine<TStateId> RegisterState<TStateClass>(
     IReadOnlyCollection<Type>? subscriptionTypes = null)
     where TStateClass : class, IState<TStateId>
   {
-    return RegisterState<TStateClass>(stateId, onSuccess, onError: null, onFailure: null, parentStateId: null, isCompositeParent: false, initialChildStateId: null, subscriptionTypes: subscriptionTypes);
+    return RegisterState<TStateClass>(stateId, onSuccess, onError: onError, onFailure: onFailure, parentStateId: null, isCompositeParent: false, initialChildStateId: null, subscriptionTypes: subscriptionTypes);
   }
 
   /// <inheritdoc/>