Optima.Net.StateMachines 3.0.0

Optima.Net.StateMachines

Optima.Net.StateMachines is a lightweight, declarative, and idempotent state machine framework for .NET 8 and later.

It models event-driven lifecycles in a passive and deterministic way:

• transitions are declared as data
• undefined transitions are ignored
• applying the same event multiple times yields the same state

This package is domain-agnostic and contains no persistence, infrastructure, or orchestration code.

Overview

Core principles:

• Declarative configuration (event → from → to)
• Passive semantics (undefined transitions are ignored)
• Idempotent operations
• Deterministic evaluation
• Stateless by default
• Extensible token model (no enums)
• Explicit, type-safe aggregation (major version change)

IMPORTANT: Aggregation Model (Major Version Change)

Aggregation was redesigned in a major release.

Aggregation no longer operates on raw StateToken values.

Instead, aggregation is explicit and type-safe:

• Machines must explicitly opt in to aggregation
• State access is decoupled from state ownership
• Aggregators work with stateless and stateful machines
• Aggregation eligibility is enforced by the type system

Key abstractions:

• IAggregatableStateMachine � permission to participate in aggregation
• IStateProvider � access to a state value
• IStateAggregator � authority that derives aggregate meaning

PART A: STATELESS STATE MACHINES (CALCULATOR MODEL)

Stateless state machines do not track internal state. They calculate a next state when given a transition and a current state.

This model is ideal when:

• state is persisted externally
• workflows are event-sourced
• replay and rehydration are required
• machines must remain pure and side-effect free

PART B: STATEFUL STATE MACHINE INSTANCES (NEW IN 3.0.0)

In addition to stateless machines, Optima.Net.StateMachines now supports stateful state machine instances.

A stateful machine instance:

• owns its current state
• applies transitions directly
• exposes its state via IStateProvider
• can participate in aggregation without adapters

1. Define a Stateful Machine Instance

public sealed class OrderStateMachineInstance :
    IAggregatableStateMachine,
    IStateProvider
{
    private readonly OrderStateMachine _machine;

    public OrderState CurrentState { get; private set; }

    public OrderStateMachineInstance(OrderState initialState)
    {
        _machine = new OrderStateMachine();
        CurrentState = initialState;
    }

    public void Apply(OrderTransition transition)
    {
        CurrentState = _machine.Apply(transition, CurrentState);
    }

    public StateToken GetCurrentState()
        => CurrentState;
}

2. Using a Stateful Machine in Application Code

var order = new OrderStateMachineInstance(OrderState.New);

order.Apply(OrderTransition.Create);
order.Apply(OrderTransition.Pay);
order.Apply(OrderTransition.Ship);

Console.WriteLine(order.CurrentState);

3. Aggregating Stateful Machine Instances

var order = new OrderStateMachineInstance(OrderState.New);
var billing = new BillingStateMachineInstance(BillingState.New);
var shipping = new ShippingStateMachineInstance(ShippingState.New);

var aggregator = new OrderAggregator();

order.Apply(OrderTransition.Create);
billing.Apply(BillingTransition.Authorize);
shipping.Apply(ShippingTransition.PrepareShipping);

var aggregateStatus = aggregator.Evaluate(
[
    (order, order),
    (billing, billing),
    (shipping, shipping)
]);

Console.WriteLine(aggregateStatus.Code);

Choosing Between Stateless and Stateful Models

Stateless machines:

• simpler
• easier to persist
• ideal for event sourcing

Stateful machines:

• encapsulate state
• easier imperative usage
• integrate directly with aggregation

Public API Summary

StateToken � symbolic extensible value for states and events TransitionToken � symbolic extensible value for transitions StateMachine<TState, TTransition> � passive stateless machine IAggregatableStateMachine � opt-in marker for aggregation IStateProvider � exposes state value IStateAggregator � aggregation authority StateAggregator � base class for aggregators AggregateStatus � aggregate-level outcome

License

MIT License (c) 2026 Optima Software