statum/lib.rs
1//! Statum provides ergonomic typestate-builder and lifecycle APIs in Rust.
2//!
3//! It builds on finite-state modeling and validates legal transitions at compile time.
4//! The main macros are:
5//!
6//! - [`state`](macro@state) for defining lifecycle states.
7//! - [`machine`](macro@machine) for defining the state-carrying machine/builder.
8//! - [`transition`](macro@transition) for validating transition impl signatures.
9//! - [`validators`](macro@validators) for rehydrating typed machines from persisted data.
10//!
11//! # Quick Example
12//!
13//! ```
14//! use statum::{machine, state, transition};
15//!
16//! #[state]
17//! enum CheckoutState {
18//! EmptyCart,
19//! ReadyToPay(OrderDraft),
20//! Paid,
21//! }
22//!
23//! #[derive(Clone)]
24//! struct OrderDraft {
25//! total_cents: u64,
26//! }
27//!
28//! #[machine]
29//! struct Checkout<CheckoutState> {
30//! id: String,
31//! }
32//!
33//! #[transition]
34//! impl Checkout<EmptyCart> {
35//! fn review(self, total_cents: u64) -> Checkout<ReadyToPay> {
36//! self.transition_with(OrderDraft { total_cents })
37//! }
38//! }
39//!
40//! #[transition]
41//! impl Checkout<ReadyToPay> {
42//! fn pay(self) -> Checkout<Paid> {
43//! self.transition()
44//! }
45//! }
46//!
47//! fn main() {
48//! let cart = Checkout::<EmptyCart>::builder()
49//! .id("order-1".to_owned())
50//! .build();
51//!
52//! let ready = cart.review(4200);
53//! assert_eq!(ready.state_data.total_cents, 4200);
54//!
55//! let _paid = ready.pay();
56//! }
57//! ```
58//!
59//! # Compile-Time Gating
60//!
61//! Methods only exist on states where you define them.
62//!
63//! ```compile_fail
64//! use statum::{machine, state};
65//!
66//! #[state]
67//! enum LightState {
68//! Off,
69//! On,
70//! }
71//!
72//! #[machine]
73//! struct Light<LightState> {}
74//!
75//! fn main() {
76//! let light = Light::<Off>::builder().build();
77//! let _ = light.switch_off(); // no such method on Light<Off>
78//! }
79//! ```
80
81pub use bon;
82pub use statum_core::*;
83pub use statum_macros::*;