Skip to main content

Crate ash_fsm

Crate ash_fsm 

Source
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 StateMachine on any struct. The trait provides all transition logic as default methods.
  • Declarative transitions — describe allowed (action, from → to) triples in StateMachineConfig. Wildcards (*) cover any action or any state.
  • History — every successful transition is recorded as a TransitionRecord in a bounded ring buffer (default 100 entries, configurable per machine).
  • Serialization — the serde feature (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 shared::SharedMachine;
pub use state::State;
pub use transition::Transition;
pub use transition::TransitionEndpoint;
pub use transition::TransitionRecord;

Modules§

config
error
machine
prelude
Convenient glob import: use ash_fsm::prelude::*;
shared
Thread-safe handles to a state machine.
state
transition