1pub mod config;
76pub mod error;
77pub mod machine;
78pub mod shared;
79pub mod state;
80pub mod transition;
81
82pub use config::StateMachineConfig;
85pub use error::FsmError;
86pub use machine::StateMachine;
87pub use shared::SharedMachine;
88pub use state::State;
89pub use transition::{Transition, TransitionEndpoint, TransitionRecord};
90
91#[cfg(feature = "async")]
92pub use shared::AsyncMachine;
93
94pub mod prelude {
96 #[cfg(feature = "async")]
97 pub use crate::AsyncMachine;
98 pub use crate::{
99 FsmError, SharedMachine, State, StateMachine, StateMachineConfig, Transition,
100 TransitionEndpoint, TransitionRecord,
101 };
102}
103
104#[cfg(test)]
107mod tests {
108 use super::*;
109 use crate::config::DEFAULT_HISTORY_LIMIT;
110
111 #[derive(Debug, Clone, PartialEq, Eq, Hash)]
114 enum TicketState {
115 Received,
116 NeedsMoreInfo,
117 InProgress,
118 Resolved,
119 Closed,
120 Archived,
121 }
122
123 impl State for TicketState {}
124
125 struct Ticket {
126 state: TicketState,
127 history: Vec<TransitionRecord<TicketState>>,
128 }
129
130 impl Ticket {
131 fn new() -> Self {
132 Self {
133 state: TicketState::Received,
134 history: Vec::new(),
135 }
136 }
137 }
138
139 impl StateMachine for Ticket {
140 type State = TicketState;
141
142 fn config() -> StateMachineConfig<TicketState> {
143 StateMachineConfig::new(TicketState::Received)
144 .initial_states(vec![TicketState::Received])
145 .deprecated_states(vec![TicketState::Archived])
146 .transitions(vec![
147 Transition::new("request_info")
148 .from(vec![TicketState::Received, TicketState::InProgress])
149 .to(vec![TicketState::NeedsMoreInfo]),
150 Transition::new("start")
151 .from(vec![TicketState::Received, TicketState::NeedsMoreInfo])
152 .to(vec![TicketState::InProgress]),
153 Transition::new("resolve")
154 .from(vec![TicketState::InProgress])
155 .to(vec![TicketState::Resolved]),
156 Transition::new("close")
158 .from_any()
159 .to(vec![TicketState::Closed]),
160 ])
161 }
162
163 fn current_state(&self) -> &TicketState {
164 &self.state
165 }
166 fn set_state(&mut self, s: TicketState) {
167 self.state = s;
168 }
169 fn history(&self) -> &[TransitionRecord<TicketState>] {
170 &self.history
171 }
172 fn history_mut(&mut self) -> &mut Vec<TransitionRecord<TicketState>> {
173 &mut self.history
174 }
175 }
176
177 #[test]
180 fn valid_transition_succeeds() {
181 let mut t = Ticket::new();
182 t.transition("start", TicketState::InProgress).unwrap();
183 assert_eq!(t.current_state(), &TicketState::InProgress);
184 }
185
186 #[test]
187 fn invalid_transition_returns_error() {
188 let mut t = Ticket::new();
189 let err = t.transition("resolve", TicketState::Resolved);
190 assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
191 assert_eq!(t.current_state(), &TicketState::Received);
193 }
194
195 #[test]
196 fn wildcard_from_allows_close_from_any_state() {
197 let mut t = Ticket::new();
198 t.transition("close", TicketState::Closed).unwrap();
199 assert_eq!(t.current_state(), &TicketState::Closed);
200 }
201
202 #[test]
205 fn history_records_transitions() {
206 let mut t = Ticket::new();
207 t.transition("start", TicketState::InProgress).unwrap();
208 t.transition("resolve", TicketState::Resolved).unwrap();
209
210 assert_eq!(t.history().len(), 2);
211 assert_eq!(t.history()[0].from, TicketState::Received);
212 assert_eq!(t.history()[0].to, TicketState::InProgress);
213 assert_eq!(t.history()[0].action, "start");
214 assert_eq!(t.history()[1].from, TicketState::InProgress);
215 assert_eq!(t.history()[1].to, TicketState::Resolved);
216 }
217
218 #[test]
219 fn history_evicts_oldest_at_limit() {
220 struct TinyMachine {
221 state: TicketState,
222 history: Vec<TransitionRecord<TicketState>>,
223 }
224 impl StateMachine for TinyMachine {
225 type State = TicketState;
226 fn config() -> StateMachineConfig<TicketState> {
227 StateMachineConfig::new(TicketState::Received)
228 .history_limit(2)
229 .transitions(vec![Transition::new("*").from_any().to_any()])
230 }
231 fn current_state(&self) -> &TicketState {
232 &self.state
233 }
234 fn set_state(&mut self, s: TicketState) {
235 self.state = s;
236 }
237 fn history(&self) -> &[TransitionRecord<TicketState>] {
238 &self.history
239 }
240 fn history_mut(&mut self) -> &mut Vec<TransitionRecord<TicketState>> {
241 &mut self.history
242 }
243 }
244
245 let mut m = TinyMachine {
246 state: TicketState::Received,
247 history: Vec::new(),
248 };
249 m.transition("*", TicketState::InProgress).unwrap();
250 m.transition("*", TicketState::Resolved).unwrap();
251 m.transition("*", TicketState::Closed).unwrap(); assert_eq!(m.history().len(), 2);
254 assert_eq!(m.history()[0].from, TicketState::InProgress);
255 }
256
257 #[test]
260 fn validate_initial_state_ok() {
261 let t = Ticket::new();
262 t.validate_initial_state().unwrap();
263 }
264
265 #[test]
266 fn validate_initial_state_err_for_invalid() {
267 let t = Ticket {
268 state: TicketState::Resolved,
269 history: Vec::new(),
270 };
271 let err = t.validate_initial_state();
272 assert!(matches!(err, Err(FsmError::InvalidInitialState { .. })));
273 }
274
275 #[test]
278 fn possible_next_states_from_received() {
279 let t = Ticket::new();
280 let mut next = t.possible_next_states();
281 next.sort_by(|a, b| format!("{a:?}").cmp(&format!("{b:?}")));
282 assert!(next.contains(&TicketState::NeedsMoreInfo));
284 assert!(next.contains(&TicketState::InProgress));
285 assert!(next.contains(&TicketState::Closed));
286 }
287
288 #[test]
289 fn possible_next_states_for_action() {
290 let t = Ticket::new();
291 let next = t.possible_next_states_for_action("close");
292 assert_eq!(next, vec![TicketState::Closed]);
293 }
294
295 #[test]
296 fn can_transition_predicate() {
297 let t = Ticket::new();
298 assert!(t.can_transition("start", &TicketState::InProgress));
299 assert!(!t.can_transition("resolve", &TicketState::Resolved));
300 }
301
302 #[test]
303 fn all_states_includes_deprecated() {
304 let all = Ticket::all_states();
305 assert!(all.contains(&TicketState::Archived));
306 }
307
308 #[test]
309 fn active_states_excludes_deprecated() {
310 let active = Ticket::active_states();
311 assert!(!active.contains(&TicketState::Archived));
312 }
313
314 #[test]
315 fn default_history_limit_is_100() {
316 assert_eq!(DEFAULT_HISTORY_LIMIT, 100);
317 let config = Ticket::config();
318 assert_eq!(config.history_limit, 100);
319 }
320
321 mod shared_tests {
324 use super::*;
325 use crate::shared::SharedMachine;
326 use std::thread;
327
328 fn make_shared() -> SharedMachine<Ticket> {
329 SharedMachine::new(Ticket::new())
330 }
331
332 #[test]
333 fn shared_machine_transitions() {
334 let m = make_shared();
335 m.transition("start", TicketState::InProgress).unwrap();
336 assert_eq!(m.current_state(), TicketState::InProgress);
337 }
338
339 #[test]
340 fn shared_machine_invalid_transition_returns_error() {
341 let m = make_shared();
342 let err = m.transition("resolve", TicketState::Resolved);
343 assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
344 assert_eq!(m.current_state(), TicketState::Received);
345 }
346
347 #[test]
348 fn shared_machine_history_snapshot() {
349 let m = make_shared();
350 m.transition("start", TicketState::InProgress).unwrap();
351 let history = m.history();
352 assert_eq!(history.len(), 1);
353 assert_eq!(history[0].action, "start");
354 }
355
356 #[test]
357 fn shared_machine_send_across_threads() {
358 let m = make_shared();
359 let handle = m.clone();
360 let t = thread::spawn(move || {
361 handle.transition("start", TicketState::InProgress).unwrap();
362 });
363 t.join().unwrap();
364 assert_eq!(m.current_state(), TicketState::InProgress);
365 }
366
367 #[test]
368 fn shared_machine_concurrent_read() {
369 let m = make_shared();
370 m.transition("start", TicketState::InProgress).unwrap();
371
372 let handles: Vec<_> = (0..4)
373 .map(|_| {
374 let clone = m.clone();
375 thread::spawn(move || clone.current_state())
376 })
377 .collect();
378
379 for h in handles {
380 assert_eq!(h.join().unwrap(), TicketState::InProgress);
381 }
382 }
383
384 #[test]
385 fn shared_machine_with_closure() {
386 let m = make_shared();
387 let result = m.with(|inner| {
388 inner.transition("start", TicketState::InProgress).unwrap();
389 inner.history().len()
390 });
391 assert_eq!(result, 1);
392 }
393
394 #[cfg(feature = "async")]
395 mod async_tests {
396 use super::*;
397 use crate::shared::AsyncMachine;
398
399 fn make_async() -> AsyncMachine<Ticket> {
400 AsyncMachine::new(Ticket::new())
401 }
402
403 #[tokio::test]
404 async fn async_machine_transitions() {
405 let m = make_async();
406 m.transition("start", TicketState::InProgress)
407 .await
408 .unwrap();
409 assert_eq!(m.current_state().await, TicketState::InProgress);
410 }
411
412 #[tokio::test]
413 async fn async_machine_invalid_transition() {
414 let m = make_async();
415 let err = m.transition("resolve", TicketState::Resolved).await;
416 assert!(matches!(err, Err(FsmError::NoMatchingTransition { .. })));
417 }
418
419 #[tokio::test]
420 async fn async_machine_history() {
421 let m = make_async();
422 m.transition("start", TicketState::InProgress)
423 .await
424 .unwrap();
425 let hist = m.history().await;
426 assert_eq!(hist.len(), 1);
427 assert_eq!(hist[0].action, "start");
428 }
429
430 #[tokio::test]
431 async fn async_machine_send_across_tasks() {
432 let m = make_async();
433 let handle = m.clone();
434 tokio::spawn(async move {
435 handle
436 .transition("start", TicketState::InProgress)
437 .await
438 .unwrap();
439 })
440 .await
441 .unwrap();
442 assert_eq!(m.current_state().await, TicketState::InProgress);
443 }
444
445 #[tokio::test]
446 async fn async_machine_with_closure() {
447 let m = make_async();
448 let result = m
449 .with(|inner| {
450 inner.transition("start", TicketState::InProgress).unwrap();
451 inner.history().len()
452 })
453 .await;
454 assert_eq!(result, 1);
455 }
456 }
457 }
458
459 #[cfg(feature = "serde")]
460 mod serde_tests {
461 use super::*;
462
463 #[derive(Debug, Clone, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
464 enum SimpleState {
465 A,
466 B,
467 C,
468 }
469 impl State for SimpleState {}
470
471 struct SimpleMachine {
472 state: SimpleState,
473 history: Vec<TransitionRecord<SimpleState>>,
474 }
475 impl StateMachine for SimpleMachine {
476 type State = SimpleState;
477 fn config() -> StateMachineConfig<SimpleState> {
478 StateMachineConfig::new(SimpleState::A).transitions(vec![
479 Transition::new("go")
480 .from(vec![SimpleState::A])
481 .to(vec![SimpleState::B]),
482 Transition::new("go")
483 .from(vec![SimpleState::B])
484 .to(vec![SimpleState::C]),
485 ])
486 }
487 fn current_state(&self) -> &SimpleState {
488 &self.state
489 }
490 fn set_state(&mut self, s: SimpleState) {
491 self.state = s;
492 }
493 fn history(&self) -> &[TransitionRecord<SimpleState>] {
494 &self.history
495 }
496 fn history_mut(&mut self) -> &mut Vec<TransitionRecord<SimpleState>> {
497 &mut self.history
498 }
499 }
500
501 #[test]
502 fn history_serializes_and_deserializes() {
503 let mut m = SimpleMachine {
504 state: SimpleState::A,
505 history: Vec::new(),
506 };
507 m.transition("go", SimpleState::B).unwrap();
508 m.transition("go", SimpleState::C).unwrap();
509
510 let json = m.serialize_history().unwrap();
511 assert!(json.contains("\"from\":\"A\""));
512
513 let mut m2 = SimpleMachine {
514 state: SimpleState::C,
515 history: Vec::new(),
516 };
517 m2.deserialize_history(&json).unwrap();
518 assert_eq!(m2.history().len(), 2);
519 assert_eq!(m2.history()[0].from, SimpleState::A);
520 assert_eq!(m2.history()[1].from, SimpleState::B);
521 }
522
523 #[test]
524 fn config_serializes() {
525 let config = SimpleMachine::config();
526 let json = serde_json::to_string(&config).unwrap();
527 assert!(json.contains("initial_states"));
528 assert!(json.contains("transitions"));
529 }
530 }
531}