Expand description
§ash-fsm
A configurable, trait-based finite state machine library for Rust, inspired by AshStateMachine.
§Design
- Traits first — define your machine by implementing
StateMachineon any struct. The trait provides all transition logic as default methods. - Declarative transitions — describe allowed
(action, from → to)triples inStateMachineConfig. Wildcards (*) cover any action or any state. - History — every successful transition is recorded as a
TransitionRecordin a bounded ring buffer (default 100 entries, configurable per machine). - Serialization — the
serdefeature (on by default) lets you round-trip history and config through any serde-compatible format.
§Quick start
use ash_fsm::{State, StateMachine};
use ash_fsm::config::StateMachineConfig;
use ash_fsm::transition::{Transition, TransitionRecord};
// 1. Define your state enum.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
enum OrderState { Pending, Active, Shipped, Closed }
impl State for OrderState {}
// 2. Define your domain struct.
struct Order {
state: OrderState,
history: Vec<TransitionRecord<OrderState>>,
}
// 3. Implement the trait.
impl StateMachine for Order {
type State = OrderState;
fn config() -> StateMachineConfig<OrderState> {
StateMachineConfig::new(OrderState::Pending)
.transitions(vec![
Transition::new("activate")
.from(vec![OrderState::Pending])
.to(vec![OrderState::Active]),
Transition::new("ship")
.from(vec![OrderState::Active])
.to(vec![OrderState::Shipped]),
// Close is allowed from any state.
Transition::new("close")
.from_any()
.to(vec![OrderState::Closed]),
])
}
fn current_state(&self) -> &OrderState { &self.state }
fn set_state(&mut self, s: OrderState) { self.state = s; }
fn history(&self) -> &[TransitionRecord<OrderState>] { &self.history }
fn history_mut(&mut self) -> &mut Vec<TransitionRecord<OrderState>> { &mut self.history }
}
// 4. Use it.
let mut order = Order { state: OrderState::Pending, history: Vec::new() };
order.validate_initial_state().unwrap();
order.transition("activate", OrderState::Active).unwrap();
order.transition("ship", OrderState::Shipped).unwrap();
assert_eq!(order.history().len(), 2);
assert_eq!(order.current_state(), &OrderState::Shipped);
// Invalid transition returns an error and leaves state unchanged.
let err = order.transition("activate", OrderState::Active);
assert!(err.is_err());Re-exports§
pub use config::StateMachineConfig;pub use error::FsmError;pub use machine::StateMachine;pub use state::State;pub use transition::Transition;pub use transition::TransitionEndpoint;pub use transition::TransitionRecord;